---
title: "Holder ledger"
method: GET
path: "/arc/token/{address}/holders"
tags: ["Arc data"]
---

# Holder ledger

`GET /arc/token/{address}/holders`

## Request

- Base URL: `https://api.getchord.xyz/v1`
- URL: `https://api.getchord.xyz/v1/arc/token/{address}/holders`
- Auth: none declared

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).

## Path parameters

- `address` string, required: EVM address, hex, case-insensitive.

## Query parameters

- `limit` integer

## Response `200`

- object
  - `chain` 5042
  - `token` string: EVM address, hex, case-insensitive.
  - `tracked` boolean
  - `complete` boolean: Backfill reached the creation block — balances are the full ledger.
  - `coverage` object
    - `addedBlock` integer, nullable
    - `floorBlock` integer, nullable
    - `backfillCursor` integer, nullable
    - `forwardCursor` integer, nullable
    - `logs` integer
  - `decimals` integer, nullable
  - `totalSupply` string, nullable: Smallest unit.
  - `holders` integer
  - `heldByWalletsPct` number, nullable
  - `concentration` object, nullable
    - `top1` number
    - `top5` number
    - `top10` number
    - `top20` number
    - `top50` number
    - `top100` number
  - `top` object[]
    - `holder` string: EVM address, hex, case-insensitive.
    - `balance` string: Smallest unit.
    - `amount` number, nullable: Whole tokens.
    - `sharePct` number, nullable
    - `kind` 'wallet' | 'pool' | 'burn'
  - `updatedAt` integer: Unix time, milliseconds — when the server built this answer.

## Other responses

- `400`: Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).
- `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.

---

[API](https://skmtc.dev/getchord/apis/chord-api.md) · [All operations](https://skmtc.dev/getchord/apis/chord-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getchord/apis/chord-api/revisions/d3bc4640fea0?raw)