> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiusd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading API overview

> How TIM (Trading Intent Model) powers trading execution across chains and venues.

## What is TIM

The Trading API is built on TIM (Trading Intent Model) — a protocol for expressing trading strategies as structured intents. You submit an intent, and TIM validates it, resolves tokens, and executes the trade on-chain.

A single tool call (`execute_intent`) covers all trading operations: immediate swaps, event-triggered rules, exit strategies, and position management.

## Intent types

TIM supports three intent types:

| Type                | Behavior                                                          |
| ------------------- | ----------------------------------------------------------------- |
| `IMMEDIATE`         | Execute an on-chain swap now                                      |
| `CONDITIONAL_ENTRY` | Register an event-triggered rule that fires when conditions match |
| `CLOSE_POSITION`    | Close an existing position by `position_id`                       |

`IMMEDIATE` intents execute and return a transaction hash. `CONDITIONAL_ENTRY` intents register a rule and return a `rule_id` — the rule stays active and triggers on each matching event until cancelled. `CLOSE_POSITION` cancels exit orders and returns realized PnL.

## Supported chains

TIM uses [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) chain identifiers:

| Chain    | CAIP-2 ID             |
| -------- | --------------------- |
| Solana   | `solana:mainnet-beta` |
| Ethereum | `eip155:1`            |
| BSC      | `eip155:56`           |
| Base     | `eip155:8453`         |
| Arbitrum | `eip155:42161`        |

## Supported DEXes

**Solana:** Jupiter, Raydium, PumpFun, Orca, Meteora DLMM, Bonk Launchpad

**EVM (via RelayerRouter):** Uniswap, Aerodrome, Sushiswap

TIM selects the best route automatically based on liquidity and price impact.

## Exit strategies

You can attach take-profit and stop-loss conditions to any `IMMEDIATE` buy intent:

* `profit_percent` — sell when PnL reaches +X%
* `loss_percent` — sell when PnL reaches -X%
* Combine with `OR` logic (either condition triggers) or `AND` logic (both must be true)

When an exit strategy is configured, TIM creates a tracked position and monitors it until an exit condition fires or you close it manually.

## Token resolution

TIM has built-in symbol-to-address resolution. You do not need to look up contract addresses before submitting intents:

1. If you provide a contract address, TIM uses it directly
2. For common tokens (SOL, USDC, USDT, ETH, BNB), TIM uses known addresses
3. For other tokens, provide the symbol and TIM resolves it

You can also use the [`GET /api/v1/tokens/resolve`](/trading-api/api#get-apiv1tokensresolve) endpoint to resolve tokens explicitly.

## AIUSD integration

TIM connects to the AIUSD ledger for funding. When you trade using your AIUSD balance, the platform moves funds from the ledger into your trading account before execution. See the [architecture page](/architecture) for how this flow works.

<Note>
  AIUSD can only be converted to stablecoins (USDC, USDT, USD1). To buy non-stablecoins with AIUSD, first convert AIUSD to USDC, then swap USDC for the target token.
</Note>

## How it fits together

```mermaid theme={null}
flowchart LR
    U[User or AI agent] --> MCP[MCP Hub]
    U --> HTTP[HTTP API]
    MCP --> TIM[TIM]
    HTTP --> TIM
    TIM --> SOL[Solana DEXes]
    TIM --> EVM[EVM DEXes]
```

You can reach TIM through two paths:

* **MCP Hub** — call `genalpha_tim_execute_intent` via the [MCP Hub API](/api). Best for AI agents using MCP tool calling.
* **HTTP API** — call `POST /api/v1/execute-intent` directly. Best for custom integrations and programmatic access.

Both paths accept the same XML intent format and return the same response structure.

## Next steps

<CardGroup cols={2}>
  <Card title="Intent format" icon="code" href="/trading-api/intent-format">
    XML schema, intent types, buy/sell semantics, and examples
  </Card>

  <Card title="HTTP API reference" icon="server" href="/trading-api/api">
    Endpoints, authentication, request/response schemas
  </Card>
</CardGroup>