> ## 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.

# HTTP API reference

> TIM HTTP API endpoints, authentication, and request/response schemas.

## Base URL

| Environment | URL                            |
| ----------- | ------------------------------ |
| Production  | `https://api.alpha.dev/api/v1` |
| Development | `https://dev.alpha.dev/api/v1` |

## Authentication

All endpoints except health check and internal cluster endpoints require a JWT Bearer token:

```
Authorization: Bearer <jwt_token>
```

<Note>
  Contact support for API access credentials.
</Note>

## Endpoints

| Method | Path                       | Description                          | Auth |
| ------ | -------------------------- | ------------------------------------ | ---- |
| POST   | `/api/v1/execute-intent`   | Execute or register a trading intent | Yes  |
| POST   | `/api/v1/normalize-intent` | Normalize intent for auto-approval   | Yes  |
| POST   | `/api/v1/trades/simulate`  | Simulate a trade without execution   | No   |
| GET    | `/api/v1/tokens/resolve`   | Resolve token symbols to addresses   | No   |
| GET    | `/api/v1/transactions`     | Transaction history                  | Yes  |

***

## POST `/api/v1/execute-intent`

Execute an on-chain swap, register a conditional rule, or close a position.

### Request

```json theme={null}
{
  "intent": "<intent><type>IMMEDIATE</type><chain_id>solana:mainnet-beta</chain_id>...</intent>"
}
```

| Field    | Type   | Required | Description                                                                |
| -------- | ------ | -------- | -------------------------------------------------------------------------- |
| `intent` | string | Yes      | TIM intent as XML string. See [intent format](/trading-api/intent-format). |

### Response

```json theme={null}
{
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "transaction_hash": "5UfD...",
  "status": "EXECUTION_STATUS_CONFIRMED",
  "details": "Swap executed successfully",
  "system_message": "...",
  "position_id": "pos_abc123",
  "exit_orders": {
    "take_profit_order_id": "ord_tp_1",
    "stop_loss_order_id": "ord_sl_1"
  },
  "rule_id": null,
  "wait_hint": {
    "type": "transaction",
    "tx_hash": "5UfD...",
    "chain_id": "solana:mainnet-beta",
    "commitment": "finalized",
    "poll_interval_ms": 2000,
    "timeout_ms": 60000,
    "system_message": "..."
  }
}
```

| Field              | Type           | Description                                                                   |
| ------------------ | -------------- | ----------------------------------------------------------------------------- |
| `intent_id`        | string         | Unique identifier for this intent                                             |
| `transaction_hash` | string or null | Blockchain transaction hash. Present for `IMMEDIATE` swaps, absent for rules. |
| `status`           | string         | Execution status (see below)                                                  |
| `details`          | string         | Human-readable status message                                                 |
| `system_message`   | string         | Message with balance verification and block explorer link                     |
| `position_id`      | string or null | Position ID if exit strategy was configured or for `CLOSE_POSITION`           |
| `exit_orders`      | object or null | Take-profit and stop-loss order IDs                                           |
| `rule_id`          | string or null | Rule ID for `CONDITIONAL_ENTRY` intents                                       |
| `cancelled_orders` | array or null  | Cancelled order IDs (for `CLOSE_POSITION`)                                    |
| `realized_pnl`     | object or null | Realized PnL with `pnl_percent` and `pnl_usd` (for `CLOSE_POSITION`)          |
| `prerequisite`     | object or null | Prerequisite action required before execution (e.g., funding)                 |
| `continuation`     | object or null | Follow-up intent to execute after prerequisite completes                      |
| `wait_hint`        | object or null | Polling hint for transaction confirmation                                     |

### Execution status values

| Status                       | Meaning                                         |
| ---------------------------- | ----------------------------------------------- |
| `EXECUTION_STATUS_PENDING`   | Transaction submitted, awaiting confirmation    |
| `EXECUTION_STATUS_CONFIRMED` | Transaction confirmed on-chain                  |
| `EXECUTION_STATUS_FAILED`    | Execution failed                                |
| `EXECUTION_STATUS_CANCELLED` | Intent was cancelled                            |
| `FUNDING_REQUIRED`           | Insufficient funds — check `prerequisite` field |

***

## POST `/api/v1/normalize-intent`

Parse and enrich an intent XML with resolved token addresses and USD values. Use this to preview what TIM will execute before submitting.

### Request

```json theme={null}
{
  "intent": "<intent>...</intent>"
}
```

### Response

```json theme={null}
{
  "intent": "{\"type\":\"IMMEDIATE\",\"chain_id\":\"solana:mainnet-beta\",...}"
}
```

The response `intent` field contains the normalized intent as a JSON string with resolved addresses and computed values.

***

## POST `/api/v1/trades/simulate`

Simulate a trade to check token liquidity and price impact without executing.

### Request

```json theme={null}
{
  "chain_id": "eip155:1",
  "token_address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "amount_usd": 1000
}
```

| Field           | Type   | Required | Description                     |
| --------------- | ------ | -------- | ------------------------------- |
| `chain_id`      | string | Yes      | CAIP-2 chain identifier         |
| `token_address` | string | Yes      | Token contract/mint address     |
| `amount_usd`    | number | Yes      | Trade size in USD (must be > 0) |

### Response (success)

```json theme={null}
{
  "success": true,
  "chain_id": "eip155:1",
  "token_address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "quote_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "amount_usd": 1000.0,
  "expected_output": "15131564379480771843325952",
  "price_impact_bps": 0,
  "simulated_at": "2026-01-07T20:14:54.715394844+00:00"
}
```

### Response (failure)

```json theme={null}
{
  "success": false,
  "chain_id": "eip155:1",
  "token_address": "0x...",
  "quote_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "amount_usd": 1000.0,
  "error_code": "insufficient_liquidity",
  "error_message": "Token has insufficient liquidity for requested amount",
  "simulated_at": "2026-01-07T20:14:54.715394844+00:00"
}
```

| Field              | Type           | Description                                   |
| ------------------ | -------------- | --------------------------------------------- |
| `success`          | boolean        | Whether the simulation succeeded              |
| `quote_token`      | string         | Quote token used (chain's default stablecoin) |
| `expected_output`  | string or null | Expected token output in smallest units       |
| `price_impact_bps` | number or null | Price impact in basis points (50 = 0.5%)      |
| `error_code`       | string or null | Error code if simulation failed               |
| `error_message`    | string or null | Error description if simulation failed        |
| `simulated_at`     | string         | ISO 8601 timestamp                            |

### Simulation error codes

| Code                     | Description                    | Retryable |
| ------------------------ | ------------------------------ | --------- |
| `insufficient_liquidity` | Liquidity below threshold      | Yes       |
| `token_not_found`        | Token not found on chain       | No        |
| `no_route_found`         | No swap route available        | Yes       |
| `high_price_impact`      | Price impact exceeds threshold | Yes       |
| `simulation_failed`      | RPC or aggregator error        | Yes       |

***

## GET `/api/v1/tokens/resolve`

Resolve a token symbol to contract addresses across chains.

### Query parameters

| Parameter   | Required | Description                                                          |
| ----------- | -------- | -------------------------------------------------------------------- |
| `query`     | Yes      | Token symbol to resolve (e.g., `USDC`, `SOL`)                        |
| `chain_ids` | No       | Comma-separated CAIP-2 chain IDs. Defaults to all configured chains. |

### Response

```json theme={null}
{
  "query": "USDC",
  "results": [
    {
      "chain_id": "solana:mainnet-beta",
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    }
  ],
  "errors": [
    {
      "chain_id": "eip155:56",
      "code": "TOKEN_NOT_FOUND",
      "message": "Token not found on chain"
    }
  ]
}
```

| Field                | Type   | Description                                 |
| -------------------- | ------ | ------------------------------------------- |
| `results[].chain_id` | string | CAIP-2 chain identifier                     |
| `results[].address`  | string | Token contract address                      |
| `results[].symbol`   | string | Token symbol                                |
| `results[].name`     | string | Token display name                          |
| `results[].decimals` | number | Token decimal places                        |
| `errors[].chain_id`  | string | Chain where resolution failed               |
| `errors[].code`      | string | Error code (`TOKEN_NOT_FOUND`, `API_ERROR`) |
| `errors[].message`   | string | Error description                           |

***

## GET `/api/v1/transactions`

List transaction history for the authenticated user.

### Query parameters

| Parameter        | Required | Default               | Description                              |
| ---------------- | -------- | --------------------- | ---------------------------------------- |
| `chain_id`       | No       | `solana:mainnet-beta` | Chain to query                           |
| `correlation_id` | No       | —                     | Filter by correlation ID                 |
| `context_query`  | No       | —                     | Filter by context label                  |
| `result_code`    | No       | —                     | Filter by result codes (comma-separated) |
| `page`           | No       | `0`                   | Page number (0-indexed)                  |
| `limit`          | No       | `20`                  | Items per page (max 100)                 |

***

## Error format

All errors follow this structure:

```json theme={null}
{
  "error": {
    "code": "INVALID_INTENT",
    "message": "Failed to parse intent XML",
    "details": { ... }
  }
}
```

### Common error codes

| Code                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `INVALID_INTENT`                | Malformed or invalid intent XML    |
| `TOKEN_NOT_FOUND`               | Token symbol could not be resolved |
| `TXN_FAILED`                    | Transaction execution failed       |
| `TRANSACTION_SIGNING_FAILED`    | Signing operation failed           |
| `TRANSACTION_SUBMISSION_FAILED` | Blockchain submission failed       |
| `INVALID_CHAIN_ID`              | Chain ID not configured            |
| `INVALID_AMOUNT`                | Amount must be a positive number   |

## MCP Hub alternative

`MCP Hub` wraps TIM with the same capabilities via MCP tool calling. If you are building an AI agent that supports MCP, you can use `genalpha_tim_execute_intent` through the [MCP Hub API](/api) instead of calling the HTTP API directly. Both accept the same intent format and return equivalent responses.