> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/zi-liao-api/token-holders.md).

# 持有者與集中度

分析某個 token 的持有結構：前 N 名持有者、以及集中度指標。回應包在 `{ data, meta }` 信封。

{% hint style="warning" %}
**這兩支較重。** 上游在 ClickHouse 上是大表掃描——熱門合約 cold cache 可能要數秒到數十秒（例：TRON USDT 約 23 秒）。命中快取後 < 30 ms。 請預留較長 timeout，並用回應 `data.meta.cost_class`（`light` / `medium` / `heavy`）決定重試 / backoff。重合約可能回 `504`。
{% endhint %}

支援鏈：`ethereum`、`tron`。`contract`：ETH 用 `0x…`（40 hex），TRON 用 Base58（`T…`）。

## 持有者排行

```bash
curl "https://api.atlantis.example/v1/token/holders?blockchain=ethereum&contract=0xdAC17F958D2ee523a2206206994597C13D831ec7&limit=10&offset=0" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

| 參數           | 必填 | 說明                  |
| ------------ | -- | ------------------- |
| `blockchain` | 是  | `ethereum` 或 `tron` |
| `contract`   | 是  | 合約地址                |
| `limit`      | 否  | 取前幾名（預設 10，上限 100）  |
| `offset`     | 否  | 偏移（預設 0）            |

```json
{
  "data": {
    "blockchain": "ethereum",
    "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "symbol": "USDT",
    "decimals": 6,
    "holder_count": 14000000,
    "total_supply": 39000000000.0,
    "total_supply_raw": "39000000000000000",
    "holders": [
      {
        "rank": 1,
        "address": "0xF977814e90dA44bFA03b6295A0616a897441aceC",
        "balance": 1200000000.0,
        "balance_raw": "1200000000000000",
        "balance_usd": 1200000000.0,
        "pct_of_supply": 3.08
      }
    ],
    "meta": { "query_duration_ms": 6100, "cost_class": "heavy", "cached": false, "limit": 10, "offset": 0 }
  },
  "meta": { "request_id": "9b1c..." }
}
```

> `balance_usd` / `pct_of_supply` 只在穩定幣或有流通量時才附。注意有**兩個 `meta`**：內層 `data.meta` 描述「查詢」（耗時、cost\_class、是否命中快取），外層 `meta` 描述「請求」（`request_id`）。

## 集中度

```bash
curl "https://api.atlantis.example/v1/token/concentration?blockchain=tron&contract=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

```json
{
  "data": {
    "blockchain": "tron",
    "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "symbol": "USDT",
    "decimals": 6,
    "holder_count": 75000000,
    "total_supply": 60000000000.0,
    "concentration": {
      "top10_pct": 18.5,
      "top100_pct": 42.0,
      "top1000_pct": 61.3,
      "hhi": 0.012,
      "gini": 0.98,
      "effective_holders_1usd": 40000000,
      "effective_holders_100usd": 8000000
    },
    "meta": { "query_duration_ms": 23000, "cost_class": "heavy", "cached": false }
  },
  "meta": { "request_id": "..." }
}
```

| 指標                                         | 說明                                        |
| ------------------------------------------ | ----------------------------------------- |
| `top10_pct` / `top100_pct` / `top1000_pct` | 前 N 名占流通量 %                               |
| `hhi`                                      | Herfindahl-Hirschman Index（0=完全分散，1=完全壟斷） |
| `gini`                                     | Gini 係數（鏈上持有天然接近 1，僅供相對比較）                |
| `effective_holders_1usd` / `_100usd`       | 餘額 ≥ $1 / $100 的地址數（**僅穩定幣**才附）           |

## 端點與計費

這兩支較重，credit 權重高於一般端點。

| Method | 路徑                        | 說明      | Credit |
| ------ | ------------------------- | ------- | ------ |
| `GET`  | `/v1/token/holders`       | 持有者排行   | 10     |
| `GET`  | `/v1/token/concentration` | 持有集中度指標 | 15     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/zi-liao-api/token-holders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.