# BCS Intelligence API Docs 一站式鏈上數據與情資 API 為政府單位、交易所、銀行、託管機構與量化基金提供地址標籤、風險評分、資金流向與交易行為等鏈上情報能力，適用於 KYT / AML 合規、投資研究與交易策略等多元場景。 * **情資地址標籤** — 識別交易對手身分 * **風險分數** — 即時評估地址風險等級 * **資金流向** — 追蹤鏈上資金路徑 * **制裁名單比對** — 自動篩查 OFAC 等制裁清單 * **交易行為分析** — 偵測異常交易模式 * **鏈上情資** — 整合多鏈情報數據
開發者文件從第一次呼叫到進階整合。https://docs.blockchainsecurity.asia/documentation/files/QGqpShJHbFuUJu4euL1y
API 參考瀏覽、測試並串接所有端點。https://docs.blockchainsecurity.asia/api-reference/files/FuUnlpoyHgkbfWeKDh7a
說明中心查詢常見問題、排解疑難。https://docs.blockchainsecurity.asia/help-center/files/Qdy9byrfngL0nWjVaffm
{% columns %} {% column width="50%" %} ## 五分鐘內開始 只要一把 API key，就能發出第一個請求。 BCS Intelligence API 提供企業級鏈上情資與風險 API。透過單一 API key，即可查詢地址風險分數、制裁命中、黑名單標籤、資金流向與交易行為，協助交易所、銀行、託管與支付業者建立 KYT / AML / 鏈上風控流程。 {% hint style="info" icon="sparkle" %} 統一回應格式（Response Envelope） 所有成功回應都包含 data 與 meta；所有錯誤回應都包含 error、code、message 與 request\_id，方便工程、風控與稽核追蹤同一筆請求。 {% endhint %} {% hint style="success" icon="key" %} **用量計費，成功才扣** 以 credit 計價，只有成功的 2xx 回應才扣點。每次回應都會附上 credits\_used、remaining\_credits 與 request\_id，方便成本控管與對帳。 {% endhint %} {% endcolumn %} {% column width="50%" %} {% stepper %} {% step %} #### 取得 API key 請你方管理員在管理後台建立一把 key，並保存一次性回傳的明碼。 {% endstep %} {% step %} #### 發出第一個地址風險查詢 把 key 放進 X-API-Key header，即可呼叫 Address Risk API。 {% tabs %} {% tab title="cURL" %} ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/address-risk" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.blockchainsecurity.asia/v1/address-risk" headers = { "X-API-Key": "ak_live_YOUR_KEY", "Content-Type": "application/json" } payload = { "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9" } response = requests.post(url, headers=headers, json=payload) print(response.json()) ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} #### 看懂回應 以下為地址風險查詢的範例回應（節錄）。實際結果會依鏈別、地址與資料更新時間而不同，完整欄位見[地址風險](https://docs.blockchainsecurity.asia/documentation/lian-shang-api-mo-zu/address-risk)。 ```json { "data": { "chain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "risk_score": 26.78, "risk_level": "low", "risk_level_zh": "低", "behaviors": [ { "code": "rapid_in_out", "name_zh": "快速進出", "severity": "high", "score": 12.0, "occurrence_count": 8, "evidence": { "out_ratio": 9.99, "window_minutes": 30 } } ] }, "meta": { "request_id": "6c41c310-6a01-4c3e-8253-13e7c23e148a" } } ``` {% endstep %} {% endstepper %} {% endcolumn %} {% endcolumns %} # 歡迎 BCS API — 開發者文件 歡迎使用 BCS API——這份文件會帶你了解本服務的基本使用方式，包括 API key 設定、認證方式、回應格式、錯誤處理、Credit 計費規則與 API Reference 查閱方式。 你可以依照使用場景選擇不同 API 模組，例如地址標籤、風險評分、資金流向、制裁名單比對、交易行為分析、市場行為分析與多鏈資料查詢。 {% hint style="info" %} 本文件所有範例使用的正式服務網址為 `https://api.blockchainsecurity.asia`，可直接使用；只要把範例中的 `ak_live_YOUR_KEY` 換成你自己的 API key 即可。 {% endhint %} ## 從哪裡開始

:rocket-launch:

快速上手五分鐘內完成第一次 API 呼叫。/pages/fMIKfNrelo451cfsRJe8

:key:

認證與 API key了解 API key 的取得、使用方式。/pages/MFQ1oeKPnts4wocXInGo

:coins:

Credit 計費每次成功呼叫如何計費，以及如何查餘額。/pages/pdZr13kdI275d1FWwSKR

:terminal:

API 參考所有端點、參數與錯誤碼。/pages/ENpILCR0cyLHZ3mzFJQ4
## API 模組總覽 API 依業務邏輯分為七大類，與 API Reference 的章節一一對應。由上而下也是建議的認識順序：先確認涵蓋範圍與計價，再查鏈上事實，然後在事實之上做風險判斷與調查追蹤。 | 分類 | 涵蓋內容 | 文件 | | ------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Assets & Market Data** | 支援的鏈與幣種、資產識別解析、美元計價 | [幣種與鏈](/documentation/assets-and-market-data/assets)、[匯率行情](/documentation/assets-and-market-data/rates) | | **On-chain Data** | 交易明細、對手方、歷史餘額、持倉排行與集中度 | [地址活動查詢](/documentation/on-chain-data/address-activity)、[持有者與集中度](/documentation/on-chain-data/token-holders) | | **Risk & Intelligence** | 地址標籤身分、ML 地址分類、行為風險評分 | [地址標籤](/documentation/risk-and-intelligence/labels)、[地址風險](/documentation/risk-and-intelligence/address-risk)、[地址分類](/documentation/risk-and-intelligence/classification) | | **Investigation** | 多跳金流展開、Bitcoin 找零偵測 | [智能追蹤](/documentation/investigation/trace)、[Bitcoin 分析](/documentation/investigation/bitcoin) | | **Cross-chain** | 跨鏈橋接續追蹤 | [跨鏈追蹤](/documentation/cross-chain/cross-chain) | | **Address Utilities** | 地址驗證、糾錯、前綴自動完成 | [地址工具](/documentation/address-utilities/search) | | **Events** | Webhook 事件推播、即時串流 | [Webhook 訂閱](/documentation/events/webhooks)、[即時串流](/documentation/events/streaming) | ## 服務特色 * 統一接入 — 透過一組 X-API-Key 串接多類鏈上資料、風險情資與市場行為 API。 一致回應格式 — 所有服務共用 data、meta、error 結構，方便工程串接、系統維護與後續擴充。 Credit 計費 — 以 credit 計價，成功回應才扣點，並回傳 credit\_cost、credit\_remaining 供成本控管與對帳。 彈性限流 — 可依 API key、客戶方案與 endpoint 設定查詢頻率，支援高頻查詢與企業級用量控管。 請求追蹤 — 每次請求皆回傳 request\_id，方便除錯、稽核、客戶支援與事後對帳。 {% hint style="success" %} 想直接試打 API？可從 API Reference 複製範例請求 [`/docs`](https://api.blockchainsecurity.asia/docs)，或下載 OpenAPI 規格匯入 Postman、Swagger UI 等工具進行測試 [`/api-docs/openapi.json`](https://api.blockchainsecurity.asia/api-docs/openapi.json)。 {% endhint %} # 服務概觀 BCS API 的運作方式與基本概念。 BCS API 是一個 **API gateway**：你的應用程式只要對接這一個入口，就能存取背後的各項區塊鏈資料與情報服務。Gateway 負責處理認證、限流、計費、審計與可觀測性，讓你專注在業務本身。 ## 運作方式 ``` 你的應用程式 │ │ HTTPS + X-API-Key ▼ BCS API ├─ Authentication ├─ Rate Limiting ├─ Billing ├─ Audit Log └─ Observability │ ▼ 各項區塊鏈服務 地址風險 / 交易行為 / 情資 ``` 每一次請求都會： 1. 以 `X-API-Key` 驗證身分。 2. 依「API key + 端點」做限流。 3. 呼叫對應的後端服務。 4. **成功（2xx）時**才依端點權重扣除 credit。 5. 寫入稽核紀錄，並在回應帶上 `X-Request-Id`、`X-Credit-Cost`、`X-Credit-`\ `Remaining`。 ## 你需要知道的基本約定 | 項目 | 約定 | | ---- | --------------------------------------------- | | 通訊協定 | HTTPS，REST + JSON | | 認證 | 在 HTTP header 帶 `X-API-Key: <你的 key>` | | 成功回應 | 一律包在 `{ "data": ..., "meta": ... }` 信封內 | | 錯誤回應 | 一律包在 `{ "error": { "code", "message" } }` 信封內 | | 版本 | 路徑前綴 `/v1` | | 分頁 | 查詢參數 `?limit=&offset=` | | 計費 | credit 制，成功才扣，回應 header 附本次成本與餘額 | ### 使用端與管理端 BCS API 將「API 呼叫」與「帳號管理」分成兩個獨立區域： {% tabs %} {% tab title="API 使用端（給系統串接）" %} API 使用端（給系統串接） 供客戶系統、後端服務、交易系統、風控系統或分析模型呼叫 API 使用，例如鏈上資料查詢、地址風險評分、資金流追蹤、交易行為分析與市場訊號查詢。 • 使用 API key 認證（X-API-Key）。\ • 依 API key、方案與 endpoint 套用限流規則。\ • 成功回應依 Credit 規則扣點。\ • 每次請求皆回傳 request\_id，方便追蹤、除錯與對帳。 {% endtab %} {% tab title="管理後台（給管理員）" %} 管理後台（給管理員） 供管理員建立、撤銷與管理 API key，查看用量、調整 Credit 額度、管理方案與查詢審計紀錄。 • 使用帳號密碼登入，取得管理 session。\ • 不使用 API key 呼叫。\ • 管理操作不依 Credit 扣點。\ • 仍受角色權限、操作紀錄與安全性頻率限制控管。 {% endtab %} {% endtabs %} ## 下一步 {% content-ref url="/pages/fMIKfNrelo451cfsRJe8" %} [快速上手](/documentation/kai-shi-shi-yong/quickstart) {% endcontent-ref %} {% content-ref url="/pages/MFQ1oeKPnts4wocXInGo" %} [認證與 API key](/documentation/kai-shi-shi-yong/authentication) {% endcontent-ref %} # 快速上手 五分鐘內完成第一次 API 呼叫。 這份快速指南帶你用一把 API key 發出第一個請求，並看懂回應。 {% hint style="success" %} **預計時間：5 分鐘。** 你只需要一把 API key 與一個能發 HTTP 請求的工具（cURL、Postman 或任何語言的 HTTP client）。 {% endhint %} {% hint style="info" %} 本服務之資料查詢、完整 API 模組與商用串接，均需使用有效 API Key。如需申請測試、正式試用或評估串接流程，請聯絡 取得 API key。 {% endhint %} ## 步驟 {% stepper %} {% step %} #### 取得 API key API key 由你方的管理員建立。建立時系統會回傳一次性的明碼 key，格式類似： ``` ak_live_3f9a2c7b8e1d4a605c... ``` {% hint style="warning" %} 明碼 key **只會出現這一次**，請當場妥善保存。遺失只能撤銷後重建。 {% endhint %} {% endstep %} {% step %} #### 確認連線 先打不需認證的健康檢查端點，確認網路通暢： ```bash curl https://api.blockchainsecurity.asia/healthz # {"status":"ok"} ``` {% endstep %} {% step %} #### 發出第一個已認證的請求 把你的 key 放進 `X-API-Key` header。以「列出 webhook 訂閱」為例： {% tabs %} {% tab title="cURL" %} ```bash curl https://api.blockchainsecurity.asia/v1/webhooks \ -H "X-API-Key: ak_live_YOUR_KEY" ``` {% endtab %} {% tab title="Python" %} ```python import requests resp = requests.get( "https://api.blockchainsecurity.asia/v1/webhooks", headers={"X-API-Key": "ak_live_YOUR_KEY"}, ) print(resp.json()) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const resp = await fetch("https://api.blockchainsecurity.asia/v1/webhooks", { headers: { "X-API-Key": "ak_live_YOUR_KEY" }, }); console.log(await resp.json()); ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} #### 看懂回應 成功的回應一律包在 `{ data, meta }` 信封內： {% code title="response.json" %} ```json { "data": [], "meta": { "request_id": "9b1c2d3e-4f5a-6789-..." } } ``` {% endcode %} 同時，回應 header 會帶上： | Header | 意義 | | -------------------- | ---------------------------- | | `X-Request-Id` | 本次請求追蹤碼，除錯、客服與稽核時可提供 | | `X-Credit-Cost` | 本次扣除的 Credit，僅成功且需計費時出現 | | `X-Credit-Remaining` | 扣點後的剩餘 Credit，僅適用於 Credit 方案 | | {% endstep %} | | | {% endstepper %} | | ## 常見問題
我收到 401 unauthorized 確認 `X-API-Key` 有帶上、值正確，且該 key 尚未被撤銷或停用。詳見[認證與 API key](/documentation/kai-shi-shi-yong/authentication)。
我收到 402 insufficient_credit 該 key 的 Credit 餘額不足以支付本次請求。請聯絡你方管理員加值，或參考 [Credit 計費](/documentation/he-xin-gai-nian/credit-billing)。
我收到 429 rate_limited 觸發限流。回應的 `Retry-After` header 會告訴你建議幾秒後重試。詳見[限流](/documentation/he-xin-gai-nian/rate-limiting)。
## 下一步 {% content-ref url="/pages/MFQ1oeKPnts4wocXInGo" %} [認證與 API key](/documentation/kai-shi-shi-yong/authentication) {% endcontent-ref %} {% content-ref url="/pages/IIOYHLhxhH8x5X7Vxdx1" %} [回應格式](/documentation/he-xin-gai-nian/response-format) {% endcontent-ref %} # 認證與 API key 說明 API key 的使用方式、認證結果、保存規則、撤銷與輪替流程。 資料平面的所有請求都以 **API key** 認證。把 key 放進每個請求的 `X-API-Key` header 即可。 ```bash curl https://api.blockchainsecurity.asia/v1/webhooks \ -H "X-API-Key: ak_live_YOUR_KEY" ``` {% hint style="info" %} 未取得 API key？歡迎先免費試用。部分端點支援免 API key 測試（同 IP 每日 10 次），方便評估回傳格式與串接流程。 若需完整 API 模組、高頻率查詢或商用正式接入，請聯絡 申請專屬 API key，以享有完整額度與用量計費。 {% endhint %} ## API key 長什麼樣子 * API key 長什麼樣子 • API key 以 `ak_live_` 開頭，後接一段隨機字串，例如 `ak_live_3f9a2c7b8e1d4a60...`。 • 管理後台與操作紀錄只會顯示 key 的前綴或部分遮蔽字元，用於辨識，不會顯示完整明碼。 • 系統只保存 key 的雜湊值，不保存完整明碼。若遺失明碼，無法取回，只能撤銷後重新建立。 {% hint style="warning" %} 請將 API key 視同密碼保存。建議放在伺服器端環境變數或密鑰管理服務中，切勿寫入前端程式碼、公開 repository、版本控制或公開頁面。 {% endhint %} ## 認證結果 | 情況 | HTTP | code | 說明 | | ---------------- | ---: | --------------------- | --------------------------- | | 未帶 key，但端點允許免費試用 | 200 | — | 依免費試用額度處理請求 | | 未帶 key，且端點需認證 | 401 | `unauthorized` | 請求未提供有效 API key | | API key 無效或已撤銷 | 401 | `unauthorized` | key 不存在、格式錯誤或已被撤銷 | | API key 有效但權限不足 | 403 | `forbidden` | key 無權呼叫該 endpoint 或 API 模組 | | Credit 不足 | 402 | `insufficient_credit` | 剩餘額度不足，無法處理需計費請求 | | 超過限流 | 429 | `rate_limited` | 請求頻率超過目前方案或 endpoint 限制 | | 認證通過 | 200 | — | 繼續處理請求 | {% hint style="info" %} 為避免洩漏「某把 key 是否存在」，key 無效、已撤銷或不存在時，系統皆回傳 401 unauthorized。 {% endhint %} ## 取得與管理金鑰 API key 由客戶方管理員在管理後台建立與管理，可執行以下操作： • 建立 — 指定 key 名稱、方案、權限範圍與初始 Credit，建立後取得一次性明碼。 • 撤銷 — 立即停用該 key；撤銷後，使用該 key 的請求一律回傳 401 unauthorized。 • 調整 Credit — 依方案或授權額度，為指定 key 增加或減少可用 Credit。 ## 輪替金鑰 系統不會自動輪替，建議流程如下： {% stepper %} {% step %} #### 建立新 key 請管理員建立一把新 key，並妥善保存明碼。 {% endstep %} {% step %} #### 切換整合 將應用程式、後端服務或排程任務改用新 key，並重新部署。 {% endstep %} {% step %} ### 觀察請求 確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。 {% endstep %} {% step %} ### 撤銷舊 key 確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。 {% endstep %} {% endstepper %} ## 追蹤每個請求 每次回應都會包含 request\_id，並可能同步出現在 X-Request-Id header。當你回報問題、查詢扣點、追蹤延遲或進行稽核時，請提供該 request\_id 以加速定位。 ## 下一步 {% content-ref url="/pages/BBN0nBFpnfmeQEccdirr" %} [錯誤處理](/documentation/he-xin-gai-nian/errors) {% endcontent-ref %} {% content-ref url="/pages/hauJglYxlKcGMt6ydPim" %} [限流](/documentation/he-xin-gai-nian/rate-limiting) {% endcontent-ref %} # 回應格式 說明成功回應、錯誤回應、meta 欄位與 response header 的統一格式。 所有 API 模組皆採用一致的 response envelope。成功回應以 data 與 meta 回傳結果與請求資訊；錯誤回應以 error 回傳錯誤碼、訊息與追蹤資訊，方便工程串接、除錯、稽核與對帳。 ## 成功信封 ```json { "data": <實際資料>, "meta": { "request_id": "9b1c2d3e-...", "pagination": { "limit": 20, "offset": 0, "total": 134 }, "credit_cost": 5, "credit_remaining": 9995 } } ``` * **`data`** — 實際的業務資料。可能是物件、陣列，或列表型端點的項目集合。 * **`meta`** — 與本次請求有關的中繼資訊。欄位皆為選用，沒有就不會出現： | 欄位 | 何時出現 | 意義 | | ------------------ | ----- | ----------------------------------------------------- | | `request_id` | 一律 | 本次請求的追蹤碼，同 `X-Request-Id` | | `pagination` | 列表型端點 | 分頁狀態，見[分頁](/documentation/he-xin-gai-nian/pagination) | | `credit_cost` | 有計費時 | 本次扣除的 credit | | `credit_remaining` | 有計費時 | 扣除後的剩餘餘額 | {% hint style="info" %} 客戶端應依「欄位存在才解析」的原則處理 meta。某些欄位只會在特定 endpoint、計費方案或列表型查詢中出現；欄位不存在不代表錯誤。 {% endhint %} ## 錯誤信封 錯誤一律回傳對稱的結構，詳見[錯誤處理](/documentation/he-xin-gai-nian/errors)： ```json { "error": { "code": "rate_limited", "message": "rate limited, retry after 3s" } } ``` ## 回應 header | Header | 說明 | | -------------------- | ----------------------------- | | `X-Request-Id` | 請求追蹤碼（可自帶沿用） | | `X-Credit-Cost` | 本次請求扣除的 credit，僅成功且需計費時出現 | | `X-Credit-Remaining` | 扣點後剩餘 credit，僅適用於 Credit 方案 | | `Retry-After` | 遇到 429 rate limit 時，建議等待幾秒後重試 | ## 下一步 {% content-ref url="/pages/BBN0nBFpnfmeQEccdirr" %} [錯誤處理](/documentation/he-xin-gai-nian/errors) {% endcontent-ref %} {% content-ref url="/pages/JTozQ5Gb9ly2bavrljBP" %} [分頁](/documentation/he-xin-gai-nian/pagination) {% endcontent-ref %} # 錯誤處理 統一的錯誤信封、錯誤碼與建議處理方式。 所有錯誤回應皆使用 error 結構，並保留 meta.request\_id 供除錯、客服與稽核追蹤使用。錯誤時不回傳 data。 請以 error.code 作為程式判斷依據；error.message 僅供顯示、紀錄與人工閱讀，內容可能因語系或版本調整。 ## 錯誤信封 ```json { "error": { "code": "insufficient_credit", "message": "insufficient credit: required 5, remaining 2" } } ``` * **`code`** — 穩定的字串代碼，請用它做程式化分支。 * **`message`** — 人類可讀的說明，僅供顯示／記錄，內容可能調整，**請勿**拿來做邏輯判斷。 {% hint style="info" %} 基於安全考量，`500 internal_error` 對外只回傳通用訊息，細節僅記錄在伺服器端。回報時請附上 `X-Request-Id`。 {% endhint %} ## 錯誤碼一覽 | HTTP | code | 意義 | 建議處理 | | ---: | --------------------- | --------------------------------- | ------------------- | | 400 | `bad_request` | 參數缺漏、格式錯誤或請求無法解析 | 修正請求後重送 | | 401 | `unauthorized` | 缺少、格式錯誤、無效或已撤銷的 API key | 檢查 `X-API-Key` | | 403 | `forbidden` | API key 有效，但無權呼叫該 endpoint 或方案未開通 | 檢查權限或聯絡管理員 | | 402 | `insufficient_credit` | Credit 餘額不足，無法處理需計費請求 | 加值或調整方案 | | 404 | `not_found` | endpoint、資源或查詢目標不存在 | 檢查路徑與參數 | | 429 | `rate_limited` | 超過 API key、IP 或 endpoint 的限流規則 | 依 `Retry-After` 後重試 | | 502 | `upstream_error` | 上游資料源或後端服務暫時異常 | 稍後重試 | | 503 | `service_unavailable` | 服務暫時無法處理，例如維護或佇列已滿 | 稍後重試 | | 500 | `internal_error` | 非預期內部錯誤 | 附 `request_id` 回報 | ## 建議的重試策略 建議的重試策略 * 可安全重試：\ 429、502、503。遇到 429 時請遵守 Retry-After；其他暫時性錯誤建議採用指數退避（exponential backoff）。 * 不建議盲目重試：\ 400、401、403、404。這類錯誤通常代表請求、認證、權限或資源狀態有問題，應先修正後再重送。 * 計費例外：\ 402 insufficient\_credit 在加值或調整方案前，重試通常仍會失敗。 {% hint style="success" %} 計費提醒：Credit 僅在成功且需計費的 2xx 回應中扣除；錯誤回應不會扣點。 {% endhint %} ## 下一步 {% content-ref url="/pages/hauJglYxlKcGMt6ydPim" %} [限流](/documentation/he-xin-gai-nian/rate-limiting) {% endcontent-ref %} {% content-ref url="/pages/yecpZZZrz03pEiGYQiNa" %} [錯誤碼與重試](/documentation/api-can-kao/error-codes) {% endcontent-ref %} # 限流 說明 API key、endpoint 與方案層級的限流規則，以及超量時的回應方式。 為確保服務穩定、公平使用與企業級用量控管，BCS Intelligence API 會依照 API key、endpoint、客戶方案與請求頻率套用限流規則。 ## 限流維度 限流以「API key + endpoint」為主要單位。不同 API key、不同 endpoint 可依方案設定不同額度；高頻查詢、批次查詢、即時串流與 webhook 類功能可能採用不同限流規則。 額度由兩個參數決定，依你的方案設定： | 參數 | 意義 | | --------- | ------------ | | **RPS** | 每秒可穩定處理的請求數 | | **Burst** | 短時間內可累積的突發容量 | ## 超量時會發生什麼 當請求超過額度時，系統會依客戶方案與 endpoint 設定採用以下其中一種行為： {% tabs %} {% tab title="Reject（直接拒絕）" %} 立即回傳 `429 rate_limited`，並附上 `Retry-After` header 告訴你建議幾秒後重試。 ``` HTTP/1.1 429 Too Many Requests Retry-After: 3 ``` ```json { "error": { "code": "rate_limited", "message": "rate limited, retry after 3s" } } ``` {% endtab %} {% tab title="Wait（排隊等待）" %} 若 endpoint 或方案支援排隊模式，請求可在短時間內進入等待佇列，待額度釋放後繼續處理。 若等待佇列已滿、等待時間過長或服務進入保護狀態，系統會回傳 `503 service_unavailable`，請稍後重試。 {% endtab %} {% endtabs %} ## 最佳實務 • 遵守 Retry-After：收到 429 時，請等待指定秒數後再重試，不要立即連續重打。 • 採用指數退避：對 429、502、503 使用 exponential backoff，避免短時間大量重試造成雪崩。 • 控制並發數：在客戶端設定合理的 concurrency 上限，避免瞬間打滿 Burst 額度。 • 分散批次任務：大量地址、交易或資金流查詢應拆成批次，平滑送出請求。 • 記錄 request\_id：若發生 429、503 或非預期錯誤，請保留 meta.request\_id 或 X-Request-Id，方便追蹤。 {% hint style="info" %} 需要更高額度？可依使用場景申請更高 RPS、Burst、批次查詢或即時串流方案。量化、高頻監控與大型批次查詢建議預先評估流量模型。 {% endhint %} ## 下一步 {% content-ref url="/pages/pdZr13kdI275d1FWwSKR" %} [Credit 計費](/documentation/he-xin-gai-nian/credit-billing) {% endcontent-ref %} # Credit 計費 說明 API credit 的扣點規則、餘額回傳、餘額不足處理與用量對帳方式。 BCS API 採 credit 點數制計費。每把 API key 都有獨立的 credit 額度；系統會依 API endpoint、查詢成本與方案設定計算扣點。 Credit 用於控管 API 用量與成本，不代表實際法幣價格。實際方案、單價與加值方式依合約或報價單為準。 ## 核心原則 {% hint style="success" %} 核心原則 只有成功且需計費的 HTTP 2xx 回應才會扣除 credit。任何錯誤回應，包括 4xx 與 5xx，皆不扣點。 {% endhint %} • 不同 endpoint 依查詢成本設定不同扣點權重。例如基礎資料查詢成本較低，資金流追蹤、風險分析或市場行為分析成本較高。 • 管理後台、健康檢查與部分沙盒試用端點不扣點。 • 每次成功回應會在 response.meta 與部分 response header 中回傳本次扣點與剩餘額度。 ## 如何得知本次花費 成功回應會回傳本次扣點與剩餘額度。建議以 response.meta 作為系統對帳依據，response header 可作為即時監控與除錯輔助。 | 來源 | 欄位 | 意義 | | ------ | -------------------- | ---------------------------------------- | | `meta` | `credit_cost` | 本次請求扣除的 credit | | `meta` | `credit_remaining` | 扣點後的剩餘 credit | | Header | `X-Credit-Cost` | 本次請求扣除的 credit，對應 `meta.credit_cost` | | Header | `X-Credit-Remaining` | 扣點後的剩餘 credit，對應 `meta.credit_remaining` | ```json { "data": { "...": "..." }, "meta": { "credit_cost": 5, "credit_remaining": 9995 } } ``` ## 餘額不足 當剩餘 credit 不足以支付本次請求時，系統會回傳 402 insufficient\_credit。該請求不會被處理，也不會扣點。 ```json { "error": { "code": "insufficient_credit", "message": "insufficient credit: required 5, remaining 2" } } ``` 請聯絡管理員增加 credit、調整方案或切換至具足夠額度的 API key 後，再重新送出請求。 ## 對帳 每筆扣點紀錄都會寫入不可覆寫的用量帳本，並記錄 request\_id、API key、endpoint、扣點數、扣點後餘額與請求時間。客戶可依 request\_id 對應 API 回應、客服紀錄與內部交易流水，進行事後對帳與稽核。 {% hint style="info" %} 建議：客戶系統可在每次成功回應後讀取 meta.remaining\_credits 或 X-Credit-Remaining，並在額度低於內部門檻時觸發提醒，避免正式服務中斷。 {% endhint %} ## 下一步 {% content-ref url="/pages/JTozQ5Gb9ly2bavrljBP" %} [分頁](/documentation/he-xin-gai-nian/pagination) {% endcontent-ref %} # 分頁 說明列表型 API 的 limit / offset 分頁規則、回應格式與翻頁方式。 列表型端點使用 offset / limit 分頁。你可以透過 limit 控制每頁筆數，透過 offset 指定從第幾筆開始讀取。 ## 查詢參數 | 參數 | 預設 | 上限 | 說明 | | -------- | ---- | ------ | -------------- | | `limit` | `20` | `1000` | 每頁最多回傳筆數 | | `offset` | `0` | — | 起始位移，表示略過前幾筆資料 | ```bash curl "https://api.blockchainsecurity.asia/v1/webhooks?limit=50&offset=100" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` {% hint style="warning" %} limit 必須大於 0；若超過上限，系統會回傳 400 bad\_request。系統不會自動截斷超額 limit，避免客戶端誤以為已取得完整資料。 {% endhint %} ## 分頁中繼資訊 分頁資訊會出現在 response.meta.pagination 中： ```json { "data": [ /* ... */ ], "meta": { "pagination": { "limit": 50, "offset": 100, "total": 1342 } } } ``` | 欄位 | 說明 | | -------- | -------------------------- | | `limit` | 本次採用的每頁筆數 | | `offset` | 本次查詢的起始位移 | | `total` | 符合條件的總筆數；部分高成本或即時資料端點可能不提供 | ## 翻頁 要取得下一頁，將 offset 加上 limit： ``` 第 1 頁：offset=0, limit=50 第 2 頁：offset=50, limit=50 第 3 頁：offset=100, limit=50 ``` 當回傳筆數少於 limit，通常代表已到最後一頁。若 response.meta.pagination.total 存在，也可用 offset + limit >= total 判斷是否已無下一頁。 ## 最佳實務 最佳實務 • 固定查詢條件：翻頁期間請保持相同的查詢條件、排序與 filter，避免結果重複或遺漏。 • 避免過大 limit：較大的 limit 可能增加延遲與記憶體消耗；大量資料建議分批拉取。 • 記錄 offset：批次任務建議記錄最後成功處理的 offset，失敗時可從中斷位置繼續。 • 高變動資料需注意：交易、地址活動、資金流等資料可能持續新增；若需要穩定快照，建議搭配時間區間條件，例如 start\_time / end\_time。 ### 下一步 {% content-ref url="/pages/qnj2vPgmFyRFTLqtmCVj" %} [Webhook 訂閱](/documentation/events/webhooks) {% endcontent-ref %} # 幣種與鏈 查詢支援鏈別、資產清單與 Token Registry，並將 symbol 或合約地址解析為標準資產格式。 提供平台支援的鏈別、原生資產與 Token 資訊。此類端點屬於基礎資料查詢，不扣除 credit，但仍需使用 API key。 所有回應皆採用 { data, meta } 信封格式，請在 request header 帶入 X-API-Key。 ## 列出支援鏈別與資產 ```bash curl https://api.blockchainsecurity.asia/v1/chains \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": [ { "name": "ethereum", "token_addresses": [ { "name": "ETH", "symbol": "ETH", "address": "0x0", "decimals": 18, "verified": true }, { "name": "USDT", "symbol": "USDT", "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "decimals": 6, "verified": true } ] } ], "meta": { "request_id": "9b1c2d3e-..." } } ``` ## 完整 token registry ```bash curl https://api.blockchainsecurity.asia/v1/registry \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": { "tokens": [ { "chain": "ethereum", "symbol": "usdt", "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "decimals": 6, "usd_mode": "stable", "rate_symbol": null, "verified": true, "display_name": "USDT" } ] }, "meta": { "request_id": "..." } } ``` ## 查詢指定鏈資產 ```bash curl "https://api.blockchainsecurity.asia/v1/assets?chain=ethereum" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": { "chain": "ethereum", "assets": [ { "symbol": "usdt", "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "decimals": 6, "usd_mode": "stable", "rate_symbol": null } ] }, "meta": { "request_id": "..." } } ``` ## 解析 symbol / 合約 → 資產規格 將 symbol 或合約地址解析為標準資產格式，包含鏈別、資產符號、合約地址、decimals 與資產類型。原生資產的 contract\_address 為 null。 ```bash # 用 symbol curl -X POST https://api.blockchainsecurity.asia/v1/resolve \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"blockchain":"ethereum","symbols":["usdt","weth"]}' # contract-first（含原生幣 null） curl -X POST https://api.blockchainsecurity.asia/v1/resolve \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"blockchain":"tron","contracts":["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",null]}' ``` ```json { "data": { "blockchain": "tron", "assets": [ { "symbol": "trx", "contract": null, "decimals": 6, "usd_mode": "rate", "rate_symbol": "TRX" }, { "symbol": "usdt", "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "decimals": 6, "usd_mode": "stable", "rate_symbol": null } ] }, "meta": { "request_id": "..." } } ``` ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ------------------- | -------------------- | ------ | | `GET` | `/v1/chains` | 查詢支援鏈別與資產 | 0 | | `GET` | `/v1/registry` | 查詢完整 Token Registry | 0 | | `GET` | `/v1/assets?chain=` | 查詢指定鏈資產 | 0 | | `POST` | `/v1/resolve` | 解析 symbol 或合約地址為資產規格 | 0 | # 匯率行情 查詢幣種對 USD 的最新價格、指定時點價格與歷史價格序列。 查詢幣種對 USD 的參考價格，支援最新價格、指定時點價格與歷史價格序列。回應包含在 { data, meta } 信封。 ## 最新 / 指定時點查價 可一次查詢多個幣種；未帶 at 時回傳最新價格，帶 at 時回傳該時間點之前最近一筆價格。 ```bash # 最新價（多幣） curl "https://api.blockchainsecurity.asia/v1/rates?symbols=BTC,ETH" \ -H "X-API-Key: ak_live_YOUR_KEY" # 某時點（unix 秒） curl "https://api.blockchainsecurity.asia/v1/rates?symbols=BTC,ETH&at=1700000000" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` | 參數 | 必填 | 說明 | | --------- | -- | ----------------------- | | `symbols` | 是 | 逗號分隔幣種（如 `BTC,ETH`） | | `at` | 否 | 指定查價時間，Unix 秒；省略時回傳最新價格 | ```json { "data": { "at": 1700000000, "rates": [ { "symbol": "BTC", "price_usd": 37500.5, "ts": 1699999200 }, { "symbol": "ETH", "price_usd": 2050.5, "ts": 1699999200 } ] }, "meta": { "request_id": "..." } } ``` > 指定 at 時，系統回傳該時間點之前最近一筆可用價格，並在 ts 標示該筆價格的實際時間。此端點免費，不扣 credit。 ## 歷史序列 查詢單一幣種在指定時間區間內的 USD 歷史價格序列。成功扣除 5 credits。 ```bash curl "https://api.blockchainsecurity.asia/v1/rates/history?symbol=BTC&start=1700000000&end=1700086400" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": { "symbol": "BTC", "points": [ { "ts": 1700000000, "price_usd": 37500.5 }, { "ts": 1700003600, "price_usd": 37520.1 } ] }, "meta": { "request_id": "..." } } ``` 成功扣 **5 credit**。 ## 支援幣種列表 查詢目前可回傳 USD 價格資料的幣種清單。此端點免費，不扣 credit。 ```bash curl https://api.blockchainsecurity.asia/v1/rates/symbols \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": { "symbols": ["BTC","ETH","TRX","BNB","AVAX","MATIC"] }, "meta": { "request_id": "..." } } ``` **免費（0 credit）**。 ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | --------------------------------------- | ------------- | ------ | | `GET` | `/v1/rates?symbols=&at=` | 最新 / 指定時點價格查詢 | 0 | | `GET` | `/v1/rates/history?symbol=&start=&end=` | 歷史價格序列 | 5 | | `GET` | `/v1/rates/symbols` | 支援幣種列表 | 0 | # 地址活動查詢 查詢交易列表、交易對手、歷史餘額與地址總覽。 查詢單一地址的鏈上活動，包括交易列表、交易對手、歷史餘額與地址總覽。相關端點皆使用 POST，request body 為 JSON；成功回應扣除 5 credits，結果以 { data, meta } 信封回傳。 {% hint style="info" %} 帶 `symbols`（如 `["trx","usdt"]`）或 `contracts`（合約清單）指定要看的幣；省略則由平台依登錄處理。`start_time` / `end_time` 為 unix 秒。 {% endhint %} ## 交易列表 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/transactions \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "symbols": ["trx","usdt"], "direction": "All", "limit": 20, "page": 0 }' ``` ```json { "data": { "chain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "transactions": [ { "tx_hash": "8b5e...", "txn_type": "token", "amount": 2.0, "value": "2", "timestamp": 1764517689, "fee": 0, "from": { "address": "TEPS...", "chain": "tron" }, "to": { "address": "TMuA...", "chain": "tron" } } ], "page": 0, "limit": 20, "is_next_page": true }, "meta": { "request_id": "..." } } ``` ## 交易對手排行 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/counterparty \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "sort": "total_amount", "order": "desc", "limit": 50, "page": 1 }' ``` ```json { "data": { "datas": [ { "address": "TAUN6Fwr...", "total_count": 158, "sent_count": 20, "received_count": 138, "total_amount": 38038188656.7, "first_activity": 1533891705, "last_activity": 1630148922 } ], "pagination": { "limit": 50, "page": 1, "has_more": true } }, "meta": { "request_id": "..." } } ``` ## 兩地址之間的交易明細 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/counterparty/transfer-between \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "target": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "counterparty": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX" }' ``` ## 兩地址聚合統計 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/counterparty/overview \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "target": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "counterparty": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX" }' ``` ## 歷史餘額（每日） 回每日餘額變化與 `final_balance`。以單一資產為主（帶一個 `symbols`）。 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/balance-history \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "symbols": ["trx"] }' ``` ```json { "data": { "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "data_points": [ { "index": "0", "balance": "28811576.136503", "received": "28811577.1", "sent": "1.0", "date": "20180810", "timestamp": 1533859200 } ], "final_balance": "35.216514", "symbol": "trx" }, "meta": { "request_id": "..." } } ``` ## 地址總覽 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/wallet-overview \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9" }' ``` ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ----------------------------------- | ------- | ------ | | `POST` | `/v1/transactions` | 交易列表 | 5 | | `POST` | `/v1/counterparty` | 交易對手排行 | 5 | | `POST` | `/v1/counterparty/transfer-between` | 兩地址交易明細 | 5 | | `POST` | `/v1/counterparty/overview` | 兩地址聚合統計 | 5 | | `POST` | `/v1/balance-history` | 歷史餘額 | 5 | | `POST` | `/v1/wallet-overview` | 地址總覽 | 5 | # 持有者與集中度 Token 持有者排行與持有集中度（HHI / Gini / Top-N 占比）。 分析某個 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 | # 地址標籤與身分 查詢地址的情報標籤（交易所、混幣器、風險等）。 查詢地址在各情報來源中的標籤、分類與來源狀態，例如交易所、混幣器、詐騙、制裁或其他風險相關標籤。成功回應扣除 5 credits，結果以 { data, meta } 信封回傳。 ## 查標籤 ```bash curl "https://api.blockchainsecurity.asia/v1/labels?chain=ethereum&address=0x28c6c06298d514db089934071355e5743bf21d60" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` | 參數 | 必填 | 說明 | | --------- | -- | --------------------------------------------- | | `chain` | 是 | 鏈別（ethereum / bsc / tron / bitcoin …） | | `address` | 是 | 查詢地址 | | `intent` | 否 | 查詢意圖：`label`（預設）＝命中且信心足即回傳；`deep`＝所有來源照查 | | `sources` | 否 | 來源；省略=預設來源，`all`=全部，或逗號分隔 | | `refresh` | 否 | 是否要求重新查詢來源；true 時會盡量跳過快取，但仍可能受來源可用性、限流或方案權限影響 | ```json { "data": { "chain": "ethereum", "address": "0x28c6c06298d514db089934071355e5743bf21d60", "label": { "entity_name": "Binance", "category": "entity_actor", "labels": ["Binance", "hot"], "confidence": 1.0, "verified": true, "hit_tier": "first_party" }, "needs_deep_analysis": false, "results": [ { "source": "first_party", "status": "ok", "category": "entity_actor", "name": "Binance", "labels": ["Binance", "hot"], "verified": true, "raw": { "...": "原始來源回應" }, "fetched_at": 1700000000, "cached": false } ], "fetched_at": 1700000000 }, "meta": { "request_id": "..." } } ``` `data.label` 為跨來源彙整後的綜合標籤，適合直接顯示： | 欄位 | 說明 | | ------------- | --------------------------- | | `entity_name` | 實體名稱（如 Binance） | | `category` | 正規化分類 | | `labels` | 標籤清單 | | `confidence` | 信心分數（0–1） | | `verified` | 是否經過驗證 | | `hit_tier` | 命中層級（如 `first_party`＝自有情資庫） | `data.needs_deep_analysis` 為布林值：true 表示標籤資訊不足，建議再走 `/v1/address-risk` 等深度分析。 `results` 為各來源明細陣列，每個來源同一外殼： | 欄位 | 說明 | | ---------- | -------------------------------------- | | `source` | 來源名稱（如 `first_party`） | | `status` | `ok` / `unknown` / `error` / `timeout` | | `category` | 正規化分類（exchange / mixer …） | | `name` | 名稱（如 Binance） | | `labels` | 標籤清單 | | `verified` | 該來源結果是否經過驗證 | | `raw` | raw｜來源回應摘要或原始欄位保留，實際內容依來源而定 | | `cached` | 是否使用快取結果 | ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ------------ | ------ | ------ | | `GET` | `/v1/labels` | 地址標籤查詢 | 5 | # 地址風險評分 對地址完整歷史跑行為偵測，回傳風險分數、等級與觸發的可疑行為。 對單一地址進行歷史交易行為分析，偵測快速進出、分散轉出、一次性錢包、分層歸集與中轉型資金流等可疑行為，並加權產出風險分數與風險等級。 目前支援 `ethereum` 與 `tron`。 ## 評估風險 ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/address-risk" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9" }' ``` {% hint style="warning" %} 本端點會掃描地址的完整歷史。交易量極大的地址（如交易所熱錢包）可能因上游查詢資源上限回傳 5xx，建議此類地址改用[地址標籤](/documentation/risk-and-intelligence/labels)判別身分。 {% endhint %} 請求 body： | 欄位 | 必填 | 說明 | | ------------ | -- | --------------------------------------------- | | `blockchain` | 是 | 鏈別，目前僅 `ethereum` / `tron` | | `address` | 是 | 要評估的地址 | | `symbols` | 否 | 納入評估的幣種 symbol 清單；省略時自動採用原生幣與主要穩定幣 | | `contracts` | 否 | contract-first：以合約位址指定幣種（與 `symbols` 二擇一，較防偽） | ```json { "data": { "chain": "tron", "address": "TMuA6YqfCeX8EhbfYEg5y7S4DqzSJireY9", "risk_score": 26.78, "risk_level": "low", "risk_level_zh": "低", "behaviors": [ { "code": "rapid_in_out", "name_zh": "快速進出", "severity": "high", "score": 12.0, "base_weight": 30.0, "intensity": 1.0, "recency_weight": 0.4, "occurrence_count": 8, "first_detected_at": 1584086703, "last_detected_at": 1638244803, "ever_detected": true, "evidence": { "in_amount_usd": 3412848.81, "out_amount_usd": 616634422.08, "out_ratio": 9.99, "window_minutes": 30 } } ], "score_breakdown": { "rapid_in_out": 12.0, "burner_wallet": 8.0, "pass_through": 6.78, "total_raw": 26.78, "capped_total": 26.78 }, "evaluated_behaviors": ["rapid_in_out", "burner_wallet"], "deferred_behaviors": ["drainer_pattern", "risky_contract_interaction"], "data_window": { "from": 1533891705, "to": 1764517689, "tx_count": 1132 } }, "meta": { "request_id": "..." } } ``` | 欄位 | 說明 | | ------------------------------ | --------------------------------------------------------------------------- | | `risk_score` | 綜合風險分數（0–100，越高越可疑） | | `risk_level` / `risk_level_zh` | 風險等級：`low` / `medium` / `high`（附中文） | | `behaviors` | 觸發的可疑行為清單 | | `behaviors[].code` | 行為代碼（如 `rapid_in_out`、`burner_wallet`、`pass_through`、`layered_aggregation`） | | `behaviors[].score` | 該行為的加權後分數（`base_weight` × `intensity` × `recency_weight`） | | `behaviors[].evidence` | 觸發該行為的量化證據（金額、比例、時間窗等，依行為而異） | | `behaviors[].occurrence_count` | 歷史上偵測到的次數，`first/last_detected_at` 為首末次時間 | | `score_breakdown` | 各行為分數與加總（`capped_total` 為封頂後總分） | | `evaluated_behaviors` | 本次已評估的行為偵測器 | | `deferred_behaviors` | 本次未評估（延後）的偵測器 | | `data_window` | 分析涵蓋的時間範圍與交易筆數 | > 較舊的行為會依時間遞減權重，因此分數反映的是加權後的整體歷史風險，而非單一事件判斷。 ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ------------------ | ----------- | ------ | | `POST` | `/v1/address-risk` | 地址風險評分與行為分析 | 5 | # 地址類型分類 用機器學習判斷一批地址的類型（交易所 / DeFi / 混幣器等），並附信心分數。 批次判斷地址類型，例如交易所、DeFi、混幣器、服務地址或未知地址，並回傳信心分數，輔助盡職調查與風險篩查。成功回應扣除 5 credits，結果以 { data, meta } 信封回傳。 單次最多 **100** 個地址。 ## 分類地址 ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/address-classify" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "addresses": ["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"] }' ``` 請求 body： | 欄位 | 必填 | 說明 | | ------------ | -- | ---------------------------------- | | `blockchain` | 否 | tron / ethereum / bitcoin（預設 tron） | | `addresses` | 是 | 要分類的地址清單，1–100 筆，不可為空 | ```json { "data": { "results": [ { "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "predicted_class": "exchange", "confidence": 0.97, "error": null } ] }, "meta": { "request_id": "..." } } ``` | 欄位 | 說明 | | --------------------------- | --------------------------------------- | | `results` | 逐一對應輸入地址的分類結果陣列 | | `results[].address` | 對應的地址 | | `results[].predicted_class` | 預測類型（如 `exchange` / `defi` / `mixer` …） | | `results[].confidence` | 信心分數，範圍 0–1，越高代表分類越有把握 | | `results[].error` | 該地址若無法分類時的錯誤訊息；成功時為 null | ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ---------------------- | ------ | ------ | | `POST` | `/v1/address-classify` | 地址類型分類 | 5 | # 多跳資金追蹤 從一個地址多跳展開向外 / 向內的金流路徑，自動釐清資金最終流向。 從一個地址出發，向外或向內逐跳展開資金流向，協助釐清資金來源、去向與多層交易路徑。 可依鏈別、幣別、金額、時間範圍與追蹤深度進行篩選。此查詢屬於較重的分析型端點，成功回應扣除 5 credits，結果會以 data 與 meta 回傳。 {% hint style="warning" %} 此端點屬於較重的分析查詢。追蹤深度、時間範圍與 limit 越大，處理時間越長。請預留較長 timeout；回應為一次性 JSON 結果。 {% endhint %} 支援鏈：`tron`、`ethereum`、`bitcoin`。 ## 追蹤資金流向 ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/trace" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "blockchain": "tron", "address": "TDZmNAhbGrrSzZZ8JJx1E3YhnSQ9TZQtYy", "track_setting": { "startTime": 1721145600, "endTime": 1721318399, "outbound_depth": 3, "inbound_depth": 1, "limit": 5, "enable_amount_aggregation": true }, "filter_criterias": [ { "symbol": "usdt", "min_value": 496, "max_value": 700, "sign": "range" } ] }' ``` 請求 body： | 欄位 | 必填 | 說明 | | ---------------------- | -- | ----------------------------------- | | `blockchain` | 是 | 鏈別（`tron` / `ethereum` / `bitcoin`） | | `address` | 是 | 起始追蹤地址 | | `track_setting` | 否 | 追蹤深度、時間範圍與結果上限設定 | | `filter_criterias` | 否 | 金額、幣別或交易條件篩選 | | `stop_track_condition` | 否 | 達到指定深度、金額低於門檻、命中特定地址類型或超過時間範圍。 | `track_setting` 內欄位： | 欄位 | 說明 | | --------------------------- | -------------- | | `startTime` / `endTime` | 追蹤時間範圍（Unix 秒） | | `outbound_depth` | 向外（資金流出）追蹤深度 | | `inbound_depth` | 向內（資金流入）追蹤深度 | | `limit` | 每跳展開的筆數上限 | | `enable_amount_aggregation` | 是否啟用金額累計彙整 | `filter_criterias[]` 內欄位： | 欄位 | 說明 | | ------------------------- | --------------- | | `symbol` | 幣種 symbol | | `min_value` / `max_value` | 金額下 / 上限 | | `sign` | 比較方式（如 `range`） | ```json { "data": { "result": { "transactions": [ { "hash": "0x...", "from": "TDZmNAhbGrrSzZZ8JJx1E3YhnSQ9TZQtYy", "to": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX", "symbol": "usdt", "value": 500.0, "timestamp": 1721200000, "depth": 1, "direction": "outbound" } ], "normal": [], "token": [] } }, "meta": { "request_id": "..." } } ``` | 欄位 | 說明 | | --------------------- | ----------------------------------- | | `result.transactions` | 展開路徑上的交易節點，包含 depth 與 direction | | `result.normal` | 原生幣轉帳，例如 ETH、TRX、BTC | | `result.token` | Token 轉帳，例如 USDT、USDC、ERC-20、TRC-20 | ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ----------- | ------ | ------ | | `POST` | `/v1/trace` | 資金流向追蹤 | 5 | # Bitcoin 找零地址偵測 偵測 Bitcoin 交易中的找零地址，推定付款輸出與找零輸出。 偵測一筆 Bitcoin 交易中的找零地址，協助判斷哪些輸出可能為付款方找零、哪些輸出可能為收款方地址，進一步推定該筆交易的資金流向。成功回應扣除 5 credits，結果以 { data, meta } 信封回傳。 ## 找零地址偵測 ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/btc/change-address" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "txid": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16" }' ``` 請求 body： | 欄位 | 必填 | 說明 | | ------ | -- | ------------------- | | `txid` | 是 | Bitcoin 交易 ID（txid） | ```json { "data": { "txid": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16", "change_address": "12cbQLTHMqcyjg2b7ZdvD8gnF5jPbE2yz", "change_index": 1, "confidence": 0.82, "reasons": ["address_reuse", "round_number_payment"] }, "meta": { "request_id": "..." } } ``` | 欄位 | 說明 | | ---------------- | --------------------------------------------------------------------------------------- | | `change_address` | 推定為找零的輸出地址；無法判斷時可能為 `null` | | `change_index` | 找零輸出在交易 outputs 中的索引 | | `confidence` | 判定信心分數，範圍 0–1 | | `reasons` | 判定依據，例如 `address_reuse`、`script_type_match`、`round_number_payment`、`new_output_address` | > 找零偵測屬啟發式判定，confidence 代表本次推定的可信度；當交易結構過於複雜或證據不足時，change\_address 可能回傳 null。 ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ------------------------ | -------------- | ------ | | `POST` | `/v1/btc/change-address` | Bitcoin 找零地址偵測 | 5 | # 跨鏈追蹤 追蹤一筆交易的資金跨鏈去向，跨到別條鏈也能接上來源鏈與目的鏈。 追蹤一筆交易的資金跨鏈去向：當資金透過跨鏈橋轉到另一條鏈時，也能接上並還原來源鏈、目的鏈與兩端的交易與收付地址。成功扣除 **5 credit**，回應包在 `{ data, meta }` 信封。 查詢需要來源交易 txhash，以及跨鏈協議或橋接服務識別 label，例如 `across`、`axelar`、`celer`、`wormhole`。查無結果時回 `404`。 ## 單筆追蹤 ```bash curl "https://api.blockchainsecurity.asia/v1/cross-chain?txhash=0x11ce7a536a3ec57699c918ecd43424ea97b928cfee38508814b40e48cb79fe15&label=across" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` | 參數 | 必填 | 說明 | | -------- | -- | --------------------------- | | `txhash` | 是 | 來源交易 hash | | `label` | 是 | protocol label（協定關鍵字，用來比對橋） | ```json { "data": { "results": [ { "label": "Across Protocol", "result": { "source_chain": "Arbitrum", "destination_chain": "Hyperliquid", "source_tx_hash": "0x11ce7a536a3ec57699c918ecd43424ea97b928cfee38508814b40e48cb79fe15", "destination_tx_hash": "0x6133d3c95096173c0b96be38612133af52e4c4ed05eb703639ca85b7dad99397", "sender_address": "0xd0d80284e8db5b36373185b9ecaabe43350306e3", "receiver_address": "0xd0d80284e8db5b36373185b9ecaabe43350306e3" } } ] }, "meta": { "request_id": "..." } } ``` | 欄位 | 說明 | | --------------------------------------------------------- | ----------- | | `results[].label` | 比對到的跨鏈橋協定名稱 | | `results[].result.source_chain` / `destination_chain` | 來源鏈 / 目的鏈 | | `results[].result.source_tx_hash` / `destination_tx_hash` | 兩端交易 hash | | `results[].result.sender_address` / `receiver_address` | 兩端收付地址 | ## 批次追蹤 一次追蹤多筆，省去逐筆呼叫。 ```bash curl -X POST "https://api.blockchainsecurity.asia/v1/cross-chain/batch" \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "queries": [ { "txhash": "0x11ce7a536a3ec57699c918ecd43424ea97b928cfee38508814b40e48cb79fe15", "label": "across" } ] }' ``` 請求 body： | 欄位 | 必填 | 說明 | | --------- | -- | -------------------------------- | | `queries` | 是 | 查詢清單，不可為空，每筆含 `txhash` 與 `label` | 回應為各筆查詢的跨鏈交易詳情陣列，欄位同單筆。 ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ----------------------- | ------ | -------- | | `GET` | `/v1/cross-chain` | 單筆跨鏈追蹤 | 5 | | `POST` | `/v1/cross-chain/batch` | 批次跨鏈追蹤 | 5/ 筆成功查詢 | # 地址工具 地址驗證、糾錯與前綴自動完成。 協助使用者在輸入階段就拿到正確完整的地址：`resolve` 驗證地址格式並對打錯的地址回傳相似候選，`autocomplete` 依前綴即時補全，適合搜尋框的 type-ahead 場景。 ## 地址驗證 / 相似候選（resolve） 驗證一個地址是否符合指定鏈別格式；若未完全命中，可回傳相似候選。成功回應扣除 5 credits。 ```bash curl "https://api.blockchainsecurity.asia/v1/addresses/resolve?chain=tron&q=TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` | 參數 | 必填 | 說明 | | ------- | -- | ---------------------------------------------- | | `q` | 是 | 要驗證或修正的地址 | | `chain` | 否 | 鏈別，例如 `tron`、`ethereum`、`bitcoin`；省略時僅做格式與候選推斷 | | `limit` | 否 | 相似候選數上限 | ```json { "data": { "query": "TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z", "chain": "tron", "match": true, "candidates": [], "total": 0, "took_ms": 3 }, "meta": { "request_id": "..." } } ``` > match: true 表示輸入地址通過驗證或完全命中；match: false 時，candidates 會列出相似候選地址，供使用者確認是否輸入錯誤。 ## 自動完成（autocomplete） 依地址前綴回傳候選清單，適合用於搜尋框自動完成。此端點不扣除 credit；q 至少 5 個字元。 ```bash curl "https://api.blockchainsecurity.asia/v1/addresses/autocomplete?chain=tron&q=TXgXcJ" \ -H "X-API-Key: ak_live_YOUR_KEY" ``` ```json { "data": { "query": "TXgXcJ", "chain": "tron", "candidates": ["TXgXcJwxbDsDfTHq3BSZagZor4Dg74tb5Z"], "total": 1 }, "meta": { "request_id": "..." } } ``` ## 端點與計費 | Method | 路徑 | 說明 | Credit | | ------ | ---------------------------- | --------- | ------ | | `GET` | `/v1/addresses/resolve` | 地址驗證與相似候選 | 5 | | `GET` | `/v1/addresses/autocomplete` | 地址前綴自動完成 | 0 | # Webhook 訂閱 訂閱鏈上事件、地址風險變化、資金流異常與市場行為訊號，並以 HMAC 簽章驗證推送來源。 Webhook 讓你在指定事件發生時主動收到通知，而不必持續輪詢 API。你可以登記一個接收網址，當符合條件的地址活動、風險變化、制裁命中、資金流異常或市場訊號出現時，系統會以 HTTP POST 推送事件。 所有 webhook 管理端點都需要 API key 認證，且只會操作該 key 名下的訂閱。 ## 建立訂閱 ```bash curl -X POST https://api.blockchainsecurity.asia/v1/webhooks \ -H "X-API-Key: ak_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "target_url": "https://your-app.example/webhooks/events", "event_type": "large_transfer" }' ``` | 欄位 | 必填 | 說明 | | ------------ | -- | ------------------------------------------------------------ | | `target_url` | 是 | 接收事件的網址，須以 `http://` 或 `https://` 開頭（正式環境請用 HTTPS），長度上限 2048 | | `event_type` | 是 | 訂閱的事件類型，1–64 字元，例如 `large_transfer`、`address_activity` | 回應包含一次性的 **`secret`**，用於驗證後續推送的來源： ```json { "data": { "id": "b2c3d4e5-...", "target_url": "https://your-app.example/webhooks/events", "event_type": "large_transfer", "status": "active", "created_at": "2026-06-02T08:00:00Z", "secret": "whsec_1a2b3c..." }, "meta": { "request_id": "..." } } ``` {% hint style="warning" %} secret 只會在建立訂閱時回傳一次，請立即保存於伺服器端密鑰管理服務。若遺失 secret，請撤銷該 webhook 後重新建立。 {% endhint %} ## 列出訂閱 ```bash curl https://api.blockchainsecurity.asia/v1/webhooks \ -H "X-API-Key: ak_live_YOUR_KEY" ``` 回傳該 API key 名下的所有訂閱；基於安全性，不會回傳 secret。 ## 刪除訂閱 ```bash curl -X DELETE https://api.blockchainsecurity.asia/v1/webhooks/{id} \ -H "X-API-Key: ak_live_YOUR_KEY" ``` 成功刪除回傳 204 No Content；若找不到該訂閱，回傳 404 not\_found。 ## 驗證 webhook 來源 每則推送都會以你的 `secret` 對 payload 做 HMAC 簽章。接收端應重新計算簽章並比對，確認事件確實來自本服務、且未被竄改。請以**常數時間比較**避免時序攻擊。 {% hint style="info" %} 請務必驗證簽章後再處理事件，切勿信任任何未通過驗證的請求。 {% endhint %} ## 下一步 {% content-ref url="/pages/ESdXtvmrmcsnU9CHeYy8" %} [即時串流](/documentation/events/streaming) {% endcontent-ref %} # 即時串流 透過 WebSocket 建立長連線，接收即時事件。 除了 Webhook 之外，你也可以透過 **WebSocket** 建立一條長連線，即時接收事件推送。當你需要持續、低延遲的串流（而非逐筆 HTTP 回呼）時，這是更合適的選擇。 ## 連線 端點為 `GET /v1/stream`，升級為 WebSocket。連線需通過 API key 認證——在升級請求的 header 帶上 `X-API-Key`。 {% tabs %} {% tab title="JavaScript" %} ```javascript // 以支援自訂 header 的 WebSocket client 為例 const ws = new WebSocket("wss://api.blockchainsecurity.asia/v1/stream", { headers: { "X-API-Key": "ak_live_YOUR_KEY" }, }); ws.on("message", (data) => { console.log("event:", data.toString()); }); ``` {% endtab %} {% tab title="Python" %} ```python import websocket ws = websocket.create_connection( "wss://api.blockchainsecurity.asia/v1/stream", header=["X-API-Key: ak_live_YOUR_KEY"], ) print(ws.recv()) # welcome 訊息 ``` {% endtab %} {% endtabs %} ## 連線後的訊息 連線建立後，伺服器會先送一則 **welcome** 訊息，確認連線與身分： ```json { "type": "welcome", "key": "ak_live_3f9a2c7b" } ``` 之後，符合你訂閱條件的事件會以 JSON 訊息推送到這條連線上。 ## 保持連線 * 送出文字訊息 `ping`，伺服器會回 `pong`，可用於保活與偵測斷線。 * 收到 `Close` 或連線中斷時，請以退避策略重新連線。 {% hint style="info" %} WebSocket 與 Webhook 可擇一或併用：Webhook 適合無狀態、可水平擴展的接收端；WebSocket 適合需要持續低延遲串流的場景。 {% endhint %} # 端點總覽 所有端點的速查表（含 Credit 成本），以及線上互動式文件。 本頁彙整主要端點、用途與 Credit 成本。完整請求格式、回應範例與線上試打介面，請參考互動式 API 文件。 {% hint style="success" %} 互動式 API 文件：可至 /docs 瀏覽並測試端點；原始 OpenAPI 規格位於 /api-docs/openapi.json。 {% endhint %} 所有資料平面端點需在 header 帶 `X-API-Key`，回應為 `{ data, meta }` 信封。成功（2xx）才扣 Credit。 ## Assets & Market Data（資產與行情） 詳見[幣種與鏈](/documentation/assets-and-market-data/assets)、[匯率行情](/documentation/assets-and-market-data/rates)。 | Method | 路徑 | 說明 | Credit | | ------ | --------------------------------------- | ----------------- | ------ | | `GET` | `/v1/chains` | 支援的鏈與幣種 | 0 | | `GET` | `/v1/registry` | 完整 token registry | 0 | | `GET` | `/v1/assets?chain=` | 某鏈的代幣 | 0 | | `POST` | `/v1/resolve` | symbol／合約 → 資產規格 | 0 | | `GET` | `/v1/rates?symbols=&at=` | 時點 / 最新查價（批次） | 0 | | `GET` | `/v1/rates/history?symbol=&start=&end=` | 歷史價序列 | 5 | | `GET` | `/v1/rates/symbols` | 有資料的幣種 | 0 | ## On-chain Data（鏈上數據） 詳見[地址活動](/documentation/on-chain-data/address-activity)、[持有者與集中度](/documentation/on-chain-data/token-holders)。持有者與集中度是較重的查詢，Credit 權重較高。 | Method | 路徑 | 說明 | Credit | | ------ | ----------------------------------- | ------------------------- | ------ | | `POST` | `/v1/transactions` | 交易列表 | 5 | | `GET` | `/v1/transaction/{hash}` | 單筆交易完整明細 | 0 | | `POST` | `/v1/counterparty` | 交易對手排行 | 5 | | `POST` | `/v1/counterparty/transfer-between` | 兩地址交易明細 | 5 | | `POST` | `/v1/counterparty/overview` | 兩地址聚合統計 | 5 | | `GET` | `/v2/counterparty/list` | 交易對手清單（Bitcoin 加速版） | 5 | | `POST` | `/v1/balance-history` | 每日歷史餘額 | 5 | | `POST` | `/v1/wallet-overview` | 地址總覽 | 5 | | `GET` | `/v1/token/holders` | 持有者排行 | 10 | | `GET` | `/v1/token/concentration` | 持有集中度（HHI / Gini / Top-N） | 15 | | `GET` | `/v1/token/addresses_flow` | 多地址資金流量聚合 | 5 | ## Risk & Intelligence（風險與情資） 詳見[地址標籤](/documentation/risk-and-intelligence/labels)、[地址風險](/documentation/risk-and-intelligence/address-risk)、[地址分類](/documentation/risk-and-intelligence/classification)。 | Method | 路徑 | 說明 | Credit | | ------ | ---------------------- | ------------------- | ------ | | `GET` | `/v1/labels` | 地址情報標籤 | 5 | | `POST` | `/v1/address-risk` | 行為風險評分（0–100）與可疑行為 | 5 | | `POST` | `/v1/address-classify` | ML 地址類型分類（批次最多 100） | 5 | ## Investigation（調查追蹤） 詳見[智能追蹤](/documentation/investigation/trace)、[Bitcoin 分析](/documentation/investigation/bitcoin)。 | Method | 路徑 | 說明 | Credit | | ------ | ------------------------ | ----------------- | ------ | | `POST` | `/v1/trace` | 多跳金流路徑展開（向外 / 向內） | 5 | | `POST` | `/v1/btc/change-address` | Bitcoin 找零地址偵測 | 5 | ## Cross-chain（跨鏈追蹤） 詳見[跨鏈追蹤](/documentation/cross-chain/cross-chain)。 | Method | 路徑 | 說明 | Credit | | ------ | ----------------------- | -------- | ------ | | `GET` | `/v1/cross-chain` | 單筆交易跨鏈追蹤 | 5 | | `POST` | `/v1/cross-chain/batch` | 批次跨鏈追蹤 | 5 | ## Address Utilities（地址工具） 詳見[地址工具](/documentation/address-utilities/search)。 | Method | 路徑 | 說明 | Credit | | ------ | ---------------------------- | --------- | ------ | | `GET` | `/v1/addresses/resolve` | 地址驗證 / 糾錯 | 5 | | `GET` | `/v1/addresses/autocomplete` | 前綴自動完成 | 0 | ## Events（事件訂閱） 詳見 [Webhook 訂閱](/documentation/events/webhooks)、[即時串流](/documentation/events/streaming)。 | Method | 路徑 | 說明 | Credit | | -------- | ------------------- | ---------------- | ------ | | `GET` | `/v1/webhooks` | 列出 webhook 訂閱 | 0 | | `POST` | `/v1/webhooks` | 建立 webhook 訂閱 | 0 | | `DELETE` | `/v1/webhooks/{id}` | 刪除 webhook 訂閱 | 0 | | `GET` | `/v1/stream` | WebSocket 即時事件串流 | 0 | ## System（系統端點，免認證） | Method | 路徑 | 說明 | | ------ | ------------------------ | --------------- | | `GET` | `/healthz` | 存活檢查（liveness） | | `GET` | `/readyz` | 就緒檢查（readiness） | | `GET` | `/docs` | 互動式 API 文件 | | `GET` | `/api-docs/openapi.json` | OpenAPI 規格 | ## 共通約定 | 項目 | 約定 | | ---- | -------------------------------------------------- | | 認證 | 資料平面 `X-API-Key` | | 成功回應 | `{ data, meta }` 信封 | | 錯誤回應 | `{ error: { code, message } }` 信封 | | 計費 | 成功（2xx）才扣；回應帶 `X-Credit-Cost`、`X-Credit-Remaining` | | 追蹤 | 回應帶 `X-Request-Id` | # 錯誤碼與重試 所有錯誤碼、對應 HTTP 狀態與處理建議。 所有錯誤回應皆採用一致結構，並回傳可供程式判斷的錯誤碼。請以 error.code 作為邏輯判斷依據；error.message 僅供顯示與紀錄，不建議作為程式分支條件。 | HTTP | `code` | 意義 | 處理方式 | | ---- | --------------------- | -------------- | ------------------- | | 400 | `bad_request` | 參數或格式錯誤 | 修正請求後重送 | | 401 | `unauthorized` | 缺少或無效的 API key | 檢查 `X-API-Key` | | 402 | `insufficient_credit` | credit 餘額不足 | 加值後重試 | | 403 | `forbidden` | 無權限（如 key 已停用） | 聯絡管理員 | | 404 | `not_found` | 資源不存在 | 檢查路徑或 ID | | 429 | `rate_limited` | 觸發限流 | 依 `Retry-After` 重試 | | 500 | `internal_error` | 內部錯誤 | 附 `X-Request-Id` 回報 | | 502 | `upstream_error` | 後端服務異常 | 退避後重試 | | 503 | `service_unavailable` | 暫時無法處理（如佇列已滿） | 稍後重試 | ## 錯誤回應 header | 錯誤 | header | 意義 | | ------------------ | ------------- | --------- | | `429 rate_limited` | `Retry-After` | 建議等待秒數後重試 | ## 範例 以下為觸發限流時的錯誤回應範例： ```json { "error": { "code": "rate_limited", "message": "rate limited, retry after 3s" } } ``` 延伸閱讀：[錯誤處理](/documentation/he-xin-gai-nian/errors)。 # 限制與配額 請求、分頁與輸入欄位的限制。 下列為平台層級限制與方案型額度。固定限制適用於所有 API key；RPS、Burst 與 Credit 配額則依方案設定而定。 ## 分頁 | 項目 | 值 | | ---------- | ------------------------ | | `limit` 預設 | 20 | | `limit` 上限 | 1000 | | 超過上限 | 回 `400 bad_request`（不截斷） | ## 限流與方案配額 | 項目 | 說明 | | ----- | --------------------------- | | 維度 | 每 API key + 端點 | | RPS | 每秒請求數，依方案 | | Burst | 突發容量，依方案 | | 超量行為 | `reject`（回 429）或 `wait`（排隊） | 詳見[限流](/documentation/he-xin-gai-nian/rate-limiting)。 ## Credit 計費 | 項目 | 說明 | | ---- | --------------------------------------------- | | 計費時機 | 僅成功回應（HTTP 2xx）扣 Credit | | 餘額不足 | 回 `402 insufficient_credit` | | 每月配額 | 依方案 `monthly_credit_quota` | | 餘額回傳 | 成功回應會帶 `X-Credit-Cost` 與 `X-Credit-Remaining` | ## 輸入欄位限制 | 欄位 | 限制 | | -------------------- | -------------------------------------- | | Webhook `target_url` | 須以 `http://` 或 `https://` 開頭，長度 ≤ 2048 | | Webhook `event_type` | 1–64 字元 | | `X-Request-Id`（自帶） | ≤ 128 字元，僅限英數、`-`、`_` | ## 請求限制 | 項目 | 說明 | | ------ | --------------------------------------------------- | | 請求逾時 | 超過處理時間上限時，回 HTTP `408`（此回應由基礎設施層產生，不帶 `{error}` 信封） | | 請求主體大小 | 超過大小上限時，回 HTTP `413`（同上，不帶 `{error}` 信封） | {% hint style="info" %} 逾時與主體大小上限可依部署環境設定，正式環境的實際值請洽你的客戶經理。 {% endhint %} # 名詞解釋 本文件常用名詞。 **API gateway** ：應用程式存取各項服務的統一入口，負責認證、限流、計費、審計等橫切功能。 **API key** ：資料平面的認證金鑰，以 `ak_live_` 開頭，放在 `X-API-Key` header。系統只保存其雜湊值。 **資料平面（data plane）** ：應用程式呼叫的業務 API（如 `/v1/*`），以 API key 認證並計費。 **控制平面（control plane）** ：管理員用的後台，以帳號密碼登入，管理 key、credit 與方案。 **Credit（點數）** ：用量計費的單位。每把 key 有自己的餘額，成功呼叫時依端點權重扣點。 **Cost weight（成本權重）** ：各端點扣除的 credit 數量；管理／系統端點為 0。 **Plan（方案）** ：一組共用的限流（RPS／Burst）與 credit 規則，建立 key 時指定。 **RPS** ：每秒請求數（requests per second），限流的速率參數。 **Burst（突發容量）** ：短時間內可累積的請求容量，超出穩定速率時的緩衝。 **回應信封（envelope）** ：統一的回應外層結構——成功為 `{ data, meta }`，錯誤為 `{ error }`。 **`meta`** ：回應信封中的中繼資訊，可能含 `request_id`、`pagination`、`credit_cost`、`credit_remaining`。 **Request ID** ：每個請求的追蹤碼，見於 `X-Request-Id` header 與 `meta.request_id`，用於對帳與客服。 **Webhook** ：事件發生時，由本服務主動以 HTTP POST 推送到你登記的網址，並以 HMAC 簽章驗證來源。 **Secret（webhook 密鑰）** ：用來驗證 webhook 簽章的金鑰，建立訂閱時一次性回傳。 # API 參考 本文件為依據 OpenAPI 規格產生的 BCS API 參考指南。 本空間的 BCS API 參考文件依據 OpenAPI 規格生成，內容隨服務自動保持同步。 * **OpenAPI 規格**：[`/api-docs/openapi.json`](https://api.blockchainsecurity.asia/api-docs/openapi.json) # Assets & Market Data 資產與價格資料：查詢平台支援的區塊鏈與資產、解析資產識別，並取得目前或歷史美元價格。不確定該用哪一支？查支援範圍用 chains；查指定鏈資產用 assets；一次同步全部資產用 registry；確認資產識別用 resolve；查價格用 rates。 # 支援鏈總覽 列出平台目前支援的區塊鏈與各鏈可用資產，適合快速確認整體支援範圍。 ## GET /v1/chains > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"列出平台目前支援的區塊鏈與各鏈可用資產，適合快速確認整體支援範圍。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/chains":{"get":{"operationId":"assets.chains.v1","responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳支援的鏈與各鏈可用代幣"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["支援鏈總覽"]}}}} ``` # 完整資產清單 一次取得平台跨鏈資產的完整規格，包括合約地址、精度與驗證狀態。適合建立本地資產對照表或定期同步資產資料。 ## GET /v1/registry > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"一次取得平台跨鏈資產的完整規格，包括合約地址、精度與驗證狀態。適合建立本地資產對照表或定期同步資產資料。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/registry":{"get":{"operationId":"assets.registry.v1","responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳完整代幣清單"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["完整資產清單"]}}}} ``` # 指定鏈資產清單 查詢指定區塊鏈目前支援的資產，包括資產代碼、合約地址、精度與計價設定。適合在後續價格或鏈上資料查詢前確認正確參數。 ## GET /v1/assets > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢指定區塊鏈目前支援的資產，包括資產代碼、合約地址、精度與計價設定。適合在後續價格或鏈上資料查詢前確認正確參數。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/assets":{"get":{"operationId":"assets.list.v1","parameters":[{"description":"鏈別，例如 ethereum / bsc / tron","in":"query","name":"chain","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳該鏈支援的代幣"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供有效且支援的鏈別"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["指定鏈資產清單"]}}}} ``` # 資產識別解析 將資產代碼或合約地址解析成標準資產識別，協助確認實際資產並降低同名代幣或跨鏈資產造成的誤判。 ## POST /v1/resolve > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"將資產代碼或合約地址解析成標準資產識別，協助確認實際資產並降低同名代幣或跨鏈資產造成的誤判。","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":{"ResolveRequest":{"description":"`POST /v1/resolve` 的請求 body。\n\n宣告型別讓 `/docs` UI 帶出可填的 body 欄位（否則送空 POST 會撞 415）。","properties":{"blockchain":{"description":"鏈別（ethereum / bsc / tron …）。","type":"string"},"contracts":{"description":"contract-first（較防偽）：合約位址清單，元素為 `null` 代表原生幣。\n與 `symbols` 同時給時以 `contracts` 為準。","items":{"type":["string","null"]},"type":["array","null"]},"symbols":{"description":"要解析的 symbol 清單；省略 / 空 / 含 `all` 代表該鏈全部。","items":{"type":"string"},"type":["array","null"]}},"required":["blockchain"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/resolve":{"post":{"operationId":"assets.resolve.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}},"description":"要解析的鏈與 symbols / contracts","required":true},"responses":{"200":{"content":{"application/json":{}},"description":"解析成功，回傳標準化的資產識別"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤（不支援的鏈別或格式錯誤），請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["資產識別解析"]}}}} ``` # 資產價格 查詢一個或多個資產的價格。未指定時間時取得目前價格；指定時間時取得對應的歷史價格。預設以美元計價，指定 quote 可改用法幣（如 TWD）計價。適合資產估值、帳務換算與損益計算。 ## GET /v1/rates > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢一個或多個資產的價格。未指定時間時取得目前價格；指定時間時取得對應的歷史價格。預設以美元計價，指定 quote 可改用法幣（如 TWD）計價。適合資產估值、帳務換算與損益計算。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/rates":{"get":{"operationId":"rates.price.v1","parameters":[{"description":"逗號分隔幣種（rate_symbol）","in":"query","name":"symbols","required":true,"schema":{"type":"string"}},{"description":"時點（unix 秒）；省略=最新","in":"query","name":"at","required":false,"schema":{"format":"int64","type":"integer"}},{"description":"計價幣別；省略 = USD。可用的法幣見 /v1/rates/symbols 的 fiat 欄位","in":"query","name":"quote","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳各幣種的價格"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 symbols"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"指定的計價幣別在該時點沒有匯率資料"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["資產價格"]}}}} ``` # 歷史價格序列 查詢指定資產在一段時間內的美元歷史價格序列。適合價格走勢分析、歷史估值、帳務回溯與策略研究。 ## GET /v1/rates/history > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢指定資產在一段時間內的美元歷史價格序列。適合價格走勢分析、歷史估值、帳務回溯與策略研究。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/rates/history":{"get":{"operationId":"rates.history.v1","parameters":[{"description":"幣種（rate_symbol）","in":"query","name":"symbol","required":true,"schema":{"type":"string"}},{"description":"起（unix 秒）","in":"query","name":"start","required":false,"schema":{"format":"int64","type":"integer"}},{"description":"迄（unix 秒）","in":"query","name":"end","required":false,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳歷史價格序列"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 symbol"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["歷史價格序列"]}}}} ``` # 可查價資產清單 列出目前可查詢價格的資產代碼，以及可用於計價與換算的法幣代碼，方便先確認哪些資產與 幣別支援價格、歷史價格或金額換算查詢。 ## GET /v1/rates/symbols > ```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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/rates/symbols":{"get":{"operationId":"rates.symbols.v1","responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳有報價資料的幣種與法幣清單"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["可查價資產清單"]}}}} ``` # 金額換算 將一筆金額從某個幣別換算成另一個幣別，兩端都可以是法幣或加密資產。指定時間時使用該 時點的歷史匯率，適合案件金額比對、帳務回溯與跨幣別對帳。回應會一併帶出換算所依據的 匯率與其資料時間，方便留存佐證。 若指定時間早於該幣別的資料涵蓋範圍，會回傳 404，而不會改用最新匯率代替。 ## GET /v1/rates/convert > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"將一筆金額從某個幣別換算成另一個幣別，兩端都可以是法幣或加密資產。指定時間時使用該\n時點的歷史匯率，適合案件金額比對、帳務回溯與跨幣別對帳。回應會一併帶出換算所依據的\n匯率與其資料時間，方便留存佐證。\n\n若指定時間早於該幣別的資料涵蓋範圍，會回傳 404，而不會改用最新匯率代替。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/rates/convert":{"get":{"operationId":"rates.convert.v1","parameters":[{"description":"要換算的金額（非負數）","in":"query","name":"amount","required":true,"schema":{"format":"double","type":"number"}},{"description":"來源幣別（法幣代碼或 rate_symbol）","in":"query","name":"from","required":true,"schema":{"type":"string"}},{"description":"目標幣別（法幣代碼或 rate_symbol）","in":"query","name":"to","required":true,"schema":{"type":"string"}},{"description":"時點（unix 秒）；省略=最新","in":"query","name":"at","required":false,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{}},"description":"換算成功，回傳結果金額與所用匯率"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查 amount / from / to"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"指定幣別在該時點沒有匯率資料"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["金額換算"]}}}} ``` # On Chain Data 鏈上資料：查詢地址交易、餘額、交易對手、錢包概況，以及代幣持有分布與資金流。查交易對手時，需要排序或篩選用 v1 counterparty；只要完整清單、講求速度（尤其 Bitcoin）用 v2 counterparty/list。 # 地址交易紀錄 查詢指定地址的交易紀錄，並可依資產、金額、時間區間與收付方向篩選。適合檢視地址的資金往來明細。 ## POST /v1/transactions > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢指定地址的交易紀錄，並可依資產、金額、時間區間與收付方向篩選。適合檢視地址的資金往來明細。","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":{"TransactionsRequest":{"description":"`POST /v1/transactions` 的請求 body。","properties":{"address":{"description":"查詢的地址。","type":"string"},"blockchain":{"description":"鏈別（ethereum / bsc / tron …）。","type":"string"},"contracts":{"description":"contract-first：合約位址清單（與 symbols 二擇一，較防偽）。","items":{"type":["string","null"]},"type":["array","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"filter_criterias":{"description":"進階：per-symbol 金額區間篩選。","items":{"$ref":"#/components/schemas/FilterCriteria"},"type":["array","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"description":"要看的幣種 symbol；省略 / 含 `all` 代表全部。","items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"},"FilterCriteria":{"description":"幣別篩選條件（交易列表用）。","properties":{"max_value":{"format":"double","type":["number","null"]},"min_value":{"format":"double","type":["number","null"]},"sign":{"type":["string","null"]},"symbol":{"type":"string"}},"required":["symbol"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/transactions":{"post":{"operationId":"transactions.query.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳符合條件的交易明細列表"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址交易紀錄"]}}}} ``` # 地址交易對手 列出指定地址曾往來的對手地址，並可依往來總額或交易筆數排序與篩選。適合找出主要資金往來對象。 ## POST /v1/counterparty > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"列出指定地址曾往來的對手地址，並可依往來總額或交易筆數排序與篩選。適合找出主要資金往來對象。","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":{"CounterpartyRequest":{"description":"`POST /v1/counterparty` 的請求 body（交易對手排行）。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"min_interactions":{"format":"int32","minimum":0,"type":["integer","null"]},"order":{"type":["string","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"sort":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/counterparty":{"post":{"operationId":"counterparty.query.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳交易對手清單與往來排行"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址交易對手"]}}}} ``` # 兩地址轉帳紀錄 查詢兩個地址之間的逐筆轉帳紀錄，呈現雙方實際資金往來。適合調查特定地址之間的直接關係。 ## POST /v1/counterparty/transfer-between > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢兩個地址之間的逐筆轉帳紀錄，呈現雙方實際資金往來。適合調查特定地址之間的直接關係。","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":{"TransferBetweenRequest":{"description":"`POST /v1/counterparty/transfer-between`：兩地址之間的交易明細。","properties":{"address_a":{"type":["string","null"]},"address_b":{"type":["string","null"]},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"counterparty":{"description":"對手地址（`address_b` 為同義別名）。","type":["string","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"order":{"type":["string","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"sort":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"target":{"description":"主地址（`address_a` 為同義別名）。","type":["string","null"]}},"required":["blockchain"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/counterparty/transfer-between":{"post":{"operationId":"counterparty.transfer-between.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferBetweenRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳兩地址之間的轉帳明細"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["兩地址轉帳紀錄"]}}}} ``` # 兩地址往來總覽 彙總兩個地址之間的往來情況，包括雙向金額、交易筆數與主要資金方向。適合快速判斷雙方往來規模。 ## POST /v1/counterparty/overview > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"彙總兩個地址之間的往來情況，包括雙向金額、交易筆數與主要資金方向。適合快速判斷雙方往來規模。","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":{"CounterpartyOverviewRequest":{"description":"`POST /v1/counterparty/overview`：兩地址聚合統計。","properties":{"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"counterparty":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"output_asset":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"target":{"type":["string","null"]}},"required":["blockchain"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/counterparty/overview":{"post":{"operationId":"counterparty.overview.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyOverviewRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳兩地址往來的彙總統計"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["兩地址往來總覽"]}}}} ``` # 地址餘額歷史 查詢指定地址持有某項資產的歷史餘額變化，回傳每日餘額序列。適合繪製持倉走勢或觀察資產增減。 ## POST /v1/balance-history > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢指定地址持有某項資產的歷史餘額變化，回傳每日餘額序列。適合繪製持倉走勢或觀察資產增減。","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":{"BalanceHistoryRequest":{"description":"`POST /v1/balance-history` 的請求 body（每日餘額變化 / 歷史餘額）。\n\n以單一資產為主，通常帶一個 symbol / contract；回應含每日 data_points\n與 `final_balance`。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"end_time":{"format":"int64","type":["integer","null"]},"output_asset":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"timezone":{"description":"UTC 偏移小時數。","format":"int32","type":["integer","null"]},"unit":{"description":"目前僅支援 `daily`。","type":["string","null"]}},"required":["blockchain","address"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/balance-history":{"post":{"operationId":"balance-history.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceHistoryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳每日餘額變化與最終餘額"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址餘額歷史"]}}}} ``` # 錢包活動總覽 取得指定地址的整體概況，包括各資產餘額、收付款次數，以及首次與最近交易時間。適合快速建立地址基本輪廓。 ## POST /v1/wallet-overview > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"取得指定地址的整體概況，包括各資產餘額、收付款次數，以及首次與最近交易時間。適合快速建立地址基本輪廓。","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":{"WalletOverviewRequest":{"description":"`POST /v1/wallet-overview` 的請求 body（地址總覽：餘額、收付次數、首末活躍…）。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"output_asset":{"type":["string","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/wallet-overview":{"post":{"operationId":"wallet-overview.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletOverviewRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳地址總覽資訊"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["錢包活動總覽"]}}}} ``` # 單筆交易詳情 依交易 Hash 查詢單筆交易詳情，包括原生資產轉帳、代幣轉帳與合約內部轉帳。適合交易查核與明細檢視。 ## GET /v1/transaction/{hash} > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"依交易 Hash 查詢單筆交易詳情，包括原生資產轉帳、代幣轉帳與合約內部轉帳。適合交易查核與明細檢視。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/transaction/{hash}":{"get":{"operationId":"transaction.overview.v1","parameters":[{"description":"tx hash (chain-native 格式)","in":"path","name":"hash","required":true,"schema":{"type":"string"}},{"description":"`ethereum` / `tron` / `bitcoin`.","in":"path","name":"blockchain","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳該筆交易的完整明細"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["單筆交易詳情"]}}}} ``` # 快速交易對手清單 快速取得指定地址的交易對手清單，並針對 Bitcoin 查詢提供最佳化處理。適合需要整理大量往來對象的場景。 ## GET /v2/counterparty/list > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"快速取得指定地址的交易對手清單，並針對 Bitcoin 查詢提供最佳化處理。適合需要整理大量往來對象的場景。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v2/counterparty/list":{"get":{"operationId":"counterparty.list.v2","parameters":[{"description":"ethereum / tron / bitcoin","in":"query","name":"blockchain","required":true,"schema":{"type":"string"}},{"description":"主地址","in":"query","name":"address","required":true,"schema":{"type":"string"}},{"description":"(optional) 預設 50","in":"query","name":"limit","required":false,"schema":{"format":"int32","minimum":0,"type":"integer"}},{"description":"(optional) 預設 0","in":"query","name":"offset","required":false,"schema":{"format":"int32","minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳交易對手清單"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["快速交易對手清單"]}}}} ``` # 代幣持有人排行 列出指定代幣持有量最高的前 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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/token/holders":{"get":{"operationId":"token.holders.v1","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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤（鏈別不支援或合約位址格式錯誤），請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請稍後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，資料量較大的代幣請稍後重試"}},"summary":"","tags":["代幣持有人排行"]}}}} ``` # 代幣持有集中度 取得指定代幣的持有集中度指標，包括前 10、100、1000 名占比，以及 HHI、Gini 等統計值。適合判斷籌碼是否集中。 ## GET /v1/token/concentration > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"取得指定代幣的持有集中度指標，包括前 10、100、1000 名占比，以及 HHI、Gini 等統計值。適合判斷籌碼是否集中。","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":{"ConcentrationMetrics":{"description":"集中度指標。effective_holders_* 依鏈不同:\n stables (USDT/USDC/DAI) — `effective_holders_1usd` / `_100usd`\n bitcoin — `effective_holders_0_001_btc` / `_0_1_btc`\n (BTC/USD 變動快,改用 BTC 計價門檻)\n 其他 token — 不附","properties":{"effective_holders_0_001_btc":{"description":"餘額 ≥ 0.001 BTC 的地址數（僅 bitcoin）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_0_1_btc":{"description":"餘額 ≥ 0.1 BTC 的地址數（僅 bitcoin）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_100usd":{"description":"餘額 ≥ $100 的地址數（僅穩定幣）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_1usd":{"description":"餘額 ≥ $1 的地址數（僅穩定幣，其他 token 不附）。","format":"int64","minimum":0,"type":["integer","null"]},"gini":{"description":"Gini coefficient（區塊鏈持有結構天然接近 1，僅供相對比較）。","format":"double","type":"number"},"hhi":{"description":"Herfindahl-Hirschman Index（0=完全分散，1=完全壟斷）。","format":"double","type":"number"},"top1000_pct":{"format":"double","type":"number"},"top100_pct":{"format":"double","type":"number"},"top10_pct":{"description":"前 10 名持有者占流通量 %。","format":"double","type":"number"}},"required":["top10_pct","top100_pct","top1000_pct","hhi","gini"],"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/token/concentration":{"get":{"operationId":"token.concentration.v1","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"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"代幣持有集中度查詢的回應。","properties":{"blockchain":{"type":"string"},"concentration":{"$ref":"#/components/schemas/ConcentrationMetrics"},"contract":{"type":["string","null"]},"decimals":{"format":"int32","minimum":0,"type":"integer"},"holder_count":{"format":"int64","minimum":0,"type":"integer"},"meta":{"$ref":"#/components/schemas/QueryMeta"},"symbol":{"type":"string"},"total_supply":{"format":"double","type":["number","null"]},"total_supply_raw":{"type":["string","null"]}},"required":["blockchain","symbol","decimals","holder_count","concentration","meta"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功，回傳持有集中度指標"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請稍後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["代幣持有集中度"]}}}} ``` # 多地址資金流 查詢指定代幣在一批地址間、特定時間區間內的資金流動。回傳各地址收入、支出、淨流量與整體加總，單次最多 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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/token/addresses_flow":{"get":{"operationId":"token.addresses-flow.v1","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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤（地址清單為空或超過 100 個、時間區間超過 365 天、或鏈別不符），請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請稍後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["多地址資金流"]}}}} ``` # Risk & Intelligence 風險與情資：查詢地址標籤、地址類型與行為風險，協助風險篩查與盡職調查。 # 地址風險評分 綜合地址的情資、行為與拓樸關係評估風險：情資維度提供標籤/實體/分類，行為維度偵測快速進出、分散轉出、一次性錢包、分層歸集等模式，拓樸維度評估交易對手與圖譜暴露。回傳 0–100 綜合分數、風險等級與各維度明細。 **維度覆蓋範圍**：情資維度支援所有鏈；行為與拓樸維度目前僅支援 Ethereum 與 Tron。 查詢其他鏈（如 Bitcoin）會成功回 200，但 `dimensions.behavior` 為 null、 `meta.behavior_available` 為 false，此時分數只反映情資維度。串接時請一律檢查 `meta`，不要把單維度結果當成完整評估。 ## POST /v1/address-risk > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"綜合地址的情資、行為與拓樸關係評估風險：情資維度提供標籤/實體/分類，行為維度偵測快速進出、分散轉出、一次性錢包、分層歸集等模式，拓樸維度評估交易對手與圖譜暴露。回傳 0–100 綜合分數、風險等級與各維度明細。\n\n**維度覆蓋範圍**：情資維度支援所有鏈；行為與拓樸維度目前僅支援 Ethereum 與 Tron。\n查詢其他鏈（如 Bitcoin）會成功回 200，但 `dimensions.behavior` 為 null、\n`meta.behavior_available` 為 false，此時分數只反映情資維度。串接時請一律檢查\n`meta`，不要把單維度結果當成完整評估。","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":{"AddressRiskRequest":{"description":"`POST /v1/address-risk` 的請求 body（綜合地址風險）。\n\n綜合地址的**情資、行為與拓樸關係**評估風險，回傳綜合分數 `composite_score`\n（0–100）、風險等級 `risk_level`（low/medium/high）與各維度明細 `dimensions`。\n行為與拓樸維度目前支援 Ethereum / Tron；情資維度為全鏈。估值與轉帳流固定以\n原生幣與主要穩定幣計算，不需（也不接受）指定代幣範圍。","properties":{"address":{"description":"查詢的地址。","type":"string"},"blockchain":{"description":"鏈別（行為/拓樸維度目前僅支援 ethereum / tron）。\n\n也可傳 `evm`：不指定鏈，以「同一個 EOA」看待該位址在各 EVM 鏈上的情資。\n此模式只有情資維度有意義，行為 / 拓樸維度綁定單一鏈，會退化為不可用。","type":"string"},"third_party":{"description":"外部來源查詢模式：`auto`（預設）＝只在可能改變風險判定時才動用外部來源；\n`force`＝一律查（合規 / 深度盡職調查用，較慢、較貴）；`off`＝只用自有情資庫。","type":["string","null"]}},"required":["blockchain","address"],"type":"object"},"RiskDecision":{"description":"判定過程資訊。","properties":{"context":{"description":"套用的身分語境，例如 `exchange`。有語境時同樣的行為會被重新詮釋\n（交易所的高頻進出屬正常營運，混幣器的則加重）。無法判定身分時為 null。","type":["string","null"]},"context_confidence":{"description":"語境判定的信心，0.0–1.0。","format":"double","type":"number"},"gate_reason":{"description":"觸發的下限原因；未觸發為 null。可能值：\n\n- `ofac_sanctioned` — 此地址本身在制裁名單上。分數下限 100。\n- `confirmed_illicit` — 此地址本身帶有已確認的非法行為者標籤\n （暗網市場、勒索軟體、盜幣、釣魚等）。分數下限 90。\n- `direct_sanctioned_edge` — 此地址本身無標籤，但直接與制裁地址往來。分數下限 70。\n\n三者判定的是不同主體：前兩者看這個地址本身，最後一者看它的交易對手。","type":["string","null"]},"gated":{"description":"是否觸發硬性下限。為 `true` 時分數由下限決定，不受其他維度稀釋——\n一個被制裁的地址不會因為行為看起來正常就被拉低。","type":"boolean"}},"required":["gated","context_confidence"],"type":"object"},"RiskDimensions":{"description":"三個評估維度。","properties":{"behavior":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BehaviorDimension","description":"行為維度：這個地址「做了什麼」。**僅 Ethereum / Tron**；其他鏈或資料暫時\n不可用時為 null（此時 `meta.behavior_available` 為 false）。"}]},"graph":{"$ref":"#/components/schemas/GraphDimension","description":"拓樸維度：這個地址「跟誰往來」。只在情資與行為無法定案時才展開（成本較高）。"},"intel":{"$ref":"#/components/schemas/IntelDimension","description":"情資維度：這個地址「是誰」。全鏈支援。"}},"required":["intel","graph"],"type":"object"},"BehaviorDimension":{"description":"行為維度明細。","properties":{"behaviors":{"description":"偵測到的行為樣態明細。","items":{"$ref":"#/components/schemas/BehaviorHit"},"type":"array"},"data_window":{"$ref":"#/components/schemas/DataWindow","description":"本次掃描涵蓋的資料範圍。"},"deferred":{"description":"本次略過未評估的行為代碼（資料不足或成本考量）。","items":{"type":"string"},"type":"array"},"evaluated":{"description":"本次實際評估的行為代碼。","items":{"type":"string"},"type":"array"},"score":{"description":"套用身分語境**之後**的行為分數，0–100。與 `score_raw` 的差距即語境的影響。","format":"double","type":"number"},"score_breakdown":{"description":"分數計算過程（各行為貢獻與封頂後總分）。"},"score_raw":{"description":"套用身分語境**之前**的原始行為分數，0–100。","format":"double","type":"number"}},"required":["score_raw","score","behaviors","score_breakdown","data_window"],"type":"object"},"BehaviorHit":{"description":"單一行為樣態。","properties":{"code":{"description":"行為代碼，例如 `rapid_in_out` / `fan_out` / `burner_wallet` / `fan_in` / `pass_through`。","type":"string"},"context_weight":{"description":"身分語境對此行為的權重倍率（<1 為壓抑、>1 為放大）。語境不明時不出現。","format":"double","type":["number","null"]},"ever_detected":{"description":"歷史上是否曾偵測到。","type":"boolean"},"evidence":{"description":"觸發此判定的證據（欄位依行為代碼而異）。"},"first_detected_at":{"description":"首次偵測到此行為的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"last_detected_at":{"description":"最近一次偵測到此行為的時間（Unix epoch 秒，UTC）。距今越久，對分數的加權越低。","format":"int64","type":"integer"},"name_zh":{"description":"行為的中文名稱。","type":"string"},"occurrence_count":{"description":"偵測到的次數。","format":"int64","type":"integer"},"score":{"description":"此行為的得分（套語境前）。","format":"double","type":"number"},"score_after_context":{"description":"套用語境後的得分。語境不明時不出現。","format":"double","type":["number","null"]},"severity":{"description":"嚴重程度：`low` | `medium` | `high`。","type":"string"}},"required":["code","name_zh","severity","score","evidence"],"type":"object"},"DataWindow":{"description":"行為掃描涵蓋的資料範圍。","properties":{"from":{"description":"掃描起點：此地址最早一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"to":{"description":"掃描終點：此地址最近一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"tx_count":{"description":"涵蓋的轉帳筆數。為 0 代表這個地址在我方資料中沒有活動紀錄。","format":"int64","type":"integer"}},"required":["from","to","tx_count"],"type":"object"},"GraphDimension":{"description":"拓樸維度明細。","properties":{"depth_reached":{"description":"實際展開的深度：`point`（未展開）| `edge`（一跳鄰居）。","type":"string"},"edge":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GraphEdge","description":"一跳鄰居篩檢結果；未展開時為 null。"}]},"paths":{"description":"多跳路徑（目前保留欄位，恆為空陣列）。","items":{},"type":"array"},"reason":{"description":"展開 / 未展開的原因代碼。","type":"string"},"score":{"description":"本維度分數，0–100。未展開時為 0。","format":"double","type":"number"}},"required":["score","depth_reached","reason"],"type":"object"},"GraphEdge":{"description":"一跳鄰居篩檢結果。","properties":{"direct_sanctioned":{"description":"是否有鄰居直接命中制裁名單。","type":"boolean"},"neighbors_hit":{"description":"篩檢後命中風險標籤的鄰居數。","format":"int64","type":"integer"},"neighbors_screened":{"description":"實際送去情資篩檢的鄰居數（有上限，故可能小於 `neighbors_total`）。","format":"int64","type":"integer"},"neighbors_total":{"description":"一跳鄰居總數。","format":"int64","type":"integer"},"risky_exposure_ratio":{"description":"風險曝險占比，0.0–1.0（風險鄰居的金額占比）。","format":"double","type":"number"},"risky_neighbors":{"description":"風險鄰居明細（依貢獻排序，最多 5 筆）。","items":{},"type":"array"}},"required":["risky_exposure_ratio","neighbors_total","neighbors_screened","neighbors_hit","direct_sanctioned"],"type":"object"},"IntelDimension":{"description":"情資維度明細。","properties":{"confidence":{"description":"情資信心，0.0–1.0。欄位語意同 `/v1/labels` 的 `label.confidence`。","format":"double","type":"number"},"entity":{"description":"實體名稱（與 `label` 同值，保留供既有整合使用）。","type":["string","null"]},"label":{"description":"實體名稱。","type":["string","null"]},"labels":{"description":"命中的標籤。欄位語意同 `/v1/labels` 的 `label.labels`。","items":{"type":"string"},"type":"array"},"score":{"description":"本維度分數，0–100。","format":"double","type":"number"}},"required":["score","confidence"],"type":"object"},"RiskFactor":{"description":"影響分數的單一因子。","properties":{"code":{"description":"因子代碼。","type":"string"},"detail":{"description":"人可讀的說明。","type":["string","null"]},"dimension":{"description":"來自哪個維度：`intel` | `behavior` | `graph`。","type":"string"},"effect":{"description":"對分數的作用：`amplify`（放大）| `suppress`（壓抑）| `as_is`（不變）。","type":"string"},"weight":{"description":"該因子的權重 / 貢獻分數。","format":"double","type":["number","null"]}},"required":["dimension","code","effect"],"type":"object"},"RiskMeta":{"description":"本次評估的覆蓋範圍。","properties":{"analysis_depth":{"description":"實際達到的分析深度：`intel_only` | `point` | `edge`。","type":"string"},"behavior_available":{"description":"行為維度是否可用。為 `false` 時 `dimensions.behavior` 為 null，\n綜合分數**不包含**行為訊號——不要把它當成完整評估。","type":"boolean"},"computed_at":{"description":"本次評估時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"graph_available":{"description":"拓樸維度是否展開。","type":"boolean"},"graph_reason":{"description":"拓樸維度展開 / 未展開的原因代碼。","type":"string"}},"required":["analysis_depth","behavior_available","graph_available","graph_reason","computed_at"],"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/address-risk":{"post":{"operationId":"address-risk.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRiskRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"綜合地址風險結果。","properties":{"address":{"description":"查詢的地址。","type":"string"},"chain":{"description":"查詢的鏈別（正規化後）。","type":"string"},"composite_score":{"description":"綜合風險分數，0–100。三個維度加權後再套用 gate 下限。","format":"double","type":"number"},"decision":{"$ref":"#/components/schemas/RiskDecision","description":"判定過程的透明化資訊。"},"dimensions":{"$ref":"#/components/schemas/RiskDimensions","description":"三個維度的明細。"},"factors":{"description":"影響本次分數的主要因子（已依影響程度排序）。","items":{"$ref":"#/components/schemas/RiskFactor"},"type":"array"},"meta":{"$ref":"#/components/schemas/RiskMeta","description":"本次評估的覆蓋範圍。**務必檢查**：維度不可用時分數只反映可用的維度。"},"risk_level":{"description":"綜合風險等級：`low` | `medium` | `high`。","type":"string"},"risk_level_zh":{"description":"風險等級的中文說明。","type":"string"}},"required":["address","chain","composite_score","risk_level","risk_level_zh","decision","dimensions","factors","meta"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功，回傳綜合分數、風險等級與情資/行為/拓樸各維度明細"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤：缺少必填欄位、blockchain 不支援、address 格式與 blockchain 不符，或 third_party 值無效"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時（大地址的完整歷史掃描較久），請稍後重試"}},"summary":"","tags":["地址風險評分"]}}}} ``` # 地址標籤與身分 查詢地址已知標籤與身分類型，例如交易所、混幣器或 DeFi。回傳實體名稱、分類、信心度與驗證狀態，並提示是否需要進一步分析。 查得到地址但沒有任何標籤是正常結果（`label` 只剩 `confidence: 0.0`），代表 「目前無情資」，不代表該地址安全。需要風險判定請走 `/v1/address-risk`。 ## GET /v1/labels > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"查詢地址已知標籤與身分類型，例如交易所、混幣器或 DeFi。回傳實體名稱、分類、信心度與驗證狀態，並提示是否需要進一步分析。\n\n查得到地址但沒有任何標籤是正常結果（`label` 只剩 `confidence: 0.0`），代表\n「目前無情資」，不代表該地址安全。需要風險判定請走 `/v1/address-risk`。","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":{"AggregateLabel":{"description":"綜合標籤。","properties":{"confidence":{"description":"綜合信心，0.0–1.0。多方一致或經我方驗證會拉高；單一來源、未經驗證會偏低。\n沒有任何命中時為 `0.0`。","format":"double","type":"number"},"entity_name":{"description":"實體名稱，例如 `Binance`。無法判定時不出現。","type":["string","null"]},"labels":{"description":"這個地址的身分與行為標籤（小寫 snake_case 代碼，去重、保序）。\n\n一個地址可以同時有多個標籤，而且它們分屬不同面向——身分（`exchange`、\n`dex`、`mixer`）、行為（`mev_bot`、`sandwich_attack`）、風險\n（`sanction`、`phishing`）、資金流形態（`peel_chain`）與活躍度\n（`dormant`）。這些**不互斥**，請逐一比對需要的標籤，不要假設只有一個。\n\n查無情資時為空陣列（欄位不出現）。","items":{"type":"string"},"type":"array"}},"required":["confidence"],"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/labels":{"get":{"operationId":"labels.v1","parameters":[{"description":"鏈別。支援 ethereum、tron、bitcoin、bsc、polygon、avalanche、base（可用 eth / btc / bnb 等常見別名）","in":"query","name":"chain","required":true,"schema":{"type":"string"}},{"description":"查詢地址。格式須與 chain 相符，否則回 400","in":"query","name":"address","required":true,"schema":{"type":"string"}},{"description":"查詢範圍。all（預設）＝自有情資庫加外部來源；first_party＝只查自有情資庫（較快，不消耗外部查詢額度）","in":"query","name":"sources","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"地址標籤查詢結果。","properties":{"address":{"description":"查詢的地址。","type":"string"},"chain":{"description":"查詢的鏈別（正規化後）。","type":"string"},"fetched_at":{"description":"本次結果產生時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"label":{"$ref":"#/components/schemas/AggregateLabel","description":"綜合標籤：各來源結果彙整後的單一結論。"}},"required":["chain","address","label","fetched_at"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤：缺少必填參數、chain 不支援、address 格式與 chain 不符，或 sources 值無效"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址標籤與身分"]}}}} ``` # 地址類型分類 使用機器學習判斷一批地址可能屬於的類型，例如交易所、DeFi 或混幣器，並回傳信心分數。單次最多 100 個地址。 本端點只看鏈上行為特徵做統計推測，**不查情資庫、不回風險分數**。要「這個地址是誰」請用 `/v1/labels`；要可量化的風險結論請用 `/v1/address-risk`。 結果順序與請求的 `addresses` 一致。單一地址分析失敗時該筆的 `predicted_class` 為 null、 `error` 有值，整批仍回 200——請逐筆檢查而不是只看 HTTP 狀態碼。 ## POST /v1/address-classify > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"使用機器學習判斷一批地址可能屬於的類型，例如交易所、DeFi 或混幣器，並回傳信心分數。單次最多 100 個地址。\n\n本端點只看鏈上行為特徵做統計推測，**不查情資庫、不回風險分數**。要「這個地址是誰」請用\n`/v1/labels`；要可量化的風險結論請用 `/v1/address-risk`。\n\n結果順序與請求的 `addresses` 一致。單一地址分析失敗時該筆的 `predicted_class` 為 null、\n`error` 有值，整批仍回 200——請逐筆檢查而不是只看 HTTP 狀態碼。","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":{"ClassifyRequest":{"description":"`POST /v1/address-classify` 的請求 body。","properties":{"addresses":{"description":"要分類的地址清單。不可為空，單次最多 100 筆，且格式須與 `blockchain` 相符。","items":{"type":"string"},"type":"array"},"blockchain":{"description":"區塊鏈網路名稱。支援 `tron`（預設）、`ethereum`、`bitcoin`。\n\n省略時為 `tron`——若你送的是其他鏈的地址，會因格式不符而回 400，不會被誤判成 Tron 地址。","type":"string"}},"required":["addresses"],"type":"object"},"AddressClassification":{"description":"單一地址的分類結果。","properties":{"address":{"description":"對應的地址（原樣回傳）。","type":"string"},"confidence":{"description":"預測信心，0.0–1.0。分類失敗時為 0。","format":"double","type":"number"},"error":{"description":"該地址分類失敗的說明；成功時為 `null`。\n\n單一地址失敗**不會**讓整批請求失敗，整體仍回 200。","type":["string","null"]},"predicted_class":{"description":"預測類型。該地址分類失敗時為 `null`（此時 `error` 有值）。\n\n可能值依鏈而異：\n- **Tron**：`Exchange`、`Deposit`、`Defi`、`Mixer`、`Scam`、`Unknown`\n- **Ethereum**：`Exchange`、`Deposit`、`Defi`、`Mixer`、`Scam`\n- **Bitcoin**：`Exchange`、`Deposit`、`Defi`、`ColdWallet`、`MiningPool`、`Scam`\n\n模型改版時可能新增類別，請以「未知字串」的方式寬容處理，不要用窮舉 match。","type":["string","null"]}},"required":["address","confidence"],"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/address-classify":{"post":{"operationId":"address-classify.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"description":"地址分類結果。","properties":{"results":{"description":"每個地址一筆，**順序與請求的 `addresses` 相同**。","items":{"$ref":"#/components/schemas/AddressClassification"},"type":"array"}},"required":["results"],"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"分類完成，回傳每個地址的預測類型與信心分數"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤：缺少必填欄位、鏈別不支援、地址清單為空或超過 100 筆，或地址格式與鏈不符"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"分類逾時（一次送較多地址時較容易發生），請縮小批次後重試"}},"summary":"","tags":["地址類型分類"]}}}} ``` # Investigation 調查追蹤：沿資金流向逐跳追蹤，並透過 Bitcoin 找零偵測還原更接近真實的收付關係。 # Bitcoin 找零地址偵測 辨識一筆 Bitcoin 交易中可能的找零地址，協助區分實際收款輸出與退回付款方的找零，還原更接近真實的資金方向。 ## POST /v1/btc/change-address > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"辨識一筆 Bitcoin 交易中可能的找零地址，協助區分實際收款輸出與退回付款方的找零，還原更接近真實的資金方向。","name":"Bitcoin 找零地址偵測"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"ChangeAddressRequest":{"description":"`POST /v1/btc/change-address` 的請求 body。","properties":{"txid":{"description":"Bitcoin 交易 ID（txid）。","type":"string"}},"required":["txid"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/btc/change-address":{"post":{"operationId":"btc.change-address.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeAddressRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"偵測成功，回傳找零地址與判定依據"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 txid"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["Bitcoin 找零地址偵測"]}}}} ``` # 多跳資金追蹤 從指定地址向外或向內逐跳追蹤資金，自動展開多層流向，並可依資產與金額條件篩選。適合調查資金來源與最終去向。 ## POST /v1/trace > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"從指定地址向外或向內逐跳追蹤資金，自動展開多層流向，並可依資產與金額條件篩選。適合調查資金來源與最終去向。","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":{"TraceRequest":{"description":"智能追蹤的請求參數。\n\n`track_setting`（時間範圍、向外 / 向內追蹤深度、回傳筆數上限、金額累計…）、\n`filter_criterias`（金額 / 幣別篩選）、`stop_track_condition`（停止追蹤條件）皆為選填；\n未提供時以預設行為追蹤。","properties":{"address":{"description":"起始追蹤地址。","type":"string"},"blockchain":{"description":"鏈別（tron / ethereum / bitcoin）。","type":"string"},"filter_criterias":{"description":"金額篩選條件陣列（symbol / min_value / max_value / sign）。"},"stop_track_condition":{"description":"停止追蹤條件（預留）。"},"track_setting":{"description":"追蹤參數（時間範圍、往外/往內深度、limit、金額累計等）。"}},"required":["blockchain","address"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/trace":{"post":{"operationId":"trace.quick.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"追蹤成功，回傳展開的金流路徑與相關交易"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 blockchain 與 address"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["多跳資金追蹤"]}}}} ``` # Cross Chain 跨鏈追蹤：追蹤資金經跨鏈橋移轉後的去向，連接來源鏈與目的鏈的交易關係。 # 跨鏈資金追蹤 追蹤單筆交易經跨鏈橋移轉後的去向，連接來源鏈、目的鏈，以及兩端交易與收付地址。 ## GET /v1/cross-chain > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"追蹤單筆交易經跨鏈橋移轉後的去向，連接來源鏈、目的鏈，以及兩端交易與收付地址。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/cross-chain":{"get":{"operationId":"cross-chain.track.v1","parameters":[{"description":"來源交易 hash","in":"query","name":"txhash","required":true,"schema":{"type":"string"}},{"description":"protocol label（協定關鍵字），例如 across、axelar、celer、wormhole","in":"query","name":"label","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳跨鏈交易詳情（來源/目的鏈、兩端交易與收付地址）"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 txhash 與 label"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["跨鏈資金追蹤"]}}}} ``` # 批次跨鏈追蹤 一次追蹤多筆交易的跨鏈去向，適合大量比對橋接交易或批次調查跨鏈資金流。 ## POST /v1/cross-chain/batch > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"一次追蹤多筆交易的跨鏈去向，適合大量比對橋接交易或批次調查跨鏈資金流。","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":{"BatchRequest":{"description":"`POST /v1/cross-chain/batch` 的請求 body。","properties":{"queries":{"items":{"$ref":"#/components/schemas/BatchItem"},"type":"array"}},"required":["queries"],"type":"object"},"BatchItem":{"description":"批次的單筆查詢。","properties":{"label":{"type":"string"},"txhash":{"type":"string"}},"required":["txhash","label"],"type":"object"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/cross-chain/batch":{"post":{"operationId":"cross-chain.batch.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳各筆跨鏈交易詳情"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["批次跨鏈追蹤"]}}}} ``` # Address Utilities 地址工具：驗證、修正與補全地址，降低因輸入錯誤造成的查詢失敗。要解析的是資產代碼或合約地址，請改用 Assets & Market Data 分類下的 resolve。 # 地址驗證與修正 驗證錢包地址格式，並針對不完整或疑似輸入錯誤的地址提供修正結果與相似候選，降低查錯地址的風險。 ## GET /v1/addresses/resolve > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"驗證錢包地址格式，並針對不完整或疑似輸入錯誤的地址提供修正結果與相似候選，降低查錯地址的風險。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/addresses/resolve":{"get":{"operationId":"address.resolve.v1","parameters":[{"description":"完整地址（驗證 / 糾錯）","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"鏈別；省略則由服務嘗試推斷","in":"query","name":"chain","required":false,"schema":{"type":"string"}},{"description":"相似候選數上限","in":"query","name":"limit","required":false,"schema":{"format":"int32","minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳比對結果與相似候選地址"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 q，或無法判斷其所屬鏈別"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"點數餘額不足"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址驗證與修正"]}}}} ``` # 地址自動補全 依輸入的地址前綴提供完整地址候選，適合搜尋框或即時輸入場景。前綴至少需 5 個字元。 ## GET /v1/addresses/autocomplete > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"依輸入的地址前綴提供完整地址候選，適合搜尋框或即時輸入場景。前綴至少需 5 個字元。","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":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/addresses/autocomplete":{"get":{"operationId":"address.autocomplete.v1","parameters":[{"description":"地址前綴（至少 5 字）","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"鏈別；省略則由服務嘗試推斷","in":"query","name":"chain","required":false,"schema":{"type":"string"}},{"description":"候選數上限","in":"query","name":"limit","required":false,"schema":{"format":"int32","minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{}},"description":"查詢成功，回傳符合前綴的候選地址"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請提供 q（且長度足夠），或無法判斷其所屬鏈別"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時無法回應，請稍後重試"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"查詢逾時，請稍後重試"}},"summary":"","tags":["地址自動補全"]}}}} ``` # Events 事件訂閱：建立 Webhook，讓符合條件的鏈上事件主動推送到你的系統。 # Webhook 訂閱清單 列出目前已建立的 Webhook 訂閱，方便查看哪些鏈上事件正在推送到你的系統。 ## GET /v1/webhooks > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"列出目前已建立的 Webhook 訂閱，方便查看哪些鏈上事件正在推送到你的系統。","name":"Webhook 訂閱清單"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/webhooks":{"get":{"operationId":"webhooks.list.v1","responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"items":{"description":"對外的訂閱視圖（不含 secret）。","properties":{"created_at":{"format":"date-time","type":"string"},"event_type":{"type":"string"},"id":{"format":"uuid","type":"string"},"status":{"type":"string"},"target_url":{"type":"string"}},"required":["id","target_url","event_type","status","created_at"],"type":"object"},"type":"array"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"查詢成功，回傳目前的訂閱清單"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"}},"summary":"","tags":["Webhook 訂閱清單"]}}}} ``` # 建立 Webhook 訂閱 建立一筆 Webhook 訂閱，指定接收 URL 與事件類型後，符合條件的事件會主動推送到你的系統。回應中的簽章密鑰僅顯示一次，請妥善保存。 ## POST /v1/webhooks > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"建立一筆 Webhook 訂閱，指定接收 URL 與事件類型後，符合條件的事件會主動推送到你的系統。回應中的簽章密鑰僅顯示一次，請妥善保存。","name":"建立 Webhook 訂閱"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"CreateWebhookRequest":{"description":"建立訂閱的請求 body。","properties":{"event_type":{"description":"訂閱的事件類型，例如 `large_transfer`、`address_activity`。","type":"string"},"target_url":{"description":"事件送達的目標 URL。","type":"string"}},"required":["target_url","event_type"],"type":"object"},"WebhookView":{"description":"對外的訂閱視圖（不含 secret）。","properties":{"created_at":{"format":"date-time","type":"string"},"event_type":{"type":"string"},"id":{"format":"uuid","type":"string"},"status":{"type":"string"},"target_url":{"type":"string"}},"required":["id","target_url","event_type","status","created_at"],"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"},"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/webhooks":{"post":{"operationId":"webhooks.create.v1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/WebhookView"},{"properties":{"secret":{"description":"用來驗證 webhook 來源的 HMAC 密鑰。","type":"string"}},"required":["secret"],"type":"object"}],"description":"建立成功時的回應（含 secret，僅此一次回傳，請客戶端妥善保存）。"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"建立成功，回傳訂閱資訊與一次性簽章密鑰"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求參數有誤，請檢查輸入內容"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"}},"summary":"","tags":["建立 Webhook 訂閱"]}}}} ``` # 刪除 Webhook 訂閱 刪除指定的 Webhook 訂閱。刪除後，該訂閱對應的事件將停止推送。 ## DELETE /v1/webhooks/{id} > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"刪除指定的 Webhook 訂閱。刪除後，該訂閱對應的事件將停止推送。","name":"刪除 Webhook 訂閱"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}},"paths":{"/v1/webhooks/{id}":{"delete":{"operationId":"webhooks.delete.v1","parameters":[{"description":"訂閱 ID（建立訂閱時回傳）","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"已成功刪除該訂閱"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"缺少或無效的 API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"目前方案不含此端點"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"找不到該訂閱"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"請求過於頻繁，請依 Retry-After 退避後重試"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"伺服器內部錯誤"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"後端服務暫時過載，請退避後重試"}},"summary":"","tags":["刪除 Webhook 訂閱"]}}}} ``` # System 系統狀態：提供存活與就緒檢查，供監控與負載平衡使用。 # 服務存活檢查 檢查服務程序是否仍可處理請求。服務存活時回傳 200，供監控系統判斷是否需要重啟。 ## GET /healthz > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"檢查服務程序是否仍可處理請求。服務存活時回傳 200，供監控系統判斷是否需要重啟。","name":"服務存活檢查"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"paths":{"/healthz":{"get":{"operationId":"healthz.v1","responses":{"200":{"content":{"application/json":{}},"description":"服務存活中"}},"summary":"","tags":["服務存活檢查"]}}}} ``` # 服務就緒檢查 檢查服務是否已啟動完成且關鍵相依正常。就緒時回傳 200，供負載平衡器判斷是否可以導入流量。 ## GET /readyz > ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"檢查服務是否已啟動完成且關鍵相依正常。就緒時回傳 200，供負載平衡器判斷是否可以導入流量。","name":"服務就緒檢查"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"paths":{"/readyz":{"get":{"operationId":"readyz.v1","responses":{"200":{"content":{"application/json":{}},"description":"服務已就緒，可以開始接收流量"},"503":{"description":"服務尚未就緒，請稍後重試"}},"summary":"","tags":["服務就緒檢查"]}}}} ``` # Models ## The AddressClassification object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"AddressClassification":{"description":"單一地址的分類結果。","properties":{"address":{"description":"對應的地址（原樣回傳）。","type":"string"},"confidence":{"description":"預測信心，0.0–1.0。分類失敗時為 0。","format":"double","type":"number"},"error":{"description":"該地址分類失敗的說明；成功時為 `null`。\n\n單一地址失敗**不會**讓整批請求失敗，整體仍回 200。","type":["string","null"]},"predicted_class":{"description":"預測類型。該地址分類失敗時為 `null`（此時 `error` 有值）。\n\n可能值依鏈而異：\n- **Tron**：`Exchange`、`Deposit`、`Defi`、`Mixer`、`Scam`、`Unknown`\n- **Ethereum**：`Exchange`、`Deposit`、`Defi`、`Mixer`、`Scam`\n- **Bitcoin**：`Exchange`、`Deposit`、`Defi`、`ColdWallet`、`MiningPool`、`Scam`\n\n模型改版時可能新增類別，請以「未知字串」的方式寬容處理，不要用窮舉 match。","type":["string","null"]}},"required":["address","confidence"],"type":"object"}}}} ``` ## The AddressFlow object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"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"}}}} ``` ## The AddressRiskRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"AddressRiskRequest":{"description":"`POST /v1/address-risk` 的請求 body（綜合地址風險）。\n\n綜合地址的**情資、行為與拓樸關係**評估風險，回傳綜合分數 `composite_score`\n（0–100）、風險等級 `risk_level`（low/medium/high）與各維度明細 `dimensions`。\n行為與拓樸維度目前支援 Ethereum / Tron；情資維度為全鏈。估值與轉帳流固定以\n原生幣與主要穩定幣計算，不需（也不接受）指定代幣範圍。","properties":{"address":{"description":"查詢的地址。","type":"string"},"blockchain":{"description":"鏈別（行為/拓樸維度目前僅支援 ethereum / tron）。\n\n也可傳 `evm`：不指定鏈，以「同一個 EOA」看待該位址在各 EVM 鏈上的情資。\n此模式只有情資維度有意義，行為 / 拓樸維度綁定單一鏈，會退化為不可用。","type":"string"},"third_party":{"description":"外部來源查詢模式：`auto`（預設）＝只在可能改變風險判定時才動用外部來源；\n`force`＝一律查（合規 / 深度盡職調查用，較慢、較貴）；`off`＝只用自有情資庫。","type":["string","null"]}},"required":["blockchain","address"],"type":"object"}}}} ``` ## The AddressesFlowAggregate object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"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"}}}} ``` ## The AggregateLabel object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"AggregateLabel":{"description":"綜合標籤。","properties":{"confidence":{"description":"綜合信心，0.0–1.0。多方一致或經我方驗證會拉高；單一來源、未經驗證會偏低。\n沒有任何命中時為 `0.0`。","format":"double","type":"number"},"entity_name":{"description":"實體名稱，例如 `Binance`。無法判定時不出現。","type":["string","null"]},"labels":{"description":"這個地址的身分與行為標籤（小寫 snake_case 代碼，去重、保序）。\n\n一個地址可以同時有多個標籤，而且它們分屬不同面向——身分（`exchange`、\n`dex`、`mixer`）、行為（`mev_bot`、`sandwich_attack`）、風險\n（`sanction`、`phishing`）、資金流形態（`peel_chain`）與活躍度\n（`dormant`）。這些**不互斥**，請逐一比對需要的標籤，不要假設只有一個。\n\n查無情資時為空陣列（欄位不出現）。","items":{"type":"string"},"type":"array"}},"required":["confidence"],"type":"object"}}}} ``` ## The BalanceHistoryRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"BalanceHistoryRequest":{"description":"`POST /v1/balance-history` 的請求 body（每日餘額變化 / 歷史餘額）。\n\n以單一資產為主，通常帶一個 symbol / contract；回應含每日 data_points\n與 `final_balance`。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"end_time":{"format":"int64","type":["integer","null"]},"output_asset":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"timezone":{"description":"UTC 偏移小時數。","format":"int32","type":["integer","null"]},"unit":{"description":"目前僅支援 `daily`。","type":["string","null"]}},"required":["blockchain","address"],"type":"object"}}}} ``` ## The BatchItem object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"BatchItem":{"description":"批次的單筆查詢。","properties":{"label":{"type":"string"},"txhash":{"type":"string"}},"required":["txhash","label"],"type":"object"}}}} ``` ## The BatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"BatchRequest":{"description":"`POST /v1/cross-chain/batch` 的請求 body。","properties":{"queries":{"items":{"$ref":"#/components/schemas/BatchItem"},"type":"array"}},"required":["queries"],"type":"object"},"BatchItem":{"description":"批次的單筆查詢。","properties":{"label":{"type":"string"},"txhash":{"type":"string"}},"required":["txhash","label"],"type":"object"}}}} ``` ## The BehaviorDimension object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"BehaviorDimension":{"description":"行為維度明細。","properties":{"behaviors":{"description":"偵測到的行為樣態明細。","items":{"$ref":"#/components/schemas/BehaviorHit"},"type":"array"},"data_window":{"$ref":"#/components/schemas/DataWindow","description":"本次掃描涵蓋的資料範圍。"},"deferred":{"description":"本次略過未評估的行為代碼（資料不足或成本考量）。","items":{"type":"string"},"type":"array"},"evaluated":{"description":"本次實際評估的行為代碼。","items":{"type":"string"},"type":"array"},"score":{"description":"套用身分語境**之後**的行為分數，0–100。與 `score_raw` 的差距即語境的影響。","format":"double","type":"number"},"score_breakdown":{"description":"分數計算過程（各行為貢獻與封頂後總分）。"},"score_raw":{"description":"套用身分語境**之前**的原始行為分數，0–100。","format":"double","type":"number"}},"required":["score_raw","score","behaviors","score_breakdown","data_window"],"type":"object"},"BehaviorHit":{"description":"單一行為樣態。","properties":{"code":{"description":"行為代碼，例如 `rapid_in_out` / `fan_out` / `burner_wallet` / `fan_in` / `pass_through`。","type":"string"},"context_weight":{"description":"身分語境對此行為的權重倍率（<1 為壓抑、>1 為放大）。語境不明時不出現。","format":"double","type":["number","null"]},"ever_detected":{"description":"歷史上是否曾偵測到。","type":"boolean"},"evidence":{"description":"觸發此判定的證據（欄位依行為代碼而異）。"},"first_detected_at":{"description":"首次偵測到此行為的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"last_detected_at":{"description":"最近一次偵測到此行為的時間（Unix epoch 秒，UTC）。距今越久，對分數的加權越低。","format":"int64","type":"integer"},"name_zh":{"description":"行為的中文名稱。","type":"string"},"occurrence_count":{"description":"偵測到的次數。","format":"int64","type":"integer"},"score":{"description":"此行為的得分（套語境前）。","format":"double","type":"number"},"score_after_context":{"description":"套用語境後的得分。語境不明時不出現。","format":"double","type":["number","null"]},"severity":{"description":"嚴重程度：`low` | `medium` | `high`。","type":"string"}},"required":["code","name_zh","severity","score","evidence"],"type":"object"},"DataWindow":{"description":"行為掃描涵蓋的資料範圍。","properties":{"from":{"description":"掃描起點：此地址最早一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"to":{"description":"掃描終點：此地址最近一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"tx_count":{"description":"涵蓋的轉帳筆數。為 0 代表這個地址在我方資料中沒有活動紀錄。","format":"int64","type":"integer"}},"required":["from","to","tx_count"],"type":"object"}}}} ``` ## The BehaviorHit object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"BehaviorHit":{"description":"單一行為樣態。","properties":{"code":{"description":"行為代碼，例如 `rapid_in_out` / `fan_out` / `burner_wallet` / `fan_in` / `pass_through`。","type":"string"},"context_weight":{"description":"身分語境對此行為的權重倍率（<1 為壓抑、>1 為放大）。語境不明時不出現。","format":"double","type":["number","null"]},"ever_detected":{"description":"歷史上是否曾偵測到。","type":"boolean"},"evidence":{"description":"觸發此判定的證據（欄位依行為代碼而異）。"},"first_detected_at":{"description":"首次偵測到此行為的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"last_detected_at":{"description":"最近一次偵測到此行為的時間（Unix epoch 秒，UTC）。距今越久，對分數的加權越低。","format":"int64","type":"integer"},"name_zh":{"description":"行為的中文名稱。","type":"string"},"occurrence_count":{"description":"偵測到的次數。","format":"int64","type":"integer"},"score":{"description":"此行為的得分（套語境前）。","format":"double","type":"number"},"score_after_context":{"description":"套用語境後的得分。語境不明時不出現。","format":"double","type":["number","null"]},"severity":{"description":"嚴重程度：`low` | `medium` | `high`。","type":"string"}},"required":["code","name_zh","severity","score","evidence"],"type":"object"}}}} ``` ## The ChangeAddressRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ChangeAddressRequest":{"description":"`POST /v1/btc/change-address` 的請求 body。","properties":{"txid":{"description":"Bitcoin 交易 ID（txid）。","type":"string"}},"required":["txid"],"type":"object"}}}} ``` ## The ClassifyRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ClassifyRequest":{"description":"`POST /v1/address-classify` 的請求 body。","properties":{"addresses":{"description":"要分類的地址清單。不可為空，單次最多 100 筆，且格式須與 `blockchain` 相符。","items":{"type":"string"},"type":"array"},"blockchain":{"description":"區塊鏈網路名稱。支援 `tron`（預設）、`ethereum`、`bitcoin`。\n\n省略時為 `tron`——若你送的是其他鏈的地址，會因格式不符而回 400，不會被誤判成 Tron 地址。","type":"string"}},"required":["addresses"],"type":"object"}}}} ``` ## The ConcentrationMetrics object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ConcentrationMetrics":{"description":"集中度指標。effective_holders_* 依鏈不同:\n stables (USDT/USDC/DAI) — `effective_holders_1usd` / `_100usd`\n bitcoin — `effective_holders_0_001_btc` / `_0_1_btc`\n (BTC/USD 變動快,改用 BTC 計價門檻)\n 其他 token — 不附","properties":{"effective_holders_0_001_btc":{"description":"餘額 ≥ 0.001 BTC 的地址數（僅 bitcoin）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_0_1_btc":{"description":"餘額 ≥ 0.1 BTC 的地址數（僅 bitcoin）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_100usd":{"description":"餘額 ≥ $100 的地址數（僅穩定幣）。","format":"int64","minimum":0,"type":["integer","null"]},"effective_holders_1usd":{"description":"餘額 ≥ $1 的地址數（僅穩定幣，其他 token 不附）。","format":"int64","minimum":0,"type":["integer","null"]},"gini":{"description":"Gini coefficient（區塊鏈持有結構天然接近 1，僅供相對比較）。","format":"double","type":"number"},"hhi":{"description":"Herfindahl-Hirschman Index（0=完全分散，1=完全壟斷）。","format":"double","type":"number"},"top1000_pct":{"format":"double","type":"number"},"top100_pct":{"format":"double","type":"number"},"top10_pct":{"description":"前 10 名持有者占流通量 %。","format":"double","type":"number"}},"required":["top10_pct","top100_pct","top1000_pct","hhi","gini"],"type":"object"}}}} ``` ## The CounterpartyOverviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"CounterpartyOverviewRequest":{"description":"`POST /v1/counterparty/overview`：兩地址聚合統計。","properties":{"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"counterparty":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"output_asset":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"target":{"type":["string","null"]}},"required":["blockchain"],"type":"object"}}}} ``` ## The CounterpartyRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"CounterpartyRequest":{"description":"`POST /v1/counterparty` 的請求 body（交易對手排行）。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"min_interactions":{"format":"int32","minimum":0,"type":["integer","null"]},"order":{"type":["string","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"sort":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"}}}} ``` ## The CreateWebhookRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"CreateWebhookRequest":{"description":"建立訂閱的請求 body。","properties":{"event_type":{"description":"訂閱的事件類型，例如 `large_transfer`、`address_activity`。","type":"string"},"target_url":{"description":"事件送達的目標 URL。","type":"string"}},"required":["target_url","event_type"],"type":"object"}}}} ``` ## The DataWindow object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"DataWindow":{"description":"行為掃描涵蓋的資料範圍。","properties":{"from":{"description":"掃描起點：此地址最早一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"to":{"description":"掃描終點：此地址最近一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"tx_count":{"description":"涵蓋的轉帳筆數。為 0 代表這個地址在我方資料中沒有活動紀錄。","format":"int64","type":"integer"}},"required":["from","to","tx_count"],"type":"object"}}}} ``` ## The ErrorDetail object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ErrorResponse":{"description":"對外錯誤信封。與成功回應的 [`crate::response::ApiResponse`] 結構對稱，\n客戶端永遠拿到 `{ \"error\": { \"code\": ..., \"message\": ... } }`。\n\n同時是 OpenAPI 的錯誤 schema：所有非 2xx 回應都是這個形狀，端點文件以\n`body = ErrorResponse` 引用它，客戶端只要寫一次錯誤解析。","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["error"],"type":"object"},"ErrorDetail":{"description":"錯誤本體。`code` 是穩定的機器可讀字串（比 HTTP 狀態碼細緻），\n`message` 是給人看的說明，不保證格式穩定——請用 `code` 做程式判斷。","properties":{"code":{"description":"機器可讀錯誤碼，例如 `bad_request` / `insufficient_credit` / `gateway_timeout`。","type":"string"},"message":{"description":"人可讀的錯誤說明。","type":"string"}},"required":["code","message"],"type":"object"}}}} ``` ## The FilterCriteria object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"FilterCriteria":{"description":"幣別篩選條件（交易列表用）。","properties":{"max_value":{"format":"double","type":["number","null"]},"min_value":{"format":"double","type":["number","null"]},"sign":{"type":["string","null"]},"symbol":{"type":"string"}},"required":["symbol"],"type":"object"}}}} ``` ## The GraphDimension object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"GraphDimension":{"description":"拓樸維度明細。","properties":{"depth_reached":{"description":"實際展開的深度：`point`（未展開）| `edge`（一跳鄰居）。","type":"string"},"edge":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GraphEdge","description":"一跳鄰居篩檢結果；未展開時為 null。"}]},"paths":{"description":"多跳路徑（目前保留欄位，恆為空陣列）。","items":{},"type":"array"},"reason":{"description":"展開 / 未展開的原因代碼。","type":"string"},"score":{"description":"本維度分數，0–100。未展開時為 0。","format":"double","type":"number"}},"required":["score","depth_reached","reason"],"type":"object"},"GraphEdge":{"description":"一跳鄰居篩檢結果。","properties":{"direct_sanctioned":{"description":"是否有鄰居直接命中制裁名單。","type":"boolean"},"neighbors_hit":{"description":"篩檢後命中風險標籤的鄰居數。","format":"int64","type":"integer"},"neighbors_screened":{"description":"實際送去情資篩檢的鄰居數（有上限，故可能小於 `neighbors_total`）。","format":"int64","type":"integer"},"neighbors_total":{"description":"一跳鄰居總數。","format":"int64","type":"integer"},"risky_exposure_ratio":{"description":"風險曝險占比，0.0–1.0（風險鄰居的金額占比）。","format":"double","type":"number"},"risky_neighbors":{"description":"風險鄰居明細（依貢獻排序，最多 5 筆）。","items":{},"type":"array"}},"required":["risky_exposure_ratio","neighbors_total","neighbors_screened","neighbors_hit","direct_sanctioned"],"type":"object"}}}} ``` ## The GraphEdge object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"GraphEdge":{"description":"一跳鄰居篩檢結果。","properties":{"direct_sanctioned":{"description":"是否有鄰居直接命中制裁名單。","type":"boolean"},"neighbors_hit":{"description":"篩檢後命中風險標籤的鄰居數。","format":"int64","type":"integer"},"neighbors_screened":{"description":"實際送去情資篩檢的鄰居數（有上限，故可能小於 `neighbors_total`）。","format":"int64","type":"integer"},"neighbors_total":{"description":"一跳鄰居總數。","format":"int64","type":"integer"},"risky_exposure_ratio":{"description":"風險曝險占比，0.0–1.0（風險鄰居的金額占比）。","format":"double","type":"number"},"risky_neighbors":{"description":"風險鄰居明細（依貢獻排序，最多 5 筆）。","items":{},"type":"array"}},"required":["risky_exposure_ratio","neighbors_total","neighbors_screened","neighbors_hit","direct_sanctioned"],"type":"object"}}}} ``` ## The HolderEntry object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"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"}}}} ``` ## The IntelDimension object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"IntelDimension":{"description":"情資維度明細。","properties":{"confidence":{"description":"情資信心，0.0–1.0。欄位語意同 `/v1/labels` 的 `label.confidence`。","format":"double","type":"number"},"entity":{"description":"實體名稱（與 `label` 同值，保留供既有整合使用）。","type":["string","null"]},"label":{"description":"實體名稱。","type":["string","null"]},"labels":{"description":"命中的標籤。欄位語意同 `/v1/labels` 的 `label.labels`。","items":{"type":"string"},"type":"array"},"score":{"description":"本維度分數，0–100。","format":"double","type":"number"}},"required":["score","confidence"],"type":"object"}}}} ``` ## The Meta object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"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"}}}} ``` ## The PaginationMeta object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"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"}}}} ``` ## The QueryMeta object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"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"}}}} ``` ## The ResolveRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"ResolveRequest":{"description":"`POST /v1/resolve` 的請求 body。\n\n宣告型別讓 `/docs` UI 帶出可填的 body 欄位（否則送空 POST 會撞 415）。","properties":{"blockchain":{"description":"鏈別（ethereum / bsc / tron …）。","type":"string"},"contracts":{"description":"contract-first（較防偽）：合約位址清單，元素為 `null` 代表原生幣。\n與 `symbols` 同時給時以 `contracts` 為準。","items":{"type":["string","null"]},"type":["array","null"]},"symbols":{"description":"要解析的 symbol 清單；省略 / 空 / 含 `all` 代表該鏈全部。","items":{"type":"string"},"type":["array","null"]}},"required":["blockchain"],"type":"object"}}}} ``` ## The RiskDecision object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"RiskDecision":{"description":"判定過程資訊。","properties":{"context":{"description":"套用的身分語境，例如 `exchange`。有語境時同樣的行為會被重新詮釋\n（交易所的高頻進出屬正常營運，混幣器的則加重）。無法判定身分時為 null。","type":["string","null"]},"context_confidence":{"description":"語境判定的信心，0.0–1.0。","format":"double","type":"number"},"gate_reason":{"description":"觸發的下限原因；未觸發為 null。可能值：\n\n- `ofac_sanctioned` — 此地址本身在制裁名單上。分數下限 100。\n- `confirmed_illicit` — 此地址本身帶有已確認的非法行為者標籤\n （暗網市場、勒索軟體、盜幣、釣魚等）。分數下限 90。\n- `direct_sanctioned_edge` — 此地址本身無標籤，但直接與制裁地址往來。分數下限 70。\n\n三者判定的是不同主體：前兩者看這個地址本身，最後一者看它的交易對手。","type":["string","null"]},"gated":{"description":"是否觸發硬性下限。為 `true` 時分數由下限決定，不受其他維度稀釋——\n一個被制裁的地址不會因為行為看起來正常就被拉低。","type":"boolean"}},"required":["gated","context_confidence"],"type":"object"}}}} ``` ## The RiskDimensions object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"RiskDimensions":{"description":"三個評估維度。","properties":{"behavior":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BehaviorDimension","description":"行為維度：這個地址「做了什麼」。**僅 Ethereum / Tron**；其他鏈或資料暫時\n不可用時為 null（此時 `meta.behavior_available` 為 false）。"}]},"graph":{"$ref":"#/components/schemas/GraphDimension","description":"拓樸維度：這個地址「跟誰往來」。只在情資與行為無法定案時才展開（成本較高）。"},"intel":{"$ref":"#/components/schemas/IntelDimension","description":"情資維度：這個地址「是誰」。全鏈支援。"}},"required":["intel","graph"],"type":"object"},"BehaviorDimension":{"description":"行為維度明細。","properties":{"behaviors":{"description":"偵測到的行為樣態明細。","items":{"$ref":"#/components/schemas/BehaviorHit"},"type":"array"},"data_window":{"$ref":"#/components/schemas/DataWindow","description":"本次掃描涵蓋的資料範圍。"},"deferred":{"description":"本次略過未評估的行為代碼（資料不足或成本考量）。","items":{"type":"string"},"type":"array"},"evaluated":{"description":"本次實際評估的行為代碼。","items":{"type":"string"},"type":"array"},"score":{"description":"套用身分語境**之後**的行為分數，0–100。與 `score_raw` 的差距即語境的影響。","format":"double","type":"number"},"score_breakdown":{"description":"分數計算過程（各行為貢獻與封頂後總分）。"},"score_raw":{"description":"套用身分語境**之前**的原始行為分數，0–100。","format":"double","type":"number"}},"required":["score_raw","score","behaviors","score_breakdown","data_window"],"type":"object"},"BehaviorHit":{"description":"單一行為樣態。","properties":{"code":{"description":"行為代碼，例如 `rapid_in_out` / `fan_out` / `burner_wallet` / `fan_in` / `pass_through`。","type":"string"},"context_weight":{"description":"身分語境對此行為的權重倍率（<1 為壓抑、>1 為放大）。語境不明時不出現。","format":"double","type":["number","null"]},"ever_detected":{"description":"歷史上是否曾偵測到。","type":"boolean"},"evidence":{"description":"觸發此判定的證據（欄位依行為代碼而異）。"},"first_detected_at":{"description":"首次偵測到此行為的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"last_detected_at":{"description":"最近一次偵測到此行為的時間（Unix epoch 秒，UTC）。距今越久，對分數的加權越低。","format":"int64","type":"integer"},"name_zh":{"description":"行為的中文名稱。","type":"string"},"occurrence_count":{"description":"偵測到的次數。","format":"int64","type":"integer"},"score":{"description":"此行為的得分（套語境前）。","format":"double","type":"number"},"score_after_context":{"description":"套用語境後的得分。語境不明時不出現。","format":"double","type":["number","null"]},"severity":{"description":"嚴重程度：`low` | `medium` | `high`。","type":"string"}},"required":["code","name_zh","severity","score","evidence"],"type":"object"},"DataWindow":{"description":"行為掃描涵蓋的資料範圍。","properties":{"from":{"description":"掃描起點：此地址最早一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"to":{"description":"掃描終點：此地址最近一筆活動的時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"tx_count":{"description":"涵蓋的轉帳筆數。為 0 代表這個地址在我方資料中沒有活動紀錄。","format":"int64","type":"integer"}},"required":["from","to","tx_count"],"type":"object"},"GraphDimension":{"description":"拓樸維度明細。","properties":{"depth_reached":{"description":"實際展開的深度：`point`（未展開）| `edge`（一跳鄰居）。","type":"string"},"edge":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GraphEdge","description":"一跳鄰居篩檢結果；未展開時為 null。"}]},"paths":{"description":"多跳路徑（目前保留欄位，恆為空陣列）。","items":{},"type":"array"},"reason":{"description":"展開 / 未展開的原因代碼。","type":"string"},"score":{"description":"本維度分數，0–100。未展開時為 0。","format":"double","type":"number"}},"required":["score","depth_reached","reason"],"type":"object"},"GraphEdge":{"description":"一跳鄰居篩檢結果。","properties":{"direct_sanctioned":{"description":"是否有鄰居直接命中制裁名單。","type":"boolean"},"neighbors_hit":{"description":"篩檢後命中風險標籤的鄰居數。","format":"int64","type":"integer"},"neighbors_screened":{"description":"實際送去情資篩檢的鄰居數（有上限，故可能小於 `neighbors_total`）。","format":"int64","type":"integer"},"neighbors_total":{"description":"一跳鄰居總數。","format":"int64","type":"integer"},"risky_exposure_ratio":{"description":"風險曝險占比，0.0–1.0（風險鄰居的金額占比）。","format":"double","type":"number"},"risky_neighbors":{"description":"風險鄰居明細（依貢獻排序，最多 5 筆）。","items":{},"type":"array"}},"required":["risky_exposure_ratio","neighbors_total","neighbors_screened","neighbors_hit","direct_sanctioned"],"type":"object"},"IntelDimension":{"description":"情資維度明細。","properties":{"confidence":{"description":"情資信心，0.0–1.0。欄位語意同 `/v1/labels` 的 `label.confidence`。","format":"double","type":"number"},"entity":{"description":"實體名稱（與 `label` 同值，保留供既有整合使用）。","type":["string","null"]},"label":{"description":"實體名稱。","type":["string","null"]},"labels":{"description":"命中的標籤。欄位語意同 `/v1/labels` 的 `label.labels`。","items":{"type":"string"},"type":"array"},"score":{"description":"本維度分數，0–100。","format":"double","type":"number"}},"required":["score","confidence"],"type":"object"}}}} ``` ## The RiskFactor object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"RiskFactor":{"description":"影響分數的單一因子。","properties":{"code":{"description":"因子代碼。","type":"string"},"detail":{"description":"人可讀的說明。","type":["string","null"]},"dimension":{"description":"來自哪個維度：`intel` | `behavior` | `graph`。","type":"string"},"effect":{"description":"對分數的作用：`amplify`（放大）| `suppress`（壓抑）| `as_is`（不變）。","type":"string"},"weight":{"description":"該因子的權重 / 貢獻分數。","format":"double","type":["number","null"]}},"required":["dimension","code","effect"],"type":"object"}}}} ``` ## The RiskMeta object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"RiskMeta":{"description":"本次評估的覆蓋範圍。","properties":{"analysis_depth":{"description":"實際達到的分析深度：`intel_only` | `point` | `edge`。","type":"string"},"behavior_available":{"description":"行為維度是否可用。為 `false` 時 `dimensions.behavior` 為 null，\n綜合分數**不包含**行為訊號——不要把它當成完整評估。","type":"boolean"},"computed_at":{"description":"本次評估時間（Unix epoch 秒，UTC）。","format":"int64","type":"integer"},"graph_available":{"description":"拓樸維度是否展開。","type":"boolean"},"graph_reason":{"description":"拓樸維度展開 / 未展開的原因代碼。","type":"string"}},"required":["analysis_depth","behavior_available","graph_available","graph_reason","computed_at"],"type":"object"}}}} ``` ## The TraceRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"TraceRequest":{"description":"智能追蹤的請求參數。\n\n`track_setting`（時間範圍、向外 / 向內追蹤深度、回傳筆數上限、金額累計…）、\n`filter_criterias`（金額 / 幣別篩選）、`stop_track_condition`（停止追蹤條件）皆為選填；\n未提供時以預設行為追蹤。","properties":{"address":{"description":"起始追蹤地址。","type":"string"},"blockchain":{"description":"鏈別（tron / ethereum / bitcoin）。","type":"string"},"filter_criterias":{"description":"金額篩選條件陣列（symbol / min_value / max_value / sign）。"},"stop_track_condition":{"description":"停止追蹤條件（預留）。"},"track_setting":{"description":"追蹤參數（時間範圍、往外/往內深度、limit、金額累計等）。"}},"required":["blockchain","address"],"type":"object"}}}} ``` ## The TransactionsRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"TransactionsRequest":{"description":"`POST /v1/transactions` 的請求 body。","properties":{"address":{"description":"查詢的地址。","type":"string"},"blockchain":{"description":"鏈別（ethereum / bsc / tron …）。","type":"string"},"contracts":{"description":"contract-first：合約位址清單（與 symbols 二擇一，較防偽）。","items":{"type":["string","null"]},"type":["array","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"filter_criterias":{"description":"進階：per-symbol 金額區間篩選。","items":{"$ref":"#/components/schemas/FilterCriteria"},"type":["array","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"description":"要看的幣種 symbol；省略 / 含 `all` 代表全部。","items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"},"FilterCriteria":{"description":"幣別篩選條件（交易列表用）。","properties":{"max_value":{"format":"double","type":["number","null"]},"min_value":{"format":"double","type":["number","null"]},"sign":{"type":["string","null"]},"symbol":{"type":"string"}},"required":["symbol"],"type":"object"}}}} ``` ## The TransferBetweenRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"TransferBetweenRequest":{"description":"`POST /v1/counterparty/transfer-between`：兩地址之間的交易明細。","properties":{"address_a":{"type":["string","null"]},"address_b":{"type":["string","null"]},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"counterparty":{"description":"對手地址（`address_b` 為同義別名）。","type":["string","null"]},"direction":{"type":["string","null"]},"end_time":{"format":"int64","type":["integer","null"]},"limit":{"format":"int32","minimum":0,"type":["integer","null"]},"order":{"type":["string","null"]},"output_asset":{"type":["string","null"]},"page":{"format":"int32","minimum":0,"type":["integer","null"]},"sort":{"type":["string","null"]},"start_time":{"format":"int64","type":["integer","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]},"target":{"description":"主地址（`address_a` 為同義別名）。","type":["string","null"]}},"required":["blockchain"],"type":"object"}}}} ``` ## The WalletOverviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"WalletOverviewRequest":{"description":"`POST /v1/wallet-overview` 的請求 body（地址總覽：餘額、收付次數、首末活躍…）。","properties":{"address":{"type":"string"},"blockchain":{"type":"string"},"contracts":{"items":{"type":["string","null"]},"type":["array","null"]},"output_asset":{"type":["string","null"]},"symbols":{"items":{"type":"string"},"type":["array","null"]}},"required":["blockchain","address"],"type":"object"}}}} ``` ## The WebhookView object ```json {"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"components":{"schemas":{"WebhookView":{"description":"對外的訂閱視圖（不含 secret）。","properties":{"created_at":{"format":"date-time","type":"string"},"event_type":{"type":"string"},"id":{"format":"uuid","type":"string"},"status":{"type":"string"},"target_url":{"type":"string"}},"required":["id","target_url","event_type","status","created_at"],"type":"object"}}}} ``` # 更新紀錄 BCS Intelligence API 的最新更新與改進。 {% updates format="full" %} {% update date="2026-06-05" tags="feature" %} ## 資料 API 上線 新增一整批區塊鏈資料查詢端點，全部走同一把 `X-API-Key`、`{ data, meta }` 信封與 credit 計費。 ### 幣種與鏈（免費） * `GET /v1/chains`、`/v1/registry`、`/v1/assets`、`POST /v1/resolve` — 支援的鏈與幣種、完整 token registry、`symbol`／合約 → 資產規格解析。 ### 地址活動 * `POST /v1/transactions`、`/v1/counterparty`、`/counterparty/transfer-between`、`/counterparty/overview`、`/v1/balance-history`、`/v1/wallet-overview` — 交易列表、交易對手排行、兩地址明細與聚合、每日歷史餘額、地址總覽。 ### Token 持有結構 * `GET /v1/token/holders`、`/v1/token/concentration` — 持有者排行與集中度（HHI / Gini / Top-N 占比、有效持有人數）。 ### 情報與搜尋 * `GET /v1/labels` — 地址情報標籤（交易所 / 風險等，多來源）。 * `GET /v1/addresses/resolve`、`/v1/addresses/autocomplete` — 地址驗證 / 糾錯與前綴自動完成（autocomplete 免費）。 ### 匯率行情 * `GET /v1/rates`、`/v1/rates/history`、`/v1/rates/symbols` — 幣種 USD 時點 / 最新 / 歷史查價。 看完整內容開發者文件 {% endupdate %} {% update date="2026-06-02" tags="release" %} ## 首次發行 BCS Intelligence API 正式上線——面向政府單位、交易所、銀行、託管機構與量化基金的一站式鏈上情報解決方案。 ### 平台基礎 * **統一接入** — 一組 `X-API-Key`、一致的 `{ data, meta }` 回應信封。 * **用量計費** — credit 制計價，成功（2xx）才扣點，回應即時帶上成本與餘額。 * **彈性限流** — 依「API key + 端點」限流，超量可選擇拒絕或排隊等待。 * **可追溯** — 每個請求都有 `X-Request-Id` 並寫入審計紀錄。 ### 即時推送 * **Webhook 訂閱** — 登記網址即可接收鏈上事件，並以 HMAC 簽章驗證來源。 * **WebSocket 串流** — 建立長連線，低延遲接收即時事件。 ### 管理後台 * API key 的建立／撤銷、credit 加值、方案管理。 看完整內容開發者文件 {% endupdate %} {% endupdates %} # 資料 API 上線 在統一閘道之上新增一整批區塊鏈資料查詢端點。全部走同一把 `X-API-Key`、`{ data, meta }` 信封、credit 計費與 `X-Request-Id` 追蹤；線上互動式文件見 `/docs`。 ### 幣種與鏈（免費） * `GET /v1/chains` — 支援的鏈與幣種 * `GET /v1/registry` — 完整 token registry * `GET /v1/assets?chain=` — 某鏈的代幣 * `POST /v1/resolve` — `symbol` / 合約 → 資產規格（含 decimals） ### 地址活動 * `POST /v1/transactions` — 交易列表 * `POST /v1/counterparty` — 交易對手排行 * `POST /v1/counterparty/transfer-between` — 兩地址交易明細 * `POST /v1/counterparty/overview` — 兩地址聚合統計 * `POST /v1/balance-history` — 每日歷史餘額 * `POST /v1/wallet-overview` — 地址總覽 ### Token 持有結構 * `GET /v1/token/holders` — 持有者排行 * `GET /v1/token/concentration` — 集中度（HHI / Gini / Top-N 占比、有效持有人數） ### 情報與搜尋 * `GET /v1/labels` — 地址情報標籤（交易所 / 風險等，多來源） * `GET /v1/addresses/resolve` — 地址驗證 / 糾錯 * `GET /v1/addresses/autocomplete` — 前綴自動完成（免費） ### 匯率行情 * `GET /v1/rates` — 時點 / 最新查價（批次） * `GET /v1/rates/history` — 歷史價序列 * `GET /v1/rates/symbols` — 有資料的幣種
計費（credit） * **免費（0）**：chains、registry、assets、resolve、addresses/autocomplete、rates、rates/symbols * **5**：transactions、counterparty 系、balance-history、wallet-overview、labels、addresses/resolve、rates/history * **10 / 15**：token/holders（10）、token/concentration（15）——查詢較重
# 首次發行 BCS Intelligence API 正式上線。本次發行提供一套完整的企業級接入基礎，讓你以一致、安全、可計費的方式存取區塊鏈服務。 ### 統一 API 接入 * 以 `X-API-Key` 認證，所有成功回應採 `{ data, meta }` 信封，錯誤採 `{ error: { code, message } }`。 * 列表型端點採 `limit`／`offset` 分頁。 閱讀文件 ### 用量計費 * credit 制計價，**只有成功（2xx）回應才扣點**。 * 每個成功回應帶 `X-Credit-Cost` 與 `X-Credit-Remaining`。 * 每筆扣點寫入帳本並關聯 `request_id`，可供對帳。 ### 限流 * 依「API key + 端點」限流，依方案設定 RPS 與 Burst。 * 超量可選 `reject`（回 429，附 `Retry-After`）或 `wait`（排隊等待）。 ### 即時推送 * Webhook 訂閱：建立／列出／刪除，事件以 HMAC 簽章驗證來源。 * WebSocket 串流：`/v1/stream` 長連線即時接收事件。 ### 管理後台 * 管理員以帳號密碼登入控制平面。 * 管理 API key（建立／撤銷／調整 credit）與方案。
安全性 * API key 僅保存雜湊值，不保存明碼。 * 管理員密碼以單向雜湊保存。 * 每個請求皆有追蹤碼並寫入審計紀錄。
# 說明中心 常見問題、計費、管理與疑難排解。 需要協助嗎？這裡彙整了使用 BCS API 時最常見的問題。找不到答案時，歡迎聯絡你的客戶經理。

:rocket-launch:

上手檢查清單/pages/JhPRlHrBZxxcG651MQZw

:coins:

Credit 計費怎麼運作/pages/Jbfbus9Z5XZsBxCgbEaX

:key:

管理 API key/pages/ITeWE3GGOFUsJHas41Xf

:wrench:

請求失敗怎麼辦/pages/33RwL2j2uqca73K5Yyi7
{% hint style="info" %} 要找技術細節（端點、參數、回應結構）嗎？請見[開發者文件](https://api.blockchainsecurity.asia/docs)。 {% endhint %} # 上手檢查清單 從零到第一次成功呼叫的步驟清單。 依序完成下列項目，即可開始使用 BCS API。 * [ ] **取得 base URL** — 向你的客戶經理確認正式服務網址（本文件以 `https://api.blockchainsecurity.asia` 示意）。 * [ ] **取得 API key** — 請你方管理員在管理後台建立一把 key，並保存一次性回傳的明碼（`ak_live_…`）。 * [ ] **確認連線** — 呼叫 `GET /healthz`，應回 `{"status":"ok"}`。 * [ ] **發出第一個已認證請求** — 在 `X-API-Key` header 帶上 key，呼叫任一 `/v1` 端點。 * [ ] **確認回應格式** — 成功回應為 `{ data, meta }`；記下回應 header 的 `X-Request-Id`。 * [ ] **掌握餘額** — 從 `X-Credit-Remaining` 追蹤 credit 餘額。 * [ ] **設定錯誤處理** — 依錯誤碼與 `Retry-After` 實作重試（見[請求失敗怎麼辦](/help-center/zheng-he-yu-yi-nan-pai-jie/troubleshooting-failed-requests)）。 {% hint style="success" %} 完成以上步驟後，建議接著閱讀[開發者文件](https://api.blockchainsecurity.asia/docs)了解各端點細節。 {% endhint %} # 能查到什麼 BCS API 能查到哪些區塊鏈資料。 透過一把 API key，你可以查詢以下幾類資料。完整參數、`curl` 範例與回應結構見[開發者文件](https://api.blockchainsecurity.asia/docs)。 | 分類 | 能做什麼 | 主要端點 | | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------- | | **Assets & Market Data** | 支援哪些鏈／幣、symbol→資產解析、USD 時點 / 歷史查價 | `/v1/chains`、`/v1/registry`、`/v1/resolve`、`/v1/rates` | | **On-chain Data** | 交易列表、交易對手、歷史餘額、地址總覽、持有者排行與集中度 | `/v1/transactions`、`/v1/counterparty`、`/v1/wallet-overview`、`/v1/token/holders` | | **Risk & Intelligence** | 地址情報標籤、ML 地址分類、行為風險評分 | `/v1/labels`、`/v1/address-classify`、`/v1/address-risk` | | **Investigation** | 多跳金流路徑追蹤、Bitcoin 找零偵測 | `/v1/trace`、`/v1/btc/change-address` | | **Cross-chain** | 跨鏈橋接續追蹤資金去向 | `/v1/cross-chain` | | **Address Utilities** | 地址驗證 / 糾錯、前綴自動完成 | `/v1/addresses/resolve`、`/v1/addresses/autocomplete` | | **Events** | 鏈上事件 webhook 主動推播 | `/v1/webhooks` | ## 計費 多數查詢成功才扣 credit；中繼資料類（幣種、自動完成、查價）免費。每次回應 header 帶 `X-Credit-Cost` 與 `X-Credit-Remaining`。詳見 [Credit 計費怎麼運作](/help-center/fang-an-yu-ji-fei/how-credit-billing-works)。 {% hint style="info" %} 要看每支端點的完整 `curl` 與回應範例、線上試打，請到[開發者文件 `/docs`](https://api.blockchainsecurity.asia/docs)。 {% endhint %} # 資料平面與控制平面 應用程式用的 API 與管理員用的後台有何不同。 BCS API 把「使用服務」與「管理帳號」分成兩個獨立平面。搞懂它們的差別，能幫你決定該用哪種認證、誰負責什麼。 | | 資料平面 | 控制平面 | | ----- | -------------------- | ------------------------ | | 給誰用 | 你的應用程式 | 你方管理員 | | 端點 | `/v1/*` | `/admin/api/*` | | 認證 | API key（`X-API-Key`） | 帳號密碼登入 + session | | 計費／限流 | 有 | 無 | | 典型操作 | 呼叫業務 API、訂閱 webhook | 建立／撤銷 key、調整 credit、管理方案 | ## 什麼時候用哪個 * **開發整合、串接服務** → 資料平面。你只需要一把 API key。 * **發放金鑰、控管用量、加值 credit** → 控制平面。由管理員在後台操作。 {% hint style="info" %} 一般開發者**不需要**控制平面的帳號；只要向管理員索取一把 API key 即可開始。 {% endhint %} 相關說明：[管理 API key](/help-center/guan-li/managing-api-keys)。 # Credit 計費怎麼運作 credit 如何扣點、如何查餘額、如何加值。 BCS API 採 credit（點數）制計費。 ## 重點 * 每把 API key 有自己的 **credit 餘額**。 * 每個端點有各自的**成本權重**；呼叫時依權重扣點。 * **只有成功（HTTP 2xx）的回應才扣點**——錯誤不扣。 * 管理／健康檢查類端點成本為 0。 ## 怎麼知道花了多少 每個成功回應都會帶： | 來源 | 欄位 | | -------------------------------------------- | ----- | | Header `X-Credit-Cost` | 本次扣除 | | Header `X-Credit-Remaining` | 扣除後餘額 | | `meta.credit_cost` / `meta.credit_remaining` | 信封內版本 | ## 餘額不足怎麼辦 餘額不足時，請求回 `402 insufficient_credit`，且不會扣點。請聯絡你方管理員加值。 ## 如何加值 加值由管理員於管理後台操作（為指定 key 增加 credit）。詳見[管理 API key](/help-center/guan-li/managing-api-keys)。 ## 如何調整方案 方案決定限流（RPS／Burst）與每月 credit 配額。需要調整方案時，請聯絡你的客戶經理，或由管理員建立新方案後將 key 套用過去。 {% hint style="info" %} 每筆扣點都會寫入帳本並關聯 `request_id`，可供事後對帳。需要用量明細請洽客戶經理。 {% endhint %} # 計費常見問題 關於 credit 與計費的常見問題。
失敗的請求會扣 credit 嗎？ 不會。credit **只在成功（2xx）回應時**扣除。任何 4xx／5xx 錯誤都不扣點。
我怎麼即時知道餘額？ 每個成功回應的 `X-Credit-Remaining` header（以及 `meta.credit_remaining`）都會帶當前餘額。建議在你的系統中記錄此值，於低水位時提前告警。
每次呼叫扣多少點？ 依端點而定，每個端點有各自的成本權重。實際扣除量會出現在回應的 `X-Credit-Cost`。管理與系統端點為 0。
餘額用完了會怎樣？ 請求會回 `402 insufficient_credit` 並停止計費。請聯絡管理員加值後即可恢復。
不同 API key 的 credit 會共用嗎？ 不會。每把 key 有獨立的餘額，互不影響。這也方便你針對不同整合分別控管用量。
我可以查歷史用量嗎？ 系統會將每筆扣點寫入帳本並關聯 `request_id`。如需用量明細報表，請聯絡你的客戶經理。
# 管理 API key 管理員如何建立、撤銷與加值 API key。 API key 讓你的應用程式以程式化方式存取 BCS API。管理員可在管理後台隨時建立、檢視、撤銷 key 與調整 credit。 ## 建立 key 在後台建立 key 時，指定**名稱**、**方案**與**初始 credit**。建立後系統會回傳一次性的明碼 key。 {% hint style="warning" %} 明碼 key（`ak_live_…`）**只會出現這一次**，請當場交付給使用者並妥善保存。系統只保存雜湊值，遺失只能撤銷後重建。 {% endhint %} 請給每把 key 一個能辨識用途的名稱（例如「行動 App」「對帳排程」），方便日後稽核。 ## 撤銷 key 在後台找到該 key 按撤銷。撤銷**立即生效**——之後使用該 key 的請求一律回 `401`。 ## 調整 credit 可為任一 key 增減 credit（`delta` 可正可負）。加值後使用者即可繼續呼叫。 ## key 的狀態 | 狀態 | 意義 | 請求結果 | | --------- | ------- | ------------------ | | active | 正常 | 通過認證 | | suspended | 暫停（如欠費） | `403 forbidden` | | revoked | 已撤銷 | `401 unauthorized` | ## 最佳實務 * **一整合一把 key** — 方便個別撤銷與用量追蹤。 * **最小權限** — 只發放必要的 credit 與方案額度。 * **定期盤點** — 撤銷不再使用的 key。 * **安全保管** — 提醒使用者把 key 放在伺服器端密鑰管理，勿入版本控制或前端。 詳細的 API 操作見[開發者文件的管理後台章節](https://api.blockchainsecurity.asia/docs)。 # 管理員帳號與安全 管理員帳號的登入、安全與最佳實務。 管理員帳號用來登入控制平面（管理後台），管理 API key、credit 與方案。它與資料平面的 API key 完全分離。 ## 登入方式 管理員以**帳號（email）+ 密碼**登入，成功後取得一個 httpOnly 的 session cookie。後續操作帶上該 cookie 即可，登出會立即使 session 失效。 ## 帳號安全 * 密碼以單向雜湊安全保存，系統不保存明碼。 * 首次由系統建立的帳號可能被要求**首次登入即改密碼**。 * session 有存活時間，閒置過久需重新登入。 ## 最佳實務 * 使用**強密碼**，並避免多人共用同一帳號。 * 僅授予真正需要的人員後台存取權。 * 離職或轉職時，及時停用對應帳號。 * 透過後台定期檢視 API key 列表，撤銷不再使用的 key。 {% hint style="info" %} 需要新增管理員帳號，或調整方案與額度時，請聯絡你的客戶經理。 {% endhint %} # 串接你的應用程式 把你的應用程式接上 BCS API。 把應用程式接上 BCS API 只需幾個步驟。 {% stepper %} {% step %} #### 取得 base URL 與 API key 向客戶經理取得正式 base URL，向管理員取得一把 API key。 {% endstep %} {% step %} #### 在每個請求帶上 key 於 HTTP header 加入 `X-API-Key: ak_live_…`。建議將 key 存於環境變數或密鑰管理服務。 {% endstep %} {% step %} #### 解析統一信封 成功讀 `data`／`meta`，失敗讀 `error.code`。以 `code` 做程式判斷，`message` 僅供顯示。 {% endstep %} {% step %} #### 處理計費與限流 讀 `X-Credit-Remaining` 掌握餘額；對 `429` 遵守 `Retry-After`，對 `5xx` 採退避重試。 {% endstep %} {% step %} #### 設定即時通知（選用） 需要鏈上事件即時通知時，建立 [Webhook 訂閱](https://api.blockchainsecurity.asia/docs)或使用 WebSocket 串流。 {% endstep %} {% endstepper %} ## 小提醒 * 自帶 `X-Request-Id` 可串接你自己的追蹤系統；不帶則由系統產生。 * 將不同用途的整合各用一把 key，方便個別控管與撤銷。 遇到問題？見[請求失敗怎麼辦](/help-center/zheng-he-yu-yi-nan-pai-jie/troubleshooting-failed-requests)。 # 請求失敗怎麼辦 常見錯誤的原因與排解。 請求失敗時，先看回應的 `error.code`，再對照下表處理。回報問題時，請附上回應 header 的 `X-Request-Id`。
401 unauthorized * 確認有帶 `X-API-Key` header，且值正確無多餘空白。 * 確認該 key 未被撤銷。 * 為避免洩漏 key 是否存在，查無此 key 與已撤銷都回同樣的 401。
403 forbidden key 有效但被停用（例如欠費）。請聯絡管理員恢復或加值。
402 insufficient_credit credit 餘額不足。請管理員加值後重試。注意：加值前重試只會再次失敗。
429 rate_limited 觸發限流。請依回應的 `Retry-After`（秒）等待後再試，並在客戶端採用指數退避，避免立即重打。
400 bad_request 請求參數或格式有誤。常見原因：`limit` 超過 1000、JSON 格式錯誤、缺少必填欄位、`target_url` 未以 `http(s)://` 開頭。修正後重送。
404 not_found 資源不存在。檢查路徑與 ID；注意 webhook 只能操作該 key 自己的訂閱。
502 / 503 後端暫時異常或服務過載。請稍後以退避策略重試。若持續發生，附 `X-Request-Id` 聯絡支援。
500 internal_error 非預期的內部錯誤。請附上 `X-Request-Id` 聯絡你的客戶經理協助定位。
{% hint style="success" %} 記得：任何錯誤回應都**不會**扣 credit。 {% endhint %} # 限流與配額 限流如何運作，以及如何優雅地因應。 為確保服務穩定與公平使用，BCS API 會對每把 API key 限流。 ## 限流如何運作 * 維度為 **「API key + 端點」**——同一把 key 對不同端點各有獨立額度。 * 額度由方案的 **RPS**（每秒請求數）與 **Burst**（突發容量）決定。 ## 超量時 依方案設定有兩種行為： | 行為 | 結果 | | ------ | -------------------------------------- | | Reject | 立即回 `429 rate_limited`，附 `Retry-After` | | Wait | 在容量內短暫排隊，等到有額度自動放行；佇列滿則回 `503` | ## 如何優雅因應 * 收到 `429` 時，**遵守 `Retry-After`** 再重試。 * 採用**指數退避**，避免雪崩式重打。 * 在客戶端設定合理併發上限，平滑送出請求。 ## 需要更高額度？ 請聯絡你的客戶經理調整方案，或請管理員將 key 套用到更高 RPS／Burst 的方案。 延伸閱讀：[開發者文件 — 限流](https://api.blockchainsecurity.asia/docs)。