## GET /openapi/v1/dex/tokens/holders

One DEX token's largest holders, and how many it has.

### Query parameters

| Parameter | Type | Default | Notes |
|:--|:--|:--|:--|
| `chain_slug`, `address` | string | required | See [naming a token](#dex-tokens-what-the-endpoints-share) |

### Response

```json
{
  "code": 0,
  "message": "success",
  "message_key": "SUCCESS",
  "result": {
    "available": true,
    "data_time": "2026-10-21T07:00:00Z",
    "stale": false,
    "holders_count": 18234,
    "items": [
      {
        "rank": 1,
        "wallet_address": "0x4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e",
        "balance": "125000000.5",
        "percent": "12.5",
        "tags": ["lp"],
        "first_active_time": "2026-08-26T19:33:20Z"
      }
    ]
  }
}
```

Not paged: up to 100 holders, largest first, as the source ranks them. The source refreshes the
snapshot every 15 minutes to an hour, less often for quiet tokens; a snapshot expires 24 hours
after it was last written, and the tab then answers `available: false`.

| Field | Type | Notes |
|:--|:--|:--|
| `available`, `data_time` | | As on `/dex/tokens/trades` |
| `stale` | boolean | Last refreshed more than 12 hours ago |
| `holders_count` | number or `null` | How many wallets hold the token: the snapshot's count, else the list's; `null` when neither has one. Served whether or not `available` |
| `items[].rank` | number | 1 is the largest |
| `items[].wallet_address` | string | |
| `items[].balance` | string or `null` | In the token's units |
| `items[].percent` | string or `null` | Share of the supply, in percent (`"12.5"` is 12.5%) |
| `items[].tags` | array | Labels on the wallet; may be empty |
| `items[].first_active_time` | string or `null` | RFC3339 |

### Examples

```bash
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/dex/tokens/holders?chain_slug=base&address=0x07b3d902783c3c12b077508c3b5c00113d1291d0"
```

| HTTP status | `code` | When |
|:--|:--|:--|
| 400 | 40000 | `chain_slug` or `address` missing |
| 404 | 40400 | The token, as on `/dex/tokens/info` |
| 503 | 50300 | No Trending list younger than three hours; reading the holders, or a token no list holds, timed out (retryable) |
| 500 | 50000 | Reading the holders failed for another reason |

The other errors are in [Errors](#errors).