地址篩查¶

地址篩查由獨立 Public API 提供。請使用目標環境提供的篩查服務基礎 URL，不要假定這些路徑與交易 API 共用主機。公開查詢無需交易 API Key。各版本是否可用取決於部署。

此處“公開查詢”指面向外部整合的查詢契約，不代表所有部署均允許匿名公網訪問。請使用服務方提供的入口並遵守其訪問與頻率限制。查詢結果不能代替交易准入，也不提供內部服務呼叫憑據。

接口與版本¶

當前狀態查詢均使用 POST 和 JSON 請求體。不同版本的判斷語義與回應結構不同，接入時應明確選擇版本。

單條請求¶

{
  "chain_family": "evm",
  "address": "0x1111111111111111111111111111111111111111"
}

批量請求¶

{
  "chain_family": "evm",
  "addresses": [
    "0x1111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222"
  ]
}

解讀當前結果¶

v1 與 v3¶

v1 回傳 schema_version、request_id、decision、is_sanctions_match、provider_id、policy_id、capability、dataset_revision、checked_at、authority_checked_at。批量增加 decision_count，並用對應陣列替換單條判斷和布爾值。

v3 除判斷和布爾值外，還回傳 coverage_status（COMPLETE / PARTIAL）、coverage_incomplete、evidence_mode（LOCAL_SNAPSHOT_MATCH / LOCAL_SNAPSHOT_NO_MATCH）、可爲 null 的 reason_code、policy_revision、serving_policy_id、serving_policy_revision、dataset_published_at。覆蓋不完整時 reason_code="SOURCE_COVERAGE_INCOMPLETE"。批量證據使用 evidence_modes 陣列，reason_code 仍是外層單一欄位。

NO_MATCH 僅表示在所查詢的數據集中未命中，不能解釋爲錢包安全的整體保證。覆蓋不完整時，本地未命中不等於完整的否定證據。

v4–v6¶

v4 包含 address、可爲 null 的 match_type、official_dataset_revision、official_coverage_mode（COMPLETE / POSITIVE_ONLY）、可爲 null 的 composite_generation、composite_revision、composite_policy_digest，以及 checked_at。

v5/v6 還回傳 official_state、composite_state（MATCH、NO_MATCH、STALE、UNKNOWN、UNAVAILABLE），可爲 null 的 official_membership_digest、composite_membership_digest、combined_membership_revision，以及 negative_evidence_complete。官方身份信息不可用時，相應欄位可以爲 null。可用來源的肯定證據仍可確定 BLOCK；不能將缺失來源證據轉換爲明確未命中。

v6 增加 details_status：AVAILABLE、UNAVAILABLE、INCONSISTENT、NOT_REQUESTED。對 COMPOSITE_CONFIRMED，詳情不可用或不一致時仍應保留 BLOCK 判斷。v4–v6 批量外層包含 schema_version、request_id、decision_count 和有序 results，每項使用對應版本的單條結果欄位。

v2 歷史摘要¶

單條查詢回傳 result 對象，批量回傳 results。每項摘要包含：

外層包含 coverage_status、coverage_incomplete、history_coverage、policy_id、policy_revision、dataset_revision、checked_at、dataset_published_at、valid_until。單條回應還有 history_status（SUMMARY_ONLY / UNAVAILABLE）。history_coverage 包含 status（COMPLETE、PARTIAL、CURRENT_ONLY）、complete、available_from、basis。沒有歷史記錄不代表地址從未被列入名單。

歷史分頁¶

POST /api/v2/address-screening-histories

身份驗證： 無。

請求體¶

{
  "chain_family": "evm",
  "address": "0x1111111111111111111111111111111111111111",
  "page_size": 25,
  "cursor": null
}

每個歷史區間包含 period_id、source_id、authority、jurisdiction、measure_type、可選 subject_name / legal_reference、官方與系統有效時間區間、起止事件標識/類型/原因、被替代事件引用和 policy_applications。官方生效時間與系統觀測時間是不同事實。has_more 爲 false 時 next_cursor 爲 null。無效或過時遊標可能被拒絕，應從第一頁重新查詢，不要猜測遊標。

來源與歷史記錄欄位¶

每條 current_origins 包含 source_id、authority、jurisdiction、可爲空的 subject_name、legal_reference、measure_type、current_state（ACTIVE / REMOVAL_PENDING），以及可爲空的 official_effective_from / official_effective_to。

每條策略記錄包含 policy_id、policy_revision、participation_mode（required / optional）、applicable_from 和可爲空的 applicable_to。history_coverage.basis 爲 OFFICIAL_ARCHIVE、CURATED_BACKFILL、FIRST_VERIFIED_SNAPSHOT 或 MIXED。日期時間序列化爲 ISO 格式字串。遊標爲 16–256 個 URL 安全字符，必須原樣保留回傳值。

錯誤¶

協定錯誤和限流使用下面的最小結構，不保證包含 schema_version 或 error.retryable：

{
  "request_id": "00000000000000000000000000000001",
  "error": {
    "code": "INVALID_REQUEST"
  }
}

篩查不可用回傳 HTTP 503、Retry-After: 5 與：

{
  "schema_version": "sanctions-screening.error.v1",
  "request_id": "00000000000000000000000000000001",
  "error": {
    "code": "SCREENING_UNAVAILABLE",
    "retryable": true
  }
}

歷史查詢不可用也回傳 503 與 Retry-After: 5，但使用獨立結構：

{
  "schema_version": "sanctions-screening.history-error.v2",
  "request_id": "00000000000000000000000000000001",
  "history_status": "UNAVAILABLE",
  "error": {
    "code": "HISTORY_UNAVAILABLE",
    "retryable": true
  }
}

按 HTTP 狀態和 error.code 分支，存在 Retry-After 時遵循該值。缺少 retryable 不等於明確 false。無效輸入應修正後再提交；技術錯誤不能當作 NO_MATCH 或 NO_BLOCK。這些結構不同於交易 API 的 detail 回應。

運維探針¶

這些端點用於部署、負載均衡和監控，建議僅透過受限的運維入口訪問。客戶接入不需要輪詢這些探針。部分探針會查詢下游依賴並返回執行狀態；列入文件不代表應將其直接開放到公網。

存活探針回傳 200 不代表策略覆蓋完整。公開查詢結果不能授權後續交易；交易接口會自行執行准入檢查。