# Tokens

Token holder distribution & concentration（資料平面）

## GET /v1/token/concentration

> \`GET /v1/token/concentration\` — token 持有結構統計。

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"name":"tokens","description":"Token holder distribution & concentration（資料平面）"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"ConcentrationMetrics":{"type":"object","description":"集中度指標。`effective_holders_*` 只在穩定幣上有意義。","required":["top10_pct","top100_pct","top1000_pct","hhi","gini"],"properties":{"effective_holders_100usd":{"type":["integer","null"],"format":"int64","description":"餘額 ≥ $100 的地址數（僅穩定幣）。","minimum":0},"effective_holders_1usd":{"type":["integer","null"],"format":"int64","description":"餘額 ≥ $1 的地址數（僅穩定幣，其他 token 不附）。","minimum":0},"gini":{"type":"number","format":"double","description":"Gini coefficient（區塊鏈持有結構天然接近 1，僅供相對比較）。"},"hhi":{"type":"number","format":"double","description":"Herfindahl-Hirschman Index（0=完全分散，1=完全壟斷）。"},"top1000_pct":{"type":"number","format":"double"},"top100_pct":{"type":"number","format":"double"},"top10_pct":{"type":"number","format":"double","description":"前 10 名持有者占流通量 %。"}}},"QueryMeta":{"type":"object","description":"查詢層級的中繼資訊（直接從 blockchain-api-v2 帶上來）。","required":["query_duration_ms","cost_class","cached"],"properties":{"cached":{"type":"boolean","description":"是否由 blockchain-api-v2 端 cache 命中（true = 來自 Redis，非 CH）。"},"cost_class":{"type":"string","description":"`light` / `medium` / `heavy`。客戶可根據此值決定 retry / backoff。"},"limit":{"type":["integer","null"],"format":"int32","description":"holders 才有：請求的 limit。","minimum":0},"offset":{"type":["integer","null"],"format":"int32","description":"holders 才有：請求的 offset。","minimum":0},"query_duration_ms":{"type":"integer","format":"int64","description":"上游 ClickHouse 查詢耗時。","minimum":0}}},"Meta":{"type":"object","description":"回應的中繼資訊。所有欄位都是 `Option`，沒有的就不會出現在 JSON 裡\n（搭配 `skip_serializing_if`），維持輸出乾淨。","properties":{"credit_cost":{"type":["integer","null"],"format":"int64","description":"本次請求扣掉的 credit 數量（計費後填入）。"},"credit_remaining":{"type":["integer","null"],"format":"int64","description":"本次請求後剩餘的 credit 餘額。"},"pagination":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaginationMeta","description":"分頁資訊（僅列表型 endpoint 會帶）。"}]},"request_id":{"type":["string","null"],"description":"本次請求的唯一識別碼，與 log / 追蹤系統對應，方便客訴時定位。"}}},"PaginationMeta":{"type":"object","description":"對外的分頁中繼資訊。","required":["limit","offset"],"properties":{"limit":{"type":"integer","format":"int32","minimum":0},"offset":{"type":"integer","format":"int32","minimum":0},"total":{"type":["integer","null"],"format":"int64","description":"符合條件的總筆數（若下游能提供）。","minimum":0}}}}},"paths":{"/v1/token/concentration":{"get":{"tags":["tokens"],"summary":"`GET /v1/token/concentration` — token 持有結構統計。","operationId":"concentration","parameters":[{"name":"blockchain","in":"path","description":"鏈名稱（`ethereum` 或 `tron`）。","required":true,"schema":{"type":"string"}},{"name":"contract","in":"path","description":"合約地址。","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"集中度指標（包在 data/meta 信封內）","content":{"application/json":{"schema":{"type":"object","description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","required":["data","meta"],"properties":{"data":{"type":"object","description":"上游 `/api/v1/token/concentration` 回應。","required":["blockchain","contract","symbol","decimals","holder_count","concentration","meta"],"properties":{"blockchain":{"type":"string"},"concentration":{"$ref":"#/components/schemas/ConcentrationMetrics"},"contract":{"type":"string"},"decimals":{"type":"integer","format":"int32","minimum":0},"holder_count":{"type":"integer","format":"int64","minimum":0},"meta":{"$ref":"#/components/schemas/QueryMeta"},"symbol":{"type":"string"},"total_supply":{"type":["number","null"],"format":"double"},"total_supply_raw":{"type":["string","null"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"輸入驗證失敗"},"401":{"description":"缺少或無效的 API key"},"402":{"description":"Credit 餘額不足"},"429":{"description":"限流"},"502":{"description":"上游 blockchain-api-v2 錯誤"},"504":{"description":"上游 timeout"}}}}}}
```

## GET /v1/token/holders

> \`GET /v1/token/holders\` — 列出某 token 持有量前 N 名。

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"name":"tokens","description":"Token holder distribution & concentration（資料平面）"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"HolderEntry":{"type":"object","description":"單一持有者。","required":["rank","address","balance","balance_raw"],"properties":{"address":{"type":"string"},"balance":{"type":"number","format":"double","description":"已換算的餘額（依 `decimals`）。"},"balance_raw":{"type":"string","description":"raw 餘額（精度備援，UInt256 字串）。"},"balance_usd":{"type":["number","null"],"format":"double","description":"僅穩定幣（USDT/USDC/DAI）會有，等於 `balance`。"},"pct_of_supply":{"type":["number","null"],"format":"double","description":"占流通量百分比（總流通量為 0 時不附）。"},"rank":{"type":"integer","format":"int32","minimum":0}}},"QueryMeta":{"type":"object","description":"查詢層級的中繼資訊（直接從 blockchain-api-v2 帶上來）。","required":["query_duration_ms","cost_class","cached"],"properties":{"cached":{"type":"boolean","description":"是否由 blockchain-api-v2 端 cache 命中（true = 來自 Redis，非 CH）。"},"cost_class":{"type":"string","description":"`light` / `medium` / `heavy`。客戶可根據此值決定 retry / backoff。"},"limit":{"type":["integer","null"],"format":"int32","description":"holders 才有：請求的 limit。","minimum":0},"offset":{"type":["integer","null"],"format":"int32","description":"holders 才有：請求的 offset。","minimum":0},"query_duration_ms":{"type":"integer","format":"int64","description":"上游 ClickHouse 查詢耗時。","minimum":0}}},"Meta":{"type":"object","description":"回應的中繼資訊。所有欄位都是 `Option`，沒有的就不會出現在 JSON 裡\n（搭配 `skip_serializing_if`），維持輸出乾淨。","properties":{"credit_cost":{"type":["integer","null"],"format":"int64","description":"本次請求扣掉的 credit 數量（計費後填入）。"},"credit_remaining":{"type":["integer","null"],"format":"int64","description":"本次請求後剩餘的 credit 餘額。"},"pagination":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaginationMeta","description":"分頁資訊（僅列表型 endpoint 會帶）。"}]},"request_id":{"type":["string","null"],"description":"本次請求的唯一識別碼，與 log / 追蹤系統對應，方便客訴時定位。"}}},"PaginationMeta":{"type":"object","description":"對外的分頁中繼資訊。","required":["limit","offset"],"properties":{"limit":{"type":"integer","format":"int32","minimum":0},"offset":{"type":"integer","format":"int32","minimum":0},"total":{"type":["integer","null"],"format":"int64","description":"符合條件的總筆數（若下游能提供）。","minimum":0}}}}},"paths":{"/v1/token/holders":{"get":{"tags":["tokens"],"summary":"`GET /v1/token/holders` — 列出某 token 持有量前 N 名。","operationId":"holders","parameters":[{"name":"blockchain","in":"path","description":"鏈名稱（`ethereum` 或 `tron`）。","required":true,"schema":{"type":"string"}},{"name":"contract","in":"path","description":"合約地址：ETH 用 `0x` 開頭 40 字 hex；TRON 用 Base58Check (`T…`)。","required":true,"schema":{"type":"string"}},{"name":"limit","in":"path","description":"取前幾名（預設 10，上限 100）。","required":true,"schema":{"type":["integer","null"],"format":"int32","minimum":0}},{"name":"offset","in":"path","description":"偏移（預設 0）。","required":true,"schema":{"type":["integer","null"],"format":"int32","minimum":0}}],"responses":{"200":{"description":"持有者排行（包在 data/meta 信封內）","content":{"application/json":{"schema":{"type":"object","description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","required":["data","meta"],"properties":{"data":{"type":"object","description":"上游 `/api/v1/token/holders` 回應。\n\n`meta` 是「query 本身」的中繼資訊（cache 狀態、耗時、成本級別）；\n我們再把整個物件包進 atlantis 的 `ApiResponse { data, meta }`，\n**外層的 meta** 才帶 request_id 等 gateway 層中繼，所以對外會看到兩個 meta，\n一個描述查詢、一個描述請求。","required":["blockchain","contract","symbol","decimals","holder_count","holders","meta"],"properties":{"blockchain":{"type":"string"},"contract":{"type":"string"},"decimals":{"type":"integer","format":"int32","minimum":0},"holder_count":{"type":"integer","format":"int64","minimum":0},"holders":{"type":"array","items":{"$ref":"#/components/schemas/HolderEntry"}},"meta":{"$ref":"#/components/schemas/QueryMeta"},"symbol":{"type":"string"},"total_supply":{"type":["number","null"],"format":"double","description":"流通量（以 token 單位換算）；空 token 可能為 null。"},"total_supply_raw":{"type":["string","null"],"description":"流通量 raw（已乘 decimals，作為精度備援）。"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"輸入驗證失敗（鏈不支援 / contract 格式錯）"},"401":{"description":"缺少或無效的 API key"},"402":{"description":"Credit 餘額不足"},"429":{"description":"限流"},"502":{"description":"上游 blockchain-api-v2 錯誤"},"504":{"description":"上游 timeout（重 token 可能超出 UPSTREAM_TIMEOUT_MS）"}}}}}}
```


---

# Agent Instructions: 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/api-reference/readme/tokens.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.