Skip to content
ChordChordChord Docs

One token: hourly tape and venue split

GET
/arc/token/{address}
curl --request GET \
  --url 'https://api.getchord.xyz/v1/arc/token/example?hours=168'

The token row plus an hourly series (1–720 hours) and the venue split for the window. Feeds Chord’s token page header, volume bars and venue table. A token with no 24-hour row comes back as { address, listed: false }.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
address
required

EVM address, hex, case-insensitive.

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

Query Parameters

Section titled “Query Parameters”
hours
integer
default: 168 >= 1 <= 720

Hourly buckets to return.

Responses

Section titled “ Responses ”

200

Section titled “200”
Media typeapplication/json
object
chain
integer
Allowed value: 5042
token
One of:

One token on Arc with its 24-hour tape.

object
address

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
symbol
string | null
name
string | null
decimals
integer | null
logoURI

Logo through Chord’s proxy (/v1/logo/5042/{address}, 128 px WebP).

string | null
logoUriRaw

The upstream logo URL the proxy fetched, when there is one.

string | null
tags

stablecoin, fx, stock, … — from the curated list; empty for unlisted tokens.

Array<string>
listed

On the curated Arc token list (metadata and logo vetted).

boolean
priceUsd

Last trade price on the token’s dominant venue, USD.

number | null
change24hPct
number | null
volume24h

USD, every venue, no dust floor.

number
buyVolume24h
number
sellVolume24h
number
trades24h
integer
buys24h
integer
sells24h
integer
traders

Distinct attributed wallets over the board’s day window. Routers, executors and bots are not wallets.

integer
lastTradeTs

Unix time, seconds, UTC.

integer
totalSupply

totalSupply() in whole tokens. Null when unreadable.

number | null
marketCapUsd

TotalSupply × price — fully diluted, since nothing on-chain says what is locked.

number | null
pools

Indexed pools holding the token.

object
v3
integer
v2
integer
v4
integer
byDex

Pool count per venue id (uniswap_v3, uniswap_v4, pools_trade, slipstream_fork, v3fork_<8hex>, …).

object
key
additional properties
integer
routable

The engine can quote this token today (at least one pool against a routing anchor).

boolean
flags

Honesty flags. wash = a day’s volume carried by one or two wallets; impostor = an unlisted token wearing a listed symbol. Absent when clean.

Array<string>
Allowed values: wash impostor
hours
integer
series

Oldest first.

Array<object>
object
hour
integer
volUsd
number
buyUsd
number
sellUsd
number
trades
integer
buys
integer
sells
integer
priceLast
number | null
byDex
Array<object>
object
dex
string
volUsd
number
trades
integer
sharePct
number
updatedAt

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

integer
Example
{
  "chain": 5042,
  "token": {
    "address": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
    "symbol": "cirBTC",
    "name": "cirBTC",
    "decimals": 8,
    "logoURI": "https://api.getchord.xyz/v1/logo/5042/0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
    "tags": [],
    "listed": true,
    "priceUsd": 80423.22925858323,
    "change24hPct": -1.0826513878648192,
    "volume24h": 5689551.810770997,
    "buyVolume24h": 2765666.247710997,
    "sellVolume24h": 2923885.56306,
    "trades24h": 19472,
    "buys24h": 10554,
    "sells24h": 8918,
    "traders": 3203,
    "lastTradeTs": 1789891845,
    "totalSupply": 336.81495614,
    "marketCapUsd": 27087746.435366876,
    "pools": {
      "v3": 21,
      "v2": 5,
      "v4": 483,
      "byDex": {
        "uniswap_v3": 10,
        "v2fork_a2448256": 1,
        "slipstream_fork": 2,
        "v3fork_5bfbceb7": 6,
        "v3fork_bb74f231": 2,
        "v2fork_49aa1c63": 2,
        "v3fork_711492df": 1,
        "sushi_v2": 2,
        "uniswap_v4": 483
      }
    },
    "routable": true,
    "logoUriRaw": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/bitcoin/info/logo.png"
  },
  "hours": 2,
  "series": [
    {
      "hour": 1789887600,
      "volUsd": 109750.71408699999,
      "buyUsd": 59532.95500899996,
      "sellUsd": 50217.759078,
      "trades": 465,
      "buys": 247,
      "sells": 218,
      "priceLast": 80315.09208021293
    },
    {
      "hour": 1789891200,
      "volUsd": 14523.166291000001,
      "buyUsd": 13047.791779000001,
      "sellUsd": 1475.374512,
      "trades": 32,
      "buys": 23,
      "sells": 9,
      "priceLast": 80404.02465976504
    }
  ],
  "byDex": [
    {
      "dex": "uniswap_v3",
      "volUsd": 100905.00920399999,
      "trades": 460,
      "sharePct": 81.1956695140446
    },
    {
      "dex": "slipstream_fork",
      "volUsd": 23247.566194,
      "trades": 28,
      "sharePct": 18.706719483843752
    }
  ],
  "updatedAt": 1789891855212
}

400

Section titled “400”

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

Media typeapplication/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

Section titled “503”

The lane behind this endpoint is not ready or not enabled here (NOT_READY, CHAIN_NOT_ENABLED, NOT_ENABLED, *_UNAVAILABLE). Retry later; do not treat it as an empty answer.

Media typeapplication/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"
}