> 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/duo-di-zhi-zi-jin-liu.md).

# 多地址資金流

查詢指定代幣在一批地址間、特定時間區間內的資金流動。回傳各地址收入、支出、淨流量與整體加總，單次最多 100 個地址。

## GET /v1/token/addresses\_flow

>

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢指定代幣在一批地址間、特定時間區間內的資金流動。回傳各地址收入、支出、淨流量與整體加總，單次最多 100 個地址。","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":{"AddressesFlowAggregate":{"description":"全體地址加總。對「項目方出貨」場景:`net_flow_total < 0` 表示淨送出。","properties":{"net_flow_total":{"format":"double","type":"number"},"net_flow_total_usd":{"format":"double","type":["number","null"]},"received_total":{"format":"double","type":"number"},"sent_total":{"format":"double","type":"number"},"tx_count_total":{"format":"int64","minimum":0,"type":"integer"}},"required":["received_total","sent_total","net_flow_total","tx_count_total"],"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"},"AddressFlow":{"description":"單一地址在區間內的流量明細。","properties":{"address":{"type":"string"},"first_activity_ts":{"format":"int64","type":["integer","null"]},"last_activity_ts":{"format":"int64","type":["integer","null"]},"net_flow":{"description":"淨流量 = received − sent。負值表示出貨。","format":"double","type":"number"},"net_flow_usd":{"description":"僅穩定幣會附（USDT / USDC / DAI）= `net_flow`。","format":"double","type":["number","null"]},"received":{"description":"區間內收到的 token 數量（已依 decimals 換算）。","format":"double","type":"number"},"received_count":{"format":"int64","minimum":0,"type":"integer"},"sent":{"description":"區間內送出的 token 數量。","format":"double","type":"number"},"sent_count":{"format":"int64","minimum":0,"type":"integer"},"tx_count":{"format":"int64","minimum":0,"type":"integer"}},"required":["address","received","sent","net_flow","received_count","sent_count","tx_count"],"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/addresses_flow":{"get":{"operationId":"addresses_flow","parameters":[{"description":"鏈名稱（`ethereum` / `tron` / `bitcoin`）。","in":"path","name":"blockchain","required":true,"schema":{"type":"string"}},{"description":"合約地址（ethereum / tron 必填，bitcoin 必須省略）。","in":"path","name":"contract","required":true,"schema":{"type":["string","null"]}},{"description":"Comma-separated 地址清單（1..=100）。","in":"path","name":"addresses","required":true,"schema":{"type":"string"}},{"description":"區間起點 unix timestamp（秒）。","in":"path","name":"from_ts","required":true,"schema":{"format":"int64","type":"integer"}},{"description":"區間終點 unix timestamp（秒）。`to_ts - from_ts ≤ 365 天`。","in":"path","name":"to_ts","required":true,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"代幣地址間資金流動查詢的回應。","properties":{"address_count":{"format":"int32","minimum":0,"type":"integer"},"aggregate":{"$ref":"#/components/schemas/AddressesFlowAggregate"},"blockchain":{"type":"string"},"contract":{"type":["string","null"]},"decimals":{"format":"int32","minimum":0,"type":"integer"},"from_ts":{"format":"int64","type":"integer"},"meta":{"$ref":"#/components/schemas/QueryMeta"},"results":{"items":{"$ref":"#/components/schemas/AddressFlow"},"type":"array"},"symbol":{"type":"string"},"to_ts":{"format":"int64","type":"integer"}},"required":["blockchain","symbol","decimals","from_ts","to_ts","address_count","results","aggregate","meta"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功，回傳每個地址的資金流向與整體加總"},"400":{"description":"請求參數有誤（地址清單為空或超過 100 個、時間區間超過 365 天、或鏈別不符），請檢查輸入內容"},"401":{"description":"缺少或無效的 API key"},"402":{"description":"點數餘額不足"},"429":{"description":"請求過於頻繁，請稍後重試"},"502":{"description":"後端服務暫時無法回應，請稍後重試"}},"summary":"","tags":["多地址資金流"]}}}}
```