持有者與集中度

Token 持有者排行與持有集中度（HHI / Gini / Top-N 占比）。

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

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

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

持有者排行

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）

{
  "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）。

集中度

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

{
  "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 個）之間、指定時間區間內的資金流動，回傳各地址收入、支出、淨流量與整體加總，適合監控名單或項目方出貨分析。

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