Tokens API

Endpoints for retrieving token information, searching tokens, importing new tokens, and fetching price data.

List Tokens

GET /api/tokens

Returns a paginated list of tokens.

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID (e.g., 167000 for Taiko)
search	string	Filter by token name or symbol
limit	integer	Number of results to return (default: 50)
offset	integer	Pagination offset (default: 0)

Response:

{
  "success": true,
  "data": [
    {
      "address": "0x...",
      "name": "Wrapped Ether",
      "symbol": "WETH",
      "decimals": 18,
      "price_usd": 3245.67,
      "volume_24h": 1250000.00,
      "logo_url": "https://..."
    }
  ],
  "total": 128
}

Get Token Details

GET /api/tokens/{address}

Returns detailed information for a single token.

Path Parameters:

Parameter	Type	Description
address	string	Token contract address

Response:

{
  "success": true,
  "data": {
    "address": "0x...",
    "name": "Wrapped Ether",
    "symbol": "WETH",
    "decimals": 18,
    "price_usd": 3245.67,
    "volume_24h": 1250000.00,
    "market_cap": 0,
    "total_supply": "1000000000000000000000",
    "holders": 1523
  }
}

Import Token

POST /api/tokens/import

Import a token by its contract address. The server fetches on-chain metadata (name, symbol, decimals) and registers the token in the database.

Request Body:

{
  "address": "0x...",
  "chain_id": 167000
}

Response:

{
  "success": true,
  "data": {
    "address": "0x...",
    "name": "My Token",
    "symbol": "MTK",
    "decimals": 18
  }
}

Batch Token Prices

GET /api/prices

Returns current USD prices for all tracked tokens on the specified chain.

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID

Response:

{
  "success": true,
  "data": {
    "0xabc...": 3245.67,
    "0xdef...": 1.001,
    "0x123...": 0.0542
  }
}

Price History

GET /api/prices/{address}/history

Returns OHLC (Open, High, Low, Close) price history for a token.

Path Parameters:

Parameter	Type	Description
address	string	Token contract address

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID
interval	string	Candle interval (e.g., 1h, 4h, 1d)
from	integer	Start timestamp (Unix seconds)
to	integer	End timestamp (Unix seconds)

Response:

{
  "success": true,
  "data": [
    {
      "timestamp": 1700000000,
      "open": 3200.00,
      "high": 3260.50,
      "low": 3190.00,
      "close": 3245.67,
      "volume": 45230.50
    }
  ]
}