001/

API Documentation

Everything you need to integrate ANIMA Trade into your AI agent. Trade crypto swaps on Base and US equities through a single, unified API.

Quick start: Register an agent, get your API key, and start trading in under 30 seconds.

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header with every request.

Example Header 
X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Do not share it publicly or commit it to version control. If compromised, generate a new key immediately from the dashboard.

Base URL

All API endpoints are relative to the following base URL:

Production 
https://anima.trade
002/

Agents

POST /v1/agents/register

Register a new agent and receive an API key. This is the only endpoint that doesn't require authentication.

Request Body
Parameter Type Description
nameoptional string Human-readable name for your agent (defaults to "Unnamed Agent")
Request 
curl -X POST "https://anima.trade/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trading Bot Alpha"
  }'
Response 
{
  "success": true,
  "agent": {
    "id": "ag_abc123def456",
    "name": "Trading Bot Alpha",
    "apiKey": "ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "createdAt": "2026-02-02T04:50:00Z"
  }
}

Save your API key immediately. It will only be shown once during registration.

GET /v1/agents/me

Retrieve information about the authenticated agent, including account status and usage statistics.

Request 
curl -X GET "https://anima.trade/v1/agents/me" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "agent": {
    "id": "ag_abc123def456",
    "name": "Trading Bot Alpha",
    "createdAt": "2026-02-02T04:50:00Z",
    "totalTrades": 142,
    "totalVolume": "25430.50"
  }
}
003/

Stocks

GET /v1/stocks/quote

Get real-time quote data for a stock symbol, including bid, ask, and last trade prices.

Query Parameters
Parameter Type Description
symbolrequired string Stock ticker symbol (e.g., AAPL, TSLA, NVDA)
Request 
curl -X GET "https://anima.trade/v1/stocks/quote?symbol=AAPL" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "quote": {
    "bidPrice": "247.26",
    "bidSize": 200,
    "askPrice": "247.30",
    "askSize": 100,
    "lastPrice": "247.28",
    "lastSize": 50,
    "timestamp": "2026-02-02T04:50:00Z"
  }
}
GET /v1/stocks/account

Retrieve your trading account information including cash balance, buying power, and portfolio value.

Request 
curl -X GET "https://anima.trade/v1/stocks/account" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "account": {
    "id": "acct_xxxxxxxxxx",
    "status": "ACTIVE",
    "currency": "USD",
    "cash": "10000.00",
    "buyingPower": "40000.00",
    "portfolioValue": "15430.50",
    "equity": "15430.50",
    "lastEquity": "15200.00",
    "daytradeCount": 2,
    "tradingBlocked": false
  }
}
GET /v1/stocks/positions

List all open positions in your portfolio with current market values and unrealized P&L.

Request 
curl -X GET "https://anima.trade/v1/stocks/positions" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "positions": [
    {
      "symbol": "AAPL",
      "qty": "10",
      "avgEntryPrice": "240.00",
      "marketValue": "2472.80",
      "currentPrice": "247.28",
      "unrealizedPL": "72.80",
      "unrealizedPLPercent": "3.03",
      "side": "long"
    },
    {
      "symbol": "NVDA",
      "qty": "5",
      "avgEntryPrice": "890.00",
      "marketValue": "4625.00",
      "currentPrice": "925.00",
      "unrealizedPL": "175.00",
      "unrealizedPLPercent": "3.93",
      "side": "long"
    }
  ]
}
GET /v1/stocks/orders

Retrieve your order history including open, filled, and cancelled orders.

Query Parameters
Parameter Type Description
statusoptional string Filter by status: open, closed, all (default: all)
limitoptional integer Number of orders to return (default: 50, max: 500)
Request 
curl -X GET "https://anima.trade/v1/stocks/orders?status=all&limit=10" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "orders": [
    {
      "id": "ord_abc123",
      "symbol": "AAPL",
      "qty": "10",
      "filledQty": "10",
      "side": "buy",
      "type": "market",
      "status": "filled",
      "filledAvgPrice": "240.00",
      "createdAt": "2026-02-01T10:30:00Z",
      "filledAt": "2026-02-01T10:30:01Z"
    }
  ]
}
POST /v1/stocks/order

Submit a new stock order. Supports market and limit orders for buying and selling.

Request Body
Parameter Type Description
symbolrequired string Stock ticker symbol
qtyrequired number Number of shares to trade
siderequired string Order side: buy or sell
typerequired string Order type: market or limit
limitPriceconditional string Required for limit orders. The maximum price for buys or minimum for sells.
timeInForceoptional string Order duration: day (default), gtc, ioc, fok
Request — Market Order 
curl -X POST "https://anima.trade/v1/stocks/order" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "qty": 10,
    "side": "buy",
    "type": "market"
  }'
Request — Limit Order 
curl -X POST "https://anima.trade/v1/stocks/order" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "NVDA",
    "qty": 5,
    "side": "buy",
    "type": "limit",
    "limitPrice": "900.00",
    "timeInForce": "gtc"
  }'
Response 
{
  "success": true,
  "order": {
    "id": "ord_xyz789",
    "symbol": "AAPL",
    "qty": "10",
    "side": "buy",
    "type": "market",
    "status": "accepted",
    "createdAt": "2026-02-02T04:50:00Z"
  }
}
004/

Crypto

GET /v1/quote

Get a swap quote for trading tokens on Base chain. Returns the expected output amount and price impact.

Query Parameters
Parameter Type Description
sellTokenrequired string Token address or symbol to sell (e.g., ETH, USDC)
buyTokenrequired string Token address or symbol to buy
sellAmountrequired string Amount to sell in base units (wei for ETH)
Request 
curl -X GET "https://anima.trade/v1/quote?sellToken=ETH&buyToken=USDC&sellAmount=1000000000000000000" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "quote": {
    "sellToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "buyToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "sellAmount": "1000000000000000000",
    "buyAmount": "3250000000",
    "price": "3250.00",
    "priceImpact": "0.05",
    "estimatedGas": "180000",
    "sources": [
      {"name": "Uniswap_V3", "proportion": "0.8"},
      {"name": "Aerodrome", "proportion": "0.2"}
    ]
  }
}
POST /v1/swap

Execute a token swap on Base chain. The swap is routed through 0x Protocol for best execution.

Request Body
Parameter Type Description
sellTokenrequired string Token address or symbol to sell
buyTokenrequired string Token address or symbol to buy
sellAmountrequired string Amount to sell in base units
slippagePercentageoptional string Max slippage tolerance (default: 0.01 = 1%)
Request 
curl -X POST "https://anima.trade/v1/swap" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "ETH",
    "buyToken": "USDC",
    "sellAmount": "1000000000000000000",
    "slippagePercentage": "0.005"
  }'
Response 
{
  "success": true,
  "swap": {
    "transactionHash": "0xabc123...",
    "sellToken": "ETH",
    "buyToken": "USDC",
    "sellAmount": "1000000000000000000",
    "buyAmount": "3248500000",
    "executedPrice": "3248.50",
    "fee": "6.50",
    "gasUsed": "175000",
    "status": "confirmed"
  }
}
GET /v1/tokens

List supported tokens on Base chain with their addresses, symbols, and decimals.

Request 
curl -X GET "https://anima.trade/v1/tokens" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 
{
  "success": true,
  "tokens": [
    {
      "symbol": "ETH",
      "name": "Ethereum",
      "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "decimals": 18
    },
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6
    },
    {
      "symbol": "WETH",
      "name": "Wrapped Ether",
      "address": "0x4200000000000000000000000000000000000006",
      "decimals": 18
    }
  ]
}
005/

Prediction Markets

Access real-time prediction market data from Polymarket. Get probabilities on future events across politics, crypto, sports, and more.

GET /v1/predictions/trending

Get the highest-volume prediction markets currently active on Polymarket.

Query Parameters
Parameter Type Description
limitoptional integer Number of markets to return (default: 10, max: 50)
Request 
curl -X GET "https://anima.trade/v1/predictions/trending?limit=5" \
  -H "X-API-Key: your_api_key"
Response 
{
  "markets": [
    {
      "id": "0x1234...",
      "question": "Will Bitcoin reach $100k in 2026?",
      "outcomes": [
        {"name": "Yes", "probability": 67.5},
        {"name": "No", "probability": 32.5}
      ],
      "volume": "$2.4M",
      "endDate": "2026-12-31T00:00:00Z",
      "category": "Crypto"
    }
  ]
}
GET /v1/predictions/search

Search for prediction markets by keyword.

Query Parameters
Parameter Type Description
qrequired string Search query (e.g., "bitcoin", "election", "fed")
limitoptional integer Number of results (default: 20, max: 50)
Request 
curl -X GET "https://anima.trade/v1/predictions/search?q=bitcoin&limit=5" \
  -H "X-API-Key: your_api_key"
Response 
{
  "query": "bitcoin",
  "count": 5,
  "markets": [
    {
      "id": "0xabcd...",
      "question": "Will Bitcoin ETF see net inflows in February?",
      "outcomes": [
        {"name": "Yes", "probability": 82.3},
        {"name": "No", "probability": 17.7}
      ],
      "volume": "$890.5K",
      "endDate": "2026-02-28T00:00:00Z"
    }
  ]
}
GET /v1/predictions/:marketId

Get detailed information about a specific prediction market.

Path Parameters
Parameter Type Description
marketIdrequired string The unique market identifier
Request 
curl -X GET "https://anima.trade/v1/predictions/0x1234abcd" \
  -H "X-API-Key: your_api_key"
Response 
{
  "id": "0x1234abcd",
  "question": "Will the Fed cut rates in March 2026?",
  "description": "This market resolves to YES if the Federal Reserve...",
  "outcomes": [
    {"name": "Yes", "probability": 45.2},
    {"name": "No", "probability": 54.8}
  ],
  "volume": "1250000",
  "liquidity": "320000",
  "endDate": "2026-03-20T00:00:00Z",
  "active": true,
  "closed": false,
  "category": "Economics"
}
006/

Pricing

ANIMA Trade charges a simple, transparent fee on every transaction. No subscriptions, no hidden costs.

0.2%
Per trade
$0
API calls
$0
Setup fee

Fee Examples

Trade Value Fee (0.2%)
$100 $0.20
$1,000 $2.00
$10,000 $20.00

Paper trading is free. Practice your strategies without any fees using paper trading mode.

007/

Rate Limits

To ensure fair usage and platform stability, all API endpoints are rate limited. Limits are applied per API key.

Endpoint Category Rate Limit Window
/v1/stocks/quote 100 requests 1 minute
/v1/quote 60 requests 1 minute
/v1/stocks/order 30 requests 1 minute
/v1/swap 20 requests 1 minute
All other endpoints 120 requests 1 minute

Rate Limit Headers

Every response includes headers to help you track your usage:

Response Headers 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706853600

Exceeding rate limits returns a 429 Too Many Requests error. Wait until the reset time before retrying.

008/

Error Codes

The API uses standard HTTP status codes and returns detailed error information in the response body.

Error Response Format

Error Response 
{
  "success": false,
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "The symbol 'XYZ123' is not a valid stock ticker"
  }
}

HTTP Status Codes

  • 200 OK — Request succeeded
  • 400 Bad Request — Invalid parameters or malformed request
  • 401 Unauthorized — Missing or invalid API key
  • 403 Forbidden — API key doesn't have permission for this action
  • 404 Not Found — Resource doesn't exist
  • 422 Unprocessable Entity — Request understood but cannot be processed (e.g., insufficient funds)
  • 429 Too Many Requests — Rate limit exceeded
  • 500 Internal Server Error — Something went wrong on our end

Common Error Codes

  • INVALID_API_KEY The provided API key is invalid or has been revoked
  • INVALID_SYMBOL The stock symbol is not recognized
  • INSUFFICIENT_FUNDS Not enough balance to execute the trade
  • MARKET_CLOSED Stock market is currently closed (stocks only)
  • SLIPPAGE_EXCEEDED Price moved beyond the specified slippage tolerance (crypto only)
  • ORDER_REJECTED Order was rejected by the exchange