> 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/risk-and-intelligence/di-zhi-feng-xian-ping-fen.md).

# 地址風險評分

綜合地址的情資、行為與拓樸關係評估風險：情資維度提供標籤/實體/分類，行為維度偵測快速進出、分散轉出、一次性錢包、分層歸集等模式，拓樸維度評估交易對手與圖譜暴露。回傳 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）。","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","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":["地址風險評分"]}}}}
```