# One token: hourly tape and venue split

`GET https://api.getchord.xyz/v1/chains/{chain}/token/{address}`

Source: https://getchord.xyz/docs/api-reference/operations/chaintoken/

The token's identity (read from the contract), 24-hour stats, an hourly series (1–720 hours) and the venue split for the window. `404 UNKNOWN_TOKEN` when the chain's rollups have never seen the token trade; the same address on another chain is another token. For a price of a token Chord has not seen trade, `/ref-price` asks CoinGecko.

Chain-keyed data for Avalanche C-Chain, Base and BNB Chain, served from Chord's rollup tables for the chain (every swap summed by hour, token and venue). Only the trade tape, the prints ticker and the wallet read raw rows, scoped to one token or one wallet and bounded.

- **Access.** No key needed while the chain is public (all three are today). A chain whose tape is off, or that is not public yet, answers `400 UNSUPPORTED_CHAIN` ("chain N is not served yet") unless the request carries an `X-API-Key`; those answers are sent `Cache-Control: private`.
- **Ingest floor.** Every count, volume and print covers trades at or above the chain's floor, returned as `ingestFloor`. BNB Chain runs at $100 today; Avalanche and Base at 0.
- **Readiness.** `503 NOT_READY` until the chain's rollup has run on this deployment; `503 CHAIN_DATA_UNAVAILABLE` when the store cannot be read. Never treat either as "no trades".

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `chain` | path | yes | `avalanche` · `base` · `bnb` · `arbitrum` · `ethereum` · `43114` · `8453` · `56` · `42161` · `1` | The chain, by key or id: `avalanche` or `43114`, `base` or `8453`, `bnb` or `56`, `arbitrum` or `42161`, `ethereum` or `1` (case-insensitive). Arc, Robinhood Chain and Monad are refused with `400 UNSUPPORTED_CHAIN` and a pointer to their own routes. |
| `address` | path | yes | string | Token address. The zero address means the chain's wrapped native token (WAVAX, WETH, WBNB). |
| `hours` | query | no | integer (default `168`) | Hourly buckets to return. |

## Response 200

Example (captured from the live API):

```json
{
  "chain": 56,
  "token": {
    "address": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c",
    "symbol": "BTCB",
    "name": "BTCB Token",
    "decimals": 18,
    "logoURI": null
  },
  "hours": 2,
  "stats24h": {
    "volUsd": 60117802.11906611,
    "buyUsd": 28027904.632707972,
    "sellUsd": 32089897.486358132,
    "trades": 43182,
    "buys": 20811,
    "sells": 22371,
    "lastTs": 1791020918,
    "dominantDex": "pancake_v3",
    "priceUsd": 84842.07226361385,
    "priceThen": 86518.97620817002,
    "change24hPct": -1.93819207999113,
    "sinceHour": 1790935200
  },
  "series": [
    {
      "hour": 1791014400,
      "volUsd": 335885.749755259,
      "buyUsd": 157624.90195060932,
      "sellUsd": 178260.84780464956,
      "trades": 500,
      "buys": 259,
      "sells": 241,
      "priceLast": 84615.63679704415
    },
    {
      "hour": 1791018000,
      "volUsd": 499369.02600572666,
      "buyUsd": 84656.32485821295,
      "sellUsd": 414712.70114751335,
      "trades": 636,
      "buys": 166,
      "sells": 470,
      "priceLast": 84842.07226361385
    }
  ],
  "byDex": [
    {
      "dex": "pancake_v3",
      "volUsd": 712878.8358403383,
      "trades": 920,
      "sharePct": 85.34866923578463
    },
    {
      "dex": "uniswap_v3",
      "volUsd": 100444.15196685962,
      "trades": 98,
      "sharePct": 12.025570506357985
    }
  ],
  "coverage": {
    "recentAt": 1791020996,
    "stale": false
  },
  "ingestFloor": {
    "minTradeUsd": 100,
    "history": [
      {
        "usd": 100,
        "fromTs": 1790789196
      }
    ]
  },
  "updatedAt": 1791021450886
}
```

- **400**: `UNSUPPORTED_CHAIN` (unknown chain, a chain with its own routes, or a chain not served to this caller yet), or `BAD_ADDRESS` / `BAD_HOURS`.
- **404**: `UNKNOWN_TOKEN`: no indexed trades for this token on this chain.
- **429**: Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.
- **503**: `NOT_READY` (the chain's rollup has not run on this deployment yet) or `CHAIN_DATA_UNAVAILABLE` (the store could not be read). Retry later; do not treat it as an empty answer.