One token: hourly tape and venue split

GET

/chains/{chain}/token/{address}

const url = 'https://api.getchord.xyz/v1/chains/avalanche/token/example?hours=168';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.getchord.xyz/v1/chains/avalanche/token/example?hours=168'

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

Path Parameters

chain

required

string

Allowed values: 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

required

EVM address, hex, case-insensitive.

string

/^0x[a-fA-F0-9]{40}$/

Token address. The zero address means the chain’s wrapped native token (WAVAX, WETH, WBNB).

Query Parameters

hours

integer

default: 168 >= 1 <= 720

Hourly buckets to return.

Responses

200

application/json

object

chain

integer

token

object

address

EVM address, hex, case-insensitive.

string

/^0x[a-fA-F0-9]{40}$/

symbol

string | null

name

string | null

decimals

integer | null

logoURI

null

hours

integer

stats24h

object

volUsd

number

buyUsd

number

sellUsd

number

trades

integer

buys

integer

sells

integer

lastTs

Unix time, seconds, UTC.

integer

dominantDex

string | null

priceUsd

Last print on the dominant venue.

number | null

priceThen

Price 24 hours ago, same rule.

number | null

change24hPct

number | null

sinceHour

integer

series

Oldest first. Hours without a trade are absent.

Array<object>

object

hour

integer

volUsd

number

buyUsd

number

sellUsd

number

trades

integer

buys

integer

sells

integer

priceLast

The busiest venue’s last print in the hour.

number | null

byDex

Over the requested window, biggest first.

Array<object>

object

dex

string

volUsd

number

trades

integer

sharePct

number

coverage

When the rollup last ran.

object

recentAt

Unix time, seconds, UTC.

integer

stale

True when the last rollup pass is more than 30 minutes old.

boolean

ingestFloor

The tape’s ingest floor. BNB Chain runs at $100 today; Avalanche and Base at 0.

object

minTradeUsd

Trades under this USD value (at index time) are not in the index, so every count, volume and candle covers trades at or above it. 0 = every priced trade.

number

history

Floors in force over time, oldest first. Empty when the chain was never floored. Raising a floor does not remove older, smaller rows.

Array<object>

object

usd

Floor in force.

number

fromTs

Unix time, seconds, UTC.

integer

updatedAt

Unix time, milliseconds — when the server built this answer.

integer

Example

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

application/json

Every non-2xx body.

object

error

required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string

message

For humans.

string

statusCode

HTTP status, when included.

integer

Example

{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

404

UNKNOWN_TOKEN: no indexed trades for this token on this chain.

application/json

Every non-2xx body.

object

error

required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string

message

For humans.

string

statusCode

HTTP status, when included.

integer

Example

{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

429

Over the per-minute limit (RATE_LIMIT_EXCEEDED). Read X-RateLimit-Reset and back off.

application/json

Every non-2xx body.

object

error

required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string

message

For humans.

string

statusCode

HTTP status, when included.

integer

Example

{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

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.

application/json

Every non-2xx body.

object

error

required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string

message

For humans.

string

statusCode

HTTP status, when included.

integer

Example

{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}