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\",...}"
}
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) |
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.
