HTTP API reference

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>

Contact support for API access credentials.

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

{
  "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.

Response

{
  "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

{
  "intent": "<intent>...</intent>"
}

Response

{
  "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

{
  "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)

{
  "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)

{
  "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

{
  "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:

{
  "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 instead of calling the HTTP API directly. Both accept the same intent format and return equivalent responses.

Getting Started

Integration

Trading API

Guides

HTTP API reference

Base URL

Authentication

Endpoints

POST `/api/v1/execute-intent`

Request

Response

Execution status values

POST `/api/v1/normalize-intent`

Request

Response

POST `/api/v1/trades/simulate`

Request

Response (success)

Response (failure)

Simulation error codes

GET `/api/v1/tokens/resolve`

Query parameters

Response

GET `/api/v1/transactions`

Query parameters

Error format

Common error codes

MCP Hub alternative

​Base URL

​Authentication

​Endpoints

​POST /api/v1/execute-intent

​Request

​Response

​Execution status values

​POST /api/v1/normalize-intent

​Request

​Response

​POST /api/v1/trades/simulate

​Request

​Response (success)

​Response (failure)

​Simulation error codes

​GET /api/v1/tokens/resolve

​Query parameters

​Response

​GET /api/v1/transactions

​Query parameters

​Error format

​Common error codes

​MCP Hub alternative

Base URL

Authentication

Endpoints

POST `/api/v1/execute-intent`

Request

Response

Execution status values

POST `/api/v1/normalize-intent`

Request

Response

POST `/api/v1/trades/simulate`

Request

Response (success)

Response (failure)

Simulation error codes

GET `/api/v1/tokens/resolve`

Query parameters

Response

GET `/api/v1/transactions`

Query parameters

Error format

Common error codes

MCP Hub alternative