Holder ledger

GET

/arc/token/{address}/holders

const url = 'https://api.getchord.xyz/v1/arc/token/example/holders?limit=50';
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/arc/token/example/holders?limit=50'

Top balances from Chord’s own Transfer-log ledger, each tagged wallet / pool / burn, with the holder count, the share of supply outside pools and burn sinks, and concentration (top 1 / 5 / 10 / 20 / 50 / 100). A token the ledger does not track yet is pinned for tracking and answers 503 HOLDERS_PENDING — retry in a few minutes. A tracked token whose backfill has not reached its creation block answers 200 with complete: false (never a guess from the tape).

Parameters

Path Parameters

address

required

EVM address, hex, case-insensitive.

string

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

Query Parameters

limit

integer

default: 50 >= 1 <= 200

Top rows.

Responses

200

application/json

object

chain

integer

Allowed value: 5042

token

EVM address, hex, case-insensitive.

string

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

tracked

boolean

complete

Backfill reached the creation block — balances are the full ledger.

boolean

coverage

object

addedBlock

integer | null

floorBlock

integer | null

backfillCursor

integer | null

forwardCursor

integer | null

logs

integer

decimals

integer | null

totalSupply

Smallest unit.

string | null

holders

integer

heldByWalletsPct

number | null

concentration

object

top1

number

top5

number

top10

number

top20

number

top50

number

top100

number

top

Array<object>

object

holder

EVM address, hex, case-insensitive.

string

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

balance

Smallest unit.

string

amount

Whole tokens.

number | null

sharePct

number | null

kind

string

Allowed values: wallet pool burn

updatedAt

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

integer

Example

{
  "chain": 5042,
  "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
  "tracked": true,
  "complete": true,
  "coverage": {
    "addedBlock": 21273471,
    "floorBlock": 560194,
    "backfillCursor": 560194,
    "forwardCursor": 21808247,
    "logs": 68037
  },
  "decimals": 8,
  "totalSupply": "33681495614",
  "holders": 2599,
  "heldByWalletsPct": 96.0477,
  "concentration": {
    "top1": 63.64,
    "top5": 90.91,
    "top10": 90.91,
    "top20": 90.91,
    "top50": 90.91,
    "top100": 90.91
  },
  "top": [
    {
      "holder": "0x34cd04070dd72b14e241112f6d83812df5af7fcd",
      "balance": "21451899028",
      "amount": 214.51899,
      "sharePct": 63.6904,
      "kind": "wallet"
    },
    {
      "holder": "0x82916bee18fcef517b26c72d7cb5f13694e1db41",
      "balance": "6776124246",
      "amount": 67.761242,
      "sharePct": 20.1182,
      "kind": "pool"
    }
  ],
  "updatedAt": 1789891855690
}

400

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, 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"
}

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.

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"
}