> 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/on-chain-data/token-holders.md).

# 持有者與集中度

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

{% hint style="warning" %}
此類查詢較重。持有人數龐大的熱門合約首次查詢可能需要數秒至數十秒；命中快取時通常較快。請預留較長 timeout，並避免短時間重複查詢同一合約。
{% endhint %}

支援鏈：`ethereum`、`tron`、`bitcoin`。`contract`：ETH 用 `0x…`（40 hex），TRON 用 Base58（`T…`）；**Bitcoin 為原生幣，必須省略 `contract`**。

## 持有者排行

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

| 參數           | 必填 | 說明                                   |
| ------------ | -- | ------------------------------------ |
| `blockchain` | 是  | `ethereum` / `tron` / `bitcoin`      |
| `contract`   | 視鏈 | 合約地址；ethereum / tron 必填，bitcoin 必須省略 |
| `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.blockchainsecurity.asia/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，數值越高代表持有越集中 |
| `gini`                                     | Gini 係數，僅供不同 token 之間相對比較              |
| `effective_holders_1usd` / `_100usd`       | 餘額大於等於指定美元門檻的地址數                       |

## 多地址資金流

查詢某個代幣在一批地址（最多 100 個）之間、指定時間區間內的資金流動，回傳各地址收入、支出、淨流量與整體加總，適合監控名單或項目方出貨分析。

```bash
curl "https://api.blockchainsecurity.asia/v1/token/addresses_flow?blockchain=ethereum&contract=0xdAC17F958D2ee523a2206206994597C13D831ec7&addresses=0xf977814e90da44bfa03b6295a0616a897441acec,0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503&from_ts=1704067200&to_ts=1735603200" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

| 參數           | 必填 | 說明                                     |
| ------------ | -- | -------------------------------------- |
| `blockchain` | 是  | `ethereum` / `tron` / `bitcoin`        |
| `contract`   | 視鏈 | 合約地址；ethereum / tron 必填，bitcoin 必須省略   |
| `addresses`  | 是  | 逗號分隔的地址清單（1–100 個）                     |
| `from_ts`    | 是  | 區間起點（unix 秒）                           |
| `to_ts`      | 是  | 區間終點（unix 秒），`to_ts - from_ts ≤ 365 天` |

回傳 `results[]`（各地址的 `received` / `sent` / `net_flow` 與筆數）及 `aggregate` 整體加總；`net_flow` 為負代表淨送出（出貨）。

## 端點與計費

持有者排行與集中度涉及大量持有人資料與計算，credit 權重高於一般基礎查詢端點。

| Method | 路徑                         | 說明      | Credit |
| ------ | -------------------------- | ------- | ------ |
| `GET`  | `/v1/token/holders`        | 持有者排行   | 10     |
| `GET`  | `/v1/token/concentration`  | 持有集中度指標 | 15     |
| `GET`  | `/v1/token/addresses_flow` | 多地址資金流  | 5      |