按需钱包筛查 API：无需交易即可筛查

有时您需要在任何交易记录生成之前检查加密货币钱包的 AML 风险，例如客户添加提现地址时，或合规团队希望临时审查某个地址时。按需钱包筛查 endpoint 可以对单个地址进行筛查，并返回完整的风险结果，且不会创建交易。这是自动加密货币筛查的独立对应功能，后者在交易提交过程中运行。两者使用相同的区块链分析服务商，并返回相同的结果结构。

适用场景

使用场景	endpoint
在没有需要记录的交易时预先检查地址	钱包筛查 — `POST /v3/wallet-screening/`
在已记录的充值/提现中筛查钱包	带有 `currency_kind: "crypto"` 的创建交易

钱包筛查不会向交易表写入任何内容。如果您需要将筛查结果附加到受监控的交易上（包括规则、警报和 Webhook），请改为提交交易。

前提条件

应用必须配置交易监控，可以使用托管服务商，也可以使用现有服务商密钥。请在 Business Console 中的交易 > 设置 > Provider Preferences 进行配置。如果未配置服务商，endpoint 将返回 409 Conflict。

请求

POST https://verification.didit.me/v3/wallet-screening/ 使用 x-api-key 请求头进行身份验证。

字段	类型	是否必填	描述
`wallet_address`	字符串	是	要筛查的地址或网络标识符。必须与所选网络匹配，例如以 `0x` 开头加 40 个十六进制字符的 EVM 链地址，或您的服务商接受的 Lightning 标识符。别名：`address`。
`blockchain`	字符串	否	资产/网络标识符。省略时，Didit 会根据地址格式识别网络：`bc1`、`1` 和 `3` 开头的地址为比特币（`BTC`），`T` 开头的地址为 Tron（`TRX`），base58 公钥为 Solana（`SOL`）。`0x` 地址在所有 EVM 网络上都有效，因此会返回 `422` 及 `candidate_chains`，不会进行筛查，也不会计费；请设置网络后重新提交。其他格式返回 `400`。可接受的值：`BTC`、`LIGHTNING`、`ETH`、`LTC`、`XRP`、`BCH`、`DOGE`、`TRX`、`SOL`、`MATIC`、`BNB`、`BASE`、`OP`、`ARB`、`AVAX`、`ADA`、`XLM`、`HBAR`、`CELO`、`MODE`、`PLUME`、`USDT`、`USDC`。也接受常见网络名称，例如 `POLYGON` 或 `POL` 表示 `MATIC`，`BSC` 表示 `BNB`，`TRON` 表示 `TRX`。别名：`currency`。
`direction`	字符串	否	`inbound`、`outbound`、`deposit` 或 `withdrawal`。为服务商提供的可选上下文；如需转账前的中立筛查，请省略。它不会改变返回的 `risk_score`、`severity` 或资金流向细分（参见响应下的说明）。

链覆盖范围

托管筛查支持 Base（BASE）、Optimism（OP）和 Arbitrum One（ARB），同时支持钱包筛查和交易哈希筛查。已接入的服务商的覆盖范围可能不同；链还必须得到您所选服务商和账户的支持。 Celo（CELO）、Mode（MODE）和 Plume（PLUME）通过已接入的 TRM Labs 账户进行筛查（Marketplace，自带密钥）；托管筛查不覆盖这些网络，并返回 400。请勿将 ETH 用于其他 EVM 网络：同一地址在每条链上的活动和风险可能不同。使用托管筛查时，USDT 和 USDC 是以太坊的旧版别名，而不是对这些代币存在的所有网络进行搜索。请使用网络标识符（ETH、TRX、SOL、MATIC、BNB、BASE、OP、ARB、AVAX、ADA、XLM、HBAR，或通过 TRM Labs 使用 CELO、MODE 或 PLUME）指定钱包实际所在的链。对于已记录交易中的代币，请将代币保留在 transaction_details.currency 中，并在 transaction_details.crypto_params.crypto_chain 中单独指定网络。参见资产与网络选择。

仅当应用在控制台 Marketplace 中已接入 Elliptic 或 Chainalysis 的 BYOK 服务商时，才可使用 LIGHTNING。使用托管的 Merkle Science、Crystal 或 TRM Labs 时不可用。未接入受支持服务商的请求将返回 400，不会进行筛查，也不会计费。

curl -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
    "blockchain": "ETH"
  }'

响应

响应是标准化的筛查结果，其结构与交易筛查返回的 WALLET_SCREENING 提供方结果完全相同。

字段	类型	说明
`provider`	字符串	筛查该地址的提供方（`merklescience`、`crystal`、`chainalysis`、`elliptic`、`trmlabs`）。
`screening_type`	字符串	始终为 `WALLET_SCREENING`。
`risk_score`	整数	标准化的 0–100 风险分数。Merkle Science 将地址评为 `0-5`，分别对应 `0`、`15`、`35`、`55`、`75` 或 `95`。
`severity`	字符串	根据 `risk_score` 得出的风险区间（见下方说明）：`UNKNOWN`、`LOW`、`MEDIUM`、`HIGH` 或 `CRITICAL`。
`status`	字符串	`SCREENED`、`PENDING` 或 `ERROR`。
`summary`	字符串	供人阅读的摘要。
`wallet_address`	字符串	被筛查的地址。
`blockchain`	字符串	被筛查的区块链。
`sanctions_hit`	布尔值	当被筛查钱包本身受制裁，或其任一交易对手的资金来自受制裁实体（风险敞口）时为 `true`。该字段不区分这两种情况。
`pep_counterparty`	布尔值 \| null	政治公众人物（PEP）风险敞口。当没有可用的 PEP 结果时为 `null`，目前所有结果都是这种情况，因为没有任何提供方报告 PEP 结果；只有在明确的否定筛查结果时才为 `false`。请勿将 `null` 理解为已完成 PEP 检查。
`dominant_risk_category`	字符串 \| null	权重最高的高风险类别，或 `null`。
`risk_factors`	数组	`risk_score` 的排序解释，即得出该判定的原因。参见风险因素。
`source_of_funds`	数组	资金来源，按实体列出。参见风险敞口明细。
`destination_of_funds`	数组	资金去向，按实体列出。条目结构与 `source_of_funds` 相同。
`counterparty_connections`	数组	提供方将该地址归属的实体。参见交易对手关联。
`network_nodes`、`network_edges`	数组	交易筛查的风险敞口图谱。在钱包筛查结果中为空。
`transaction_hash`、`block_timestamp`、`total_value_usd`、`fee_usd`、`transaction_flows_status`、`transaction_flows_error`	null	交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。
`sender_rows`、`receiver_rows`、`transaction_flows`	数组	交易筛查字段。在钱包筛查结果中始终为空。
`raw_response`	对象	提供方自身的原始载荷。其结构因提供方而异，且可能在不另行通知的情况下变化：请读取上面的标准化字段，而不要解析它。
`report_signature`	字符串	针对本结果的不透明签名，作用范围限定在您的应用内。请原样重新提交响应（包括此字段），以渲染为 PDF。

severity 的设定方式。 severity 是标准化 risk_score 所在的区间：0-9 → UNKNOWN，10-39 → LOW，40-69 → MEDIUM，70-89 → HIGH，90-100 → CRITICAL。UNKNOWN 是最低的区间，而不是单独的”无数据”状态：risk_score: 0（常见的干净地址情况）表示提供方没有返回不利评估，而 1-9 范围内的非零分数是真实存在但低于 LOW 的信号，因此应直接查看 risk_score 本身，而不只看区间。无论哪种情况，都不要将 UNKNOWN 显示为明确的”安全”或”通过”。direction 不会改变风险模型。 可选的 direction 字段仅作为背景信息传递给提供方。它不影响 risk_score、severity，也不影响返回哪些明细列表：source_of_funds 和 destination_of_funds 始终都会返回。因此，更改或省略 direction 不需要对已筛查过的地址重新筛查。

风险因素

risk_factors 是对”该地址为何得到这一分数”的排序解释。提供方使用自己的模型对地址评级，只返回判定结果。例如 Merkle Science 返回 0-5 的整数，因此仅凭 risk_score 无法采取行动。每个条目列出一个驱动因素，先按高风险排序，再按经过该因素的金额排序。

字段	类型	说明
`source`	字符串	`attribution`（提供方认定该地址是什么，即其自身的标签或聚类）或 `exposure`（其资金实际流经的去向）。
`category`	字符串	标准化风险类别，与风险敞口明细使用相同的词汇表。
`label`	字符串	提供方自己的表述，例如 `Gambling / Crypto only`。在界面中使用此字段，因为它与您在提供方控制台中看到的内容一致。
`entity_name`	字符串 \| null	归属的实体，例如赌博网站或交易所。本页示例使用 `Example Gambling` 等占位符。
`direction`	字符串	`incoming`（转入）、`outgoing`（转出）、`connected`（关联）、`attribution`（该地址自身的标签），或当提供方未报告方向时为 `unknown`。
`exposure_type`	字符串	`direct`（1 跳）、`indirect`（多跳）、`attribution`（该地址自身的标签），或当提供方未说明交易对手相隔几跳时为 `unknown`。请将 `unknown` 视为未分类，切勿视为 `direct`。
`amount_usd`	数字 \| null	归属于该驱动因素的美元金额。
`percentage`	数字	占该地址总筛查金额的比例，转入和转出合并计算。这与 `source_of_funds` / `destination_of_funds` 中的 `percentage` 不同，后者按各方向分别标准化。该值可在整个列表中进行比较和求和。
`is_high_risk`	布尔值	该类别是否属于 Didit 视为高风险的类别（`sanctioned`、`mixer`、`stolen_funds`、`ransomware`、`scam`、`darknet_market`、`terrorist_financing`、`child_exploitation`、`hacked_exchange`、`high_risk_exchange`、`seized_funds`）。
`description`	字符串	对该驱动因素的单行描述，例如 `9.01% indirect outgoing exposure to Gambling / Crypto only (Example Gambling)`。

分数高但没有 is_high_risk 因素，是一个真实且有意义的结果。 这表示提供方仅依据其自身的风险敞口模型对地址评级，并未报告制裁、PEP 或已归属实体的匹配。列出的因素正是构成该评级的资金流向。summary 对此有明确说明，因此应将这类地址视为”需要审查资金流向”，而不是已确认的命中。risk_factors 最多只列出五个最强的驱动因素；source_of_funds 和 destination_of_funds 始终提供完整明细。risk_factors 是顶层字段，而不是嵌套字段。 在该字段出现之前完成的筛查结果不包含此键。应将其视为空列表，而不是假定其解释为空。

风险敞口明细

source_of_funds / destination_of_funds 中的每一条记录，都描述该地址与之发生资金往来的一个实体：

字段	类型	说明
`category`	string	标准化的风险类别（`exchange_licensed`、`dex`、`defi`、`mixer`、`sanctioned`、`darknet_market`、`stolen_funds` 等）。
`entity_name`	string \| null	归因的实体，例如交易所、混币器或受制裁团体。本页示例使用占位符。
`entity_type`	string \| null	服务商的实体类型（`Exchange`、`DeFi`、`Sanctions`）。
`entity_subtype`	string \| null	更细的子类型（`Mandatory KYC and AML`、`OFAC`）。
`description`	string \| null	`entity_type / entity_subtype`，即服务商对该实体的标注。
`exposure_direction`	string	`incoming`、`outgoing` 或 `connected`。
`exposure_type`	string	`direct`（1 跳）或 `indirect`（多跳）。
`is_direct`	boolean	当 `exposure_type` 为 `direct` 时为 `true`。
`amount_usd`	number \| null	归属于该实体的美元金额。
`percentage`	number	占该方向总风险敞口的比例（0–100）。
`hops`	integer \| null	到达该实体的跳数（直接交易对手为 `1`），前提是服务商提供该数据。对于 Merkle Science，此字段始终为 `null`，因为它只报告风险敞口是直接还是间接：请使用 `exposure_type`。
`country`	string \| null	该实体主要所在国家/地区的 ISO 3166-1 alpha-2 代码。服务商未知时为空或 `null`。
`provider_entity_id`、`provider_entity_type_id`、`provider_entity_subtype_id`	string \| null	服务商为该实体及其类型分配的标识符。
`raw_amount`、`raw_currency`	number \| null、string \| null	以资产自身单位表示的金额，前提是服务商提供该数据。

交易对手关联

counterparty_connections 列出服务商将被筛查地址归属到的实体。对于 Merkle Science，这些实体来自地址自身的所有者标签和用户标签，因此同一实体可能出现两次，并且它们不包含资金流动：received_usd、sent_usd、received_hops 和 sent_hops 为 null，percentage 为 0.0。资金流动请从 source_of_funds 和 destination_of_funds 中读取。

字段	类型	说明
`entity_name`	string \| null	归因的实体。
`entity_type`	string \| null	服务商的实体类型。
`entity_subtype`	string \| null	更细的子类型。
`categories`	array	该实体的标准化风险类别。
`risk_level`	string	小写，因服务商而异。对于 Merkle Science，它是地址自身的 0 至 5 级风险等级（`no_risk`、`low`、`medium_low`、`medium`、`high`、`critical`），当实体的类别为高风险时提升为 `high`；它不是该实体单独的等级。
`is_direct`	boolean	对于 Merkle Science 始终为 `true`，因为其关联是归因，而不是交易对手。
`received_usd`、`sent_usd`	number \| null	从该实体收到及发送给该实体的美元金额，前提是服务商提供该数据。
`received_hops`、`sent_hops`	integer \| null	各方向到达该实体的跳数，前提是服务商提供该数据。
`percentage`	number	占该地址风险敞口的比例，前提是服务商提供该数据；否则为 `0.0`。
`country`	string \| null	该实体所在国家/地区（如已知）。
`provider_entity_id`	string \| null	服务商为该实体分配的标识符。

请勿依据 counterparty_connections[].risk_level 或 counterparty_connections[].is_direct 做路由判断：对于 Merkle Science，前者重复的是地址自身的评级（请读取 risk_score），后者始终为 true。判定请使用 sanctions_hit、dominant_risk_category 和 risk_factors[].is_high_risk，判断直接性请使用 source_of_funds / destination_of_funds 中的 exposure_type。

示例

以下是使用 Merkle Science 对 OFAC 制裁名单上的一个地址进行筛查所得的真实响应。仅 raw_response 经过缩短，report_signature 已替换：

{
  "provider": "merklescience",
  "screening_type": "WALLET_SCREENING",
  "risk_score": 95,
  "severity": "CRITICAL",
  "status": "SCREENED",
  "summary": "Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant risk: sanctioned. Driven by: the address is attributed to Sanctions / OFAC (Example Sanctions)",
  "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
  "transaction_hash": null,
  "blockchain": "ETH",
  "block_timestamp": null,
  "total_value_usd": null,
  "fee_usd": null,
  "sender_rows": [],
  "receiver_rows": [],
  "transaction_flows": [],
  "transaction_flows_status": null,
  "transaction_flows_error": null,
  "source_of_funds": [
    {
      "category": "sanctioned",
      "percentage": 100.0,
      "amount_usd": 9813695.0,
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "hops": null,
      "description": "Sanctions / OFAC",
      "is_direct": true,
      "exposure_direction": "incoming",
      "exposure_type": "direct",
      "provider_entity_id": "118885",
      "provider_entity_type_id": "30",
      "provider_entity_subtype_id": "125",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    }
  ],
  "destination_of_funds": [
    {
      "category": "defi",
      "percentage": 84.824453,
      "amount_usd": 7783414.38,
      "entity_name": "Example DeFi 7",
      "entity_type": "DeFi",
      "entity_subtype": "Bridges",
      "hops": null,
      "description": "DeFi / Bridges",
      "is_direct": false,
      "exposure_direction": "outgoing",
      "exposure_type": "indirect",
      "provider_entity_id": "118459",
      "provider_entity_type_id": "33",
      "provider_entity_subtype_id": "143",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    },
    {
      "category": "defi",
      "percentage": 15.175547,
      "amount_usd": 1392494.37,
      "entity_name": "Example DeFi 2",
      "entity_type": "DeFi",
      "entity_subtype": "Yield Aggregator",
      "hops": null,
      "description": "DeFi / Yield Aggregator",
      "is_direct": false,
      "exposure_direction": "outgoing",
      "exposure_type": "indirect",
      "provider_entity_id": "90192",
      "provider_entity_type_id": "33",
      "provider_entity_subtype_id": "142",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    }
  ],
  "counterparty_connections": [
    {
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "risk_level": "critical",
      "categories": [
        "sanctioned"
      ],
      "received_usd": null,
      "sent_usd": null,
      "received_hops": null,
      "sent_hops": null,
      "percentage": 0.0,
      "is_direct": true,
      "country": null,
      "provider_entity_id": null
    },
    {
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "risk_level": "critical",
      "categories": [
        "sanctioned"
      ],
      "received_usd": null,
      "sent_usd": null,
      "received_hops": null,
      "sent_hops": null,
      "percentage": 0.0,
      "is_direct": true,
      "country": null,
      "provider_entity_id": null
    }
  ],
  "network_nodes": [],
  "network_edges": [],
  "sanctions_hit": true,
  "pep_counterparty": null,
  "dominant_risk_category": "sanctioned",
  "risk_factors": [
    {
      "source": "attribution",
      "category": "sanctioned",
      "label": "Sanctions / OFAC",
      "entity_name": "Example Sanctions",
      "direction": "attribution",
      "exposure_type": "attribution",
      "amount_usd": null,
      "percentage": 0.0,
      "is_high_risk": true,
      "description": "the address is attributed to Sanctions / OFAC (Example Sanctions)"
    },
    {
      "source": "exposure",
      "category": "sanctioned",
      "label": "Sanctions / OFAC",
      "entity_name": "Example Sanctions",
      "direction": "incoming",
      "exposure_type": "direct",
      "amount_usd": 9813695.0,
      "percentage": 51.679304,
      "is_high_risk": true,
      "description": "51.6793% direct incoming exposure to Sanctions / OFAC (Example Sanctions)"
    },
    {
      "source": "exposure",
      "category": "defi",
      "label": "DeFi / Bridges",
      "entity_name": "Example DeFi 7",
      "direction": "outgoing",
      "exposure_type": "indirect",
      "amount_usd": 7783414.38,
      "percentage": 40.987766,
      "is_high_risk": false,
      "description": "40.9878% indirect outgoing exposure to DeFi / Bridges (Example DeFi 7)"
    },
    {
      "source": "exposure",
      "category": "defi",
      "label": "DeFi / Yield Aggregator",
      "entity_name": "Example DeFi 2",
      "direction": "outgoing",
      "exposure_type": "indirect",
      "amount_usd": 1392494.37,
      "percentage": 7.33293,
      "is_high_risk": false,
      "description": "7.33293% indirect outgoing exposure to DeFi / Yield Aggregator (Example DeFi 2)"
    }
  ],
  "raw_response": {
    "...": "provider-specific details"
  },
  "report_signature": "<hmac-sha256 over the result, scoped to your application>"
}

示例仅用于说明响应结构，并不保证真实地址的判定结果。风险评分和制裁敞口取决于所选网络、当前情报以及配置的风险策略。交易所归因并不意味着风险评分为零：交易所钱包可能因其资金流动而存在制裁敞口。 sanctions_hit: true 可能表示钱包本身受制裁，也可能仅表示其资金存在制裁敞口，因此它本身并不意味着被筛查的钱包所有者受制裁。当同一筛查作用于已记录的交易时，规则还可以读取 custom_values.wallet_sanctioned（仅当服务商将钱包本身归因于受制裁实体时为 true）和 custom_values.aml_sanctions_exposure_pct。请参阅规则的筛查字段。请阅读 risk_factors、source_of_funds 和 destination_of_funds，以区分归因与风险敞口。有关详细说明，请参阅加密货币与钱包筛查。

PDF 报告

要获取某个筛查结果的 Didit 品牌 PDF，请将完全未经修改的响应正文（包括 report_signature）重新提交至 POST /v3/wallet-screening/pdf/。该接口为无状态接口：不调用服务商，不产生额外费用，也不保存任何数据。在重新提交前修改任何已签名字段（risk_score、severity、sanctions_hit 等），都会失败并返回 400。

RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "blockchain": "ETH"}')

curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$RESULT" \
  -o wallet_screening_report.pdf

请参阅钱包筛查 PDF，了解完整的请求和响应结构以及错误格式。

计费

每次成功筛查按与交易关联的加密货币筛查相同的费率计为一次 AML 监控用量。托管密钥和已连接密钥的费率请参阅定价。沙盒应用不计费。验证错误（400）和未配置提供商错误（409）永远不计费。

错误

状态	含义
`400`	钱包地址格式错误、缺少 `wallet_address`，或 `blockchain` 不受支持。
`401`	缺少或无效的 `x-api-key`。
`409`	该应用未配置 AML 提供商，请先配置交易监控。
`409`	服务商拒绝了您连接的 API 密钥（`wallet_screening_provider_credentials_rejected`）。请在 Marketplace 连接中更新密钥，或在交易监控设置中更新在那里配置的密钥。使用同一密钥重试无效。
`409`	已配置的 AML 提供商暂不支持钱包筛查（`wallet_screening_provider_unavailable`）。
`422`	发送的 `0x` 地址未包含 `blockchain`（`wallet_screening_chain_undetermined`）。响应体会列出 `candidate_chains`，请从中选择一条链重新发送。不会执行筛查，也不会计费。
`502`	服务商无法完成筛查，请稍后重试。

后续步骤

API 参考

Screen Wallet endpoint 的完整请求与响应结构。

Screen Wallet PDF

将筛查结果渲染为带有 Didit 品牌的 PDF。

加密货币与钱包筛查

交易创建期间的自动筛查及结果模型。

​适用场景

​前提条件

​请求

​链覆盖范围

​响应

​风险因素

​风险敞口明细

​交易对手关联

​示例

​PDF 报告

​计费

​错误

​后续步骤

API 参考

Screen Wallet PDF

加密货币与钱包筛查

适用场景

前提条件

请求

链覆盖范围

响应

风险因素

风险敞口明细

交易对手关联

示例

PDF 报告

计费

错误

后续步骤