# Holder ledger

`GET https://api.getchord.xyz/v1/arc/token/{address}/holders`

Source: https://getchord.xyz/docs/api-reference/operations/arctokenholders/

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

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `address` | path | yes | string |  |
| `limit` | query | no | integer (default `50`) | Top rows. |

## Response 200

Example (captured from the live API):

```json
{
  "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`, …).
- **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.