地址筛查¶

地址筛查由独立 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 不代表策略覆盖完整。公开查询结果不能授权后续交易；交易接口会自行执行准入检查。