> 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/api-reference/readme/on-chain-data/dai-bi-chi-you-ren-pai-xing.md).

# 代幣持有人排行

列出指定代幣持有量最高的前 N 個地址，快速查看主要持有人與籌碼分布。

## GET /v1/token/holders

>

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"列出指定代幣持有量最高的前 N 個地址，快速查看主要持有人與籌碼分布。","name":"代幣持有人排行"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"HolderEntry":{"description":"單一持有者。","properties":{"address":{"type":"string"},"balance":{"description":"已換算的餘額（依 `decimals`）。","format":"double","type":"number"},"balance_raw":{"description":"raw 餘額（精度備援，UInt256 字串）。","type":"string"},"balance_usd":{"description":"僅穩定幣（USDT/USDC/DAI）會有，等於 `balance`。","format":"double","type":["number","null"]},"pct_of_supply":{"description":"占流通量百分比（總流通量為 0 時不附）。","format":"double","type":["number","null"]},"rank":{"format":"int32","minimum":0,"type":"integer"}},"required":["rank","address","balance","balance_raw"],"type":"object"},"QueryMeta":{"description":"查詢層級的中繼資訊。","properties":{"cached":{"description":"是否命中快取（true = 快取結果，回應較快）。","type":"boolean"},"cost_class":{"description":"`light` / `medium` / `heavy`。可依此值決定 retry / backoff 策略。","type":"string"},"limit":{"description":"holders 才有：請求的 limit。","format":"int32","minimum":0,"type":["integer","null"]},"offset":{"description":"holders 才有：請求的 offset。","format":"int32","minimum":0,"type":["integer","null"]},"query_duration_ms":{"description":"本次查詢耗時（毫秒）。","format":"int64","minimum":0,"type":"integer"}},"required":["query_duration_ms","cost_class","cached"],"type":"object"},"Meta":{"description":"回應的中繼資訊。所有欄位都是 `Option`，沒有的就不會出現在 JSON 裡\n（搭配 `skip_serializing_if`），維持輸出乾淨。","properties":{"credit_cost":{"description":"本次請求扣掉的 credit 數量（計費後填入）。","format":"int64","type":["integer","null"]},"credit_remaining":{"description":"本次請求後剩餘的 credit 餘額。","format":"int64","type":["integer","null"]},"pagination":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaginationMeta","description":"分頁資訊（僅列表型 endpoint 會帶）。"}]},"request_id":{"description":"本次請求的唯一識別碼，與 log / 追蹤系統對應，方便客訴時定位。","type":["string","null"]}},"type":"object"},"PaginationMeta":{"description":"對外的分頁中繼資訊。","properties":{"limit":{"format":"int32","minimum":0,"type":"integer"},"offset":{"format":"int32","minimum":0,"type":"integer"},"total":{"description":"符合條件的總筆數（若下游能提供）。","format":"int64","minimum":0,"type":["integer","null"]}},"required":["limit","offset"],"type":"object"}}},"paths":{"/v1/token/holders":{"get":{"operationId":"holders","parameters":[{"description":"鏈名稱（`ethereum` / `tron` / `bitcoin`）。","in":"path","name":"blockchain","required":true,"schema":{"type":"string"}},{"description":"合約地址:ETH 用 `0x` 開頭 40 字 hex;TRON 用 Base58Check (`T…`)。\nBitcoin 必須省略。","in":"path","name":"contract","required":true,"schema":{"type":["string","null"]}},{"description":"取前幾名（預設 10，上限 100）。","in":"path","name":"limit","required":true,"schema":{"format":"int32","minimum":0,"type":["integer","null"]}},{"description":"偏移（預設 0）。","in":"path","name":"offset","required":true,"schema":{"format":"int32","minimum":0,"type":["integer","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"代幣持有人查詢的回應。\n\n內層 `meta` 描述這次查詢本身（cache 狀態、耗時、成本級別）；外層信封的 `meta`\n則帶 request_id 等請求層資訊，所以你會看到兩個 `meta`：一個關於查詢、一個關於請求。\n\n`contract` 對 Bitcoin 原生幣為 null（BTC 無合約概念）。","properties":{"blockchain":{"type":"string"},"contract":{"type":["string","null"]},"decimals":{"format":"int32","minimum":0,"type":"integer"},"holder_count":{"format":"int64","minimum":0,"type":"integer"},"holders":{"items":{"$ref":"#/components/schemas/HolderEntry"},"type":"array"},"meta":{"$ref":"#/components/schemas/QueryMeta"},"symbol":{"type":"string"},"total_supply":{"description":"流通量（以 token 單位換算）；空 token 可能為 null。","format":"double","type":["number","null"]},"total_supply_raw":{"description":"流通量 raw（已乘 decimals，作為精度備援）。","type":["string","null"]}},"required":["blockchain","symbol","decimals","holder_count","holders","meta"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功，回傳代幣持有量排行"},"400":{"description":"請求參數有誤（鏈別不支援或合約位址格式錯誤），請檢查輸入內容"},"401":{"description":"缺少或無效的 API key"},"402":{"description":"點數餘額不足"},"429":{"description":"請求過於頻繁，請稍後重試"},"502":{"description":"後端服務暫時無法回應，請稍後重試"},"504":{"description":"查詢逾時，資料量較大的代幣請稍後重試"}},"summary":"","tags":["代幣持有人排行"]}}}}
```