StatusTerminal
APIUse casesOracleMCP & AgentsSDKsSkillsChangelog

Top holders of a token

GET
/chains/{chain}/tokens/{address}/holders

Wallets holding the token now, largest balance first, with their labels. Balances are the positions avee reconstructs from swaps and transfers it indexes, so a wallet that only ever received the token outside an indexed venue can be missing. holder_stats — count and top-ten share from the holder sweep, the same block the token carries — rides on the first page only.

Path Parameters

chain*string

chain slug (ton) or numeric chain id (950000)

Length1 <= length <= 32
address*string

chain-native address; EVM addresses are case-insensitive

Length1 <= length <= 128

Query Parameters

limit?integer

page size; plans above startup may raise the ceiling

Formatint32
Range1 <= value <= 100
Default10
cursor?string

opaque cursor from next_cursor or prev_cursor

Lengthlength <= 512

Header Parameters

Accept-Payment?string

payment methods the client can use, comma-separated, case-insensitive. With x402 in the list, a spent keyless budget answers 402 with the x402 challenge instead of 429.

PAYMENT-SIGNATURE?string

base64 x402 v2 payment payload for this request. A paid request skips the keyless budget and is settled only when it answers 2xx. The v1 header X-PAYMENT is accepted too.

Response Body

application/json

application/problem+json

application/problem+json

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/chains/string/tokens/string/holders"
{  "items": [    {      "address": "string",      "balance": 0.1,      "share_pct": 0.1,      "tier": "string",      "wallet_type": "unknown",      "labels": [        {          "kind": 0,          "name": "string",          "confidence": 0.1,          "token_address": "string"        }      ],      "first_buy_at": "string"    }  ],  "next_cursor": "string",  "prev_cursor": "string",  "holder_stats": {    "count": 0,    "top10_pct": 0.1,    "updated_at": "string"  }}

Resolve many tokens at once POST

Resolves up to 200 deployment references in one call. Unresolvable references come back with `found: false` rather than failing the batch.

Wallets that traded a token, with their PNL on it GET

Every wallet with a position in the token, open or closed, ranked by realized PNL unless `sort` says otherwise. Figures are lifetime on this token; there is no time window yet.