> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 加密钱包与地址筛查 API（KYT）

> Didit 为每笔转账中的加密钱包地址和交易哈希进行 AML 风险筛查，涵盖风险评分、风险敞口和制裁检查。每次检查 $0.15 起。

Didit 的加密钱包筛查（也称地址筛查，或 KYT，即了解您的交易）会检查每笔加密货币转账的钱包地址和交易哈希，评估其 AML 风险，并返回风险评分、对风险来源的暴露程度以及任何制裁命中结果。

对于加密货币交易，Didit 可以在创建交易时，将钱包地址和交易哈希提交给 Merkle Science、Crystal、Chainalysis、Elliptic 和 TRM Labs 等区块链分析服务商进行筛查。筛查在服务端运行，无需您这边额外调用 API。

> [!TIP]
>
> 需要在**没有**交易的情况下筛查某个地址？使用[按需钱包筛查](https://docs.didit.me/zh/transaction-monitoring/wallet-screening.md) endpoint（`POST /v3/wallet-screening/`），只需一次 API 调用，即可获得单个钱包相同的风险结果。

## 筛查触发方式

当以下两个条件同时满足时，加密货币筛查会自动运行：

1. 交易详情中包含 `currency_kind: "crypto"`
2. 您的[应用设置](https://docs.didit.me/zh/transaction-monitoring/settings.md)中已启用交易监控

您可以在创建交易的请求体中使用 `include_crypto_screening`，为每笔交易单独覆盖此默认设置：

| 值 | 行为 |
| - | - |
| `true` | 即使应用级默认设置已禁用，仍运行加密货币筛查 |
| `false` | 即使应用级默认设置已启用，仍跳过加密货币筛查 |
| 省略或为 `null` | 使用控制台中配置的应用级默认设置 |

> [!TIP]
>
> 应用级默认设置位于 Business Console 中的 **交易** > **设置**。`include_crypto_screening` 仅为您当前创建的这笔交易覆盖该默认设置。

## 资产与网络选择

资产和网络是两个独立的字段。
将 `transaction_details.currency` 设为代币符号，将 `transaction_details.currency_kind` 设为 `crypto`，并将 `transaction_details.crypto_params.crypto_chain` 设为网络。
例如，以下片段记录了 Base 网络上的一种自定义代币：

```json theme={null}
{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}
```

托管筛查支持 `BTC`、`ETH`、`LTC`、`XRP`、`BCH`、`DOGE`、`TRX`、`SOL`、`MATIC`、`BNB`、`BASE`、`OP`、`ARB`、`AVAX`、`ADA`、`XLM` 和 `HBAR`。
`BASE` 表示 Base，`OP` 表示 Optimism，`ARB` 表示 Arbitrum One，`AVAX` 表示 Avalanche C-Chain，`ADA` 表示 Cardano，`XLM` 表示 Stellar，`HBAR` 表示 Hedera。
常见的网络名称也可以使用，例如 `POLYGON` 或 `POL` 表示 `MATIC`，`BSC` 表示 `BNB`，`TRON` 表示 `TRX`。
Celo、Mode 和 Plume 不在托管集成的覆盖范围内；它们通过已连接的 TRM Labs 账户进行筛查（`CELO`、`MODE`、`PLUME`）。
已连接的服务商有各自的覆盖范围；Lightning 有下文所述的额外要求。

对于代币，始终要指定 `crypto_chain`，包括 USDT 和 USDC。
若不指定，则会把币种本身当作网络使用，而 USDT 和 USDC 会从交易哈希中确定网络；若没有哈希，则从钱包地址中确定。
Tron 或 Solana 的哈希会分别选定 Tron 或 Solana。
`0x` 哈希在每个 EVM 网络上的格式都相同，因此对于 USDT、USDC 和 ETH，Didit 会在 Ethereum、BNB Chain、Polygon、Base、Arbitrum 和 Optimism 上查询该哈希，并在找到该哈希的网络上筛查交易。
之所以包含 ETH，是因为它在 Ethereum、Base、Arbitrum 和 Optimism 上是原生资产，同时也以桥接的 BEP-20 代币形式在 BNB Chain 上转移。
如果没有任何网络包含该哈希，或者此时无法检查这些网络，则不会对该交易进行筛查，也不收费。
此时 `custom_values.aml_screening_status` 为 `FAILED`，`custom_values.aml_screening_error` 会说明原因，已通过的交易将转入审核。

没有哈希的 USDT 或 USDC 交易会筛查钱包，并由钱包地址决定网络。
Tron 地址在 Tron 上筛查，Solana 地址在 Solana 上筛查。
`0x` 地址会在 Ethereum、BNB Chain、Polygon、Base、Arbitrum 和 Optimism 中，选择该地址已发送过交易或持有该代币的第一个网络进行筛查。
若该 `0x` 地址在上述网络中均无活动记录，或此时无法检查这些网络，则在 Ethereum 上筛查。

传入 `crypto_chain` 可避免上述查询。
切勿用 `ETH` 替代实际网络。

记录自定义代币符号并不保证其转账已建立索引以进行交易哈希筛查。代币覆盖范围必须通过代币合约和网络进行核实。
交易创建成功并不代表筛查已成功：在将其视为已筛查之前，请检查筛查状态和服务商结果。

## 入账与出账

`transaction_details.direction` 为必填项，用于告诉 Didit 应对转账的哪一方进行筛查。

| 方向 | 链上转账前 | 链上转账后 |
| - | - | - |
| **入账**（存款） | 若您在 `counterparty.payment_method.account_id` 中提供了交易对手发送方地址，则筛查该地址 | 对 `subject.payment_method.account_id` 中限定于您的服务或客户充值地址的交易哈希进行筛查 |
| **出账**（取款） | 在您发送资金之前，筛查 `counterparty.payment_method.account_id` 中的目标地址 | 对 `counterparty.payment_method.account_id` 中限定于同一目标钱包的交易哈希进行筛查 |

转账前筛查时，请省略 `transaction_details.payment_reference_id`；Didit 会对相关地址执行钱包筛查。转账后筛查时，请在 `transaction_details.payment_reference_id` 中填入链上交易哈希；Didit 会执行交易筛查，并在链上数据补充可用时存储交易摘要数据。

### 闪电网络

如需进行闪电网络筛查，请将 `transaction_details.crypto_params.crypto_chain` 设置为 `LIGHTNING`。
闪电网络筛查要求在控制台的 **Marketplace** 中已连接 Elliptic 或 Chainalysis 的 BYOK 提供商。
托管的 Merkle Science、Crystal 和 TRM Labs 不接受 `LIGHTNING`；Didit 会在筛查或计费之前以 `400` 拒绝这些请求。

对于 Elliptic，Didit 会通过 Elliptic 的 BTC 闪电网络钱包分析，对所提供的闪电网络标识符进行筛查。
对于 Chainalysis，当存在 `transaction_details.payment_reference_id` 时，Didit 会将闪电网络转账提交至 KYT。

## 必填字段

对于所有加密货币筛查请求，请发送以下字段：

* `transaction_details.direction`：`INBOUND` 或 `OUTBOUND`
* `transaction_details.currency_kind`：`crypto`
* `transaction_details.currency`：资产符号，例如 `BTC`、`ETH`、`USDC` 或您的自定义 token
* 上述方向规则所选参与方中的地址

对于资产上链后的交易哈希筛查，还需发送：

* `transaction_details.payment_reference_id`：区块链交易哈希

如果已启用加密货币筛查，但缺少该方向所需的地址，创建交易 API 将拒绝该请求。

## 示例：转账前出账筛查

在发送资金之前，创建一笔不含交易哈希的出账加密货币交易。Didit 会筛查目标钱包。

```json theme={null}
{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}
```

## 示例：转账后入账筛查

收到资金之后，请填入交易哈希。Didit 会对限定于您充值地址的交易哈希进行筛查，并在可用时将交易摘要信息补充到响应中。

```json theme={null}
{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}
```

## 支持的提供商

| 提供商 | 状态 | 托管定价 | 自带密钥定价 |
| - | - | - | - |
| **Merkle Science** | 可用 | \$0.15/次筛查 | \$0.02/次筛查 |
| **Crystal** | 通过 Marketplace 连接提供商密钥 | 不可用 | \$0.02/次筛查 |
| **Chainalysis** | 通过 Marketplace 连接提供商密钥 | 不可用 | \$0.02/次筛查 |
| **Elliptic** | 通过 Marketplace 连接提供商密钥 | 不可用 | \$0.02/次筛查 |
| **TRM Labs** | 通过 Marketplace 连接提供商密钥 | 不可用 | \$0.02/次筛查 |

在 [Business Console](https://business.didit.me) 中的 **Transactions** > **Settings** > **Provider Preferences** 配置您偏好的提供商，或从控制台的 **Marketplace**（加密货币监控类别）连接您自己的提供商密钥。

仅已连接自有密钥的 Chainalysis 和 Elliptic 配置支持 `LIGHTNING`。

> [!TIP]
>
> 使用**自带密钥定价**时，您需连接现有的提供商 API 密钥，并按每次筛查支付所列的基础设施费用。如果您已与某区块链分析提供商签订商业协议，可选择此方式。

## 筛查结果

每次筛查都会生成标准化的结果，与所用的提供方无关。

### 筛查状态

`custom_values.aml_screening_status` 用于说明某笔交易是否经过筛查。

| 值 | 含义 |
| - | - |
| `COMPLETED` | 筛查已完成。结果位于 `provider_results` 以及其他 `custom_values` 筛查字段中。 |
| `PENDING` | 筛查尚未完成：提供方仍在分析，或 Didit 稍后会再次对该交易哈希进行筛查（见下文）。 |
| `ERROR` | 提供方已作出回复，但报告其自身的分析失败。 |
| `FAILED` | 该交易未经过筛查。`custom_values.aml_screening_error` 说明失败原因。Didit 托管筛查不收费；若您已连接的提供方回复了该请求，则计为一次提供方请求。 |

若某笔交易原本会被批准，只要其筛查状态不是 `COMPLETED`，它就会转为 `IN_REVIEW`。

### 尚未索引的交易哈希

区块链分析提供方可能需要数分钟才能索引刚被打包的转账，在此之前无法对其进行筛查。
当提供方回复称尚未索引某个交易哈希，且网络本身确认该交易存在时，Didit 会在后台重新筛查，而不会直接判定失败：

* 创建响应中已将 `custom_values.aml_screening_status` 显示为 `PENDING`，原因记录在 `custom_values.aml_screening_error` 中。
  原本会被批准的交易将保持 `IN_REVIEW`，`decision_reason_code` 为 `aml_screening_pending`。
* Didit 会在交易创建后约 2、12 和 42 分钟再次对该交易哈希进行筛查。
* 重试筛查完成后，结果会像其他筛查一样被保存，且本次筛查只收取一次费用。您的规则会基于筛查数据重新运行，交易的保留状态会被解除，您将收到一条 `transaction.status.updated` Webhook，其中包含规则运行后交易的状态，无论状态是否发生变化。
  若交易在此期间已被拒绝或已由审核员解决，则保持其原有状态。
* 若在最后一次重试后，提供方仍未索引该交易哈希，则筛查以 `FAILED` 结束，与创建时的结果一致：交易保持 `IN_REVIEW`，`decision_reason_code` 为 `aml_screening_failed`。收费方式与创建时的失败相同：Didit 托管筛查不收费；若最后一次尝试到达了您已连接的提供方，则计为一次提供方请求。此前被重试的尝试均不收费。
* 若重试运行时您的余额已不足以支付筛查费用，则筛查以 `FAILED` 结束，且不收取任何费用。

重试适用于以下网络上的交易哈希：Ethereum、BNB Chain、Polygon、Base、Arbitrum、Optimism 和 Tron。
若哈希所属网络不认识该哈希，或该哈希属于其他网络，则不会重试，筛查将立即失败。

### 风险评分与严重级别

每个经过筛查的钱包或交易都会获得：

* **风险评分**（0–100）：分数越高，表示面临风险实体的风险敞口越高
* **严重级别**：根据评分得出，可能为 `LOW`、`MEDIUM`、`HIGH` 或 `CRITICAL`

### 资金来源分析

按实体类型分类，以百分比形式列出资金来源分布：

| 类别 | 风险等级 | 说明 |
| - | - | - |
| `SANCTIONED` | 严重 | 列入国际制裁名单（OFAC、欧盟、联合国）的实体 |
| `TERRORIST_FINANCING` | 严重 | 与恐怖主义融资相关的地址 |
| `CHILD_EXPLOITATION` | 严重 | 与儿童剥削材料相关的地址 |
| `RANSOMWARE` | 高 | 勒索软件付款地址 |
| `STOLEN_FUNDS` | 高 | 与已知盗窃或黑客攻击相关的地址 |
| `DARKNET_MARKET` | 高 | 暗网市场地址 |
| `MIXER` | 高 | 用于掩盖资金来源的混币或搅拌服务 |
| `SCAM` | 高 | 已知的诈骗或欺诈地址 |
| `HIGH_RISK_EXCHANGE` | 中 | KYC/AML 管控薄弱的交易所 |
| `HIGH_RISK_JURISDICTION` | 中 | 位于 FATF 列出的高风险司法辖区的实体 |
| `GAMBLING_UNLICENSED` | 中 | 未获许可的赌博平台 |
| `P2P_EXCHANGE` | 低 | 点对点交易服务 |
| `EXCHANGE` | 低 | 受监管的加密货币交易所 |
| `UNNAMED_SERVICE` | 低 | 身份未明的服务 |

分析结果中的每个实体都包含资金占比、收到和发出的金额，以及关联是直接还是间接的。

### 风险敞口表

风险敞口表展示资金来源、去向及交易对手实体，包括：

* 实体名称和类别
* 直接或间接关联（跳数）
* 收到和发出的金额
* 每个实体的风险等级

### 网络图谱

以可视化的节点和边呈现钱包的交易关系：

* **节点**代表钱包、交易所、服务及其他实体
* **边**代表节点之间的交易，并标注金额和交易哈希
* **指标**包括中心性和深度等图谱级统计数据

网络图谱可在 [Business Console](https://docs.didit.me/zh/transaction-monitoring/console.md) 中以交互式可视化形式查看。

## 与规则集成

筛查结果会直接输入[规则引擎](https://docs.didit.me/zh/transaction-monitoring/rules.md)。Didit 提供预设规则，这些规则会根据筛查数据自动触发：

| 预设规则 | 操作 |
| - | - |
| **制裁交易对手** | 立即拒绝，被筛查的钱包本身归属于受制裁实体（`custom_values.wallet_sanctioned`） |
| **制裁风险敞口** | 添加评分并标记以供审核，钱包向受制裁实体转入或从其转出资金，但自身未受制裁（`sanctions_hit` 为 true，`wallet_sanctioned` 不为 true） |
| **恐怖主义融资/儿童剥削** | 立即拒绝 |
| **暗网市场风险敞口** | 添加评分并标记以供审核 |
| **混币/混淆服务风险敞口** | 添加评分并标记以供审核 |
| **高风险资金来源（>30%）** | 添加评分并标记以供审核 |
| **多个高风险交易对手** | 添加评分并标记以供审核 |
| **中等钱包风险评分** | 添加评分并标记以供审核 |
| **筛查待完成** | 在筛查完成前暂停交易 |

### 规则可用的筛查字段

加密货币筛查会将以下键写入交易的 `custom_values`，以便规则将其用作 `custom_values.<key>`：

| 字段 | 类型 | 描述 |
| - | - | - |
| `sanctions_hit` | 布尔值 | 当钱包本身受制裁，或其任一交易对手的资金来自受制裁实体（风险敞口）时为 `true`。大型交易所通常仅因风险敞口即为 `true`。 |
| `wallet_sanctioned` | 布尔值 | 仅当筛查服务商将被筛查钱包本身归属于受制裁实体（OFAC、欧盟、联合国或 HMT 指定名单）时为 `true`。仅有风险敞口时，该字段永远不会被设为 true。 |
| `aml_sanctions_exposure_pct` | 数字（0-100） | 钱包已筛查交易量中接触受制裁实体的占比。其计算方式与 `aml_high_risk_exposure_pct` 相同，但仅限于制裁。 |

使用 `wallet_sanctioned` 可阻止向受制裁钱包的转账，同时不拒绝仅存在间接风险敞口的主要交易所转账。
使用 `sanctions_hit` 或 `aml_sanctions_exposure_pct` 来审核或为风险敞口评分。

**制裁交易对手**预设规则在 `wallet_sanctioned` 为 `true` 时拒绝交易，**制裁风险敞口**预设规则则将仅有风险敞口的钱包转入审核。
两者不会同时匹配同一笔交易，因此受制裁钱包的转账始终会被拒绝。
如果您在此变更之前安装了**制裁交易对手**规则，Didit 已为您将其改为使用 `wallet_sanctioned`，并以相同模式添加了**制裁风险敞口**规则。因此，之前仅因风险敞口而被旧规则拒绝的转账，现在会转入审核。

筛查完成后，Didit 会自动根据补充后的交易数据重新评估所有规则，并触发任何适用的 Webhook。

## 后续步骤

> [card] [提交交易](https://docs.didit.me/zh/transaction-monitoring/transactions.md)
>
> 如何提交交易，包括加密货币钱包详情。

> [card] [规则与评分](https://docs.didit.me/zh/transaction-monitoring/rules.md)
>
> 筛查结果如何输入规则引擎。

> [card] [控制台指南](https://docs.didit.me/zh/transaction-monitoring/console.md)
>
> 在控制台中查看加密货币筛查分析、资金来源和网络图谱。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.