> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/api-reference/readme/models.md). # 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）。","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"}}}} ```