> ## 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.

# 交易监控规则与评分：速率与条件

> Didit 的 KYT 规则可配置条件、速率窗口和自动操作，支持预设组合或自定义。每月包含 1,000 次，之后每次 $0.001。

提交至 Didit 的每笔交易都会根据您应用中的所有有效规则进行评估。规则定义了条件、速率检查和操作，用于确定交易的最终状态和评分。

本章是 Didit Academy 欺诈规则引擎课程的一部分，从创建规则开始讲起。

规则引擎课程在 7:54 处通过录屏演示创建规则：包括触发器、条件、操作和评分，然后在部署前进行回测。

[创建规则 — Didit Academy](https://www.youtube.com/embed/Yhm63_n7HuU?start=474\&rel=0\&playsinline=1)

> [!NOTE]
>
> 规则可以在 **业务控制台**、**管理 API** 和 **Didit MCP** 中管理。如果需要合规团队中的人员审查每一次变更，请使用控制台；如果规则需要以编程方式创建和调整，例如从其他服务商迁移规则集，请使用 API 或 MCP。请参阅 [API 参考](https://docs.didit.me/zh/management-api/transactions/rules-list.md) 和 [通过 API 与 MCP 管理规则指南](https://docs.didit.me/zh/transaction-monitoring/rules-api.md)。规则会在每笔通过 [`POST /v3/transactions/`](https://docs.didit.me/zh/management-api/transactions/create) 提交的交易上进行评估，结果会显示在交易的 `rule_runs[]` 数组中（参见 [响应结构](https://docs.didit.me/zh/transaction-monitoring/response-schema.md)）。

## 内置规则包

Didit 提供预配置的规则库，涵盖常见的监管类型。您可以从规则库中安装所需的预设（或整个规则包），方式包括：在控制台中操作、通过 [安装 API](https://docs.didit.me/zh/management-api/transactions/rules-install.md)，或使用 MCP 工具，并控制每个已安装预设的模式。如需查看所有预设规则的完整目录（包括阈值和操作），请参阅 [规则库](https://docs.didit.me/zh/transaction-monitoring/rules-library.md)。

| 规则包 | 示例 |
| - | - |
| **金融** | 结构化交易检测（入账/出账），超过报告阈值的大额单笔交易 |
| **AML/CTF** | 累计交易量限制，快速转入转出，制裁交易对手匹配，可疑付款备注关键词 |
| **异常检测** | 高频入账/出账，休眠 12+ 个月后账户重新激活 |
| **FATF** | 交易对手及主体 IP 涉及高风险司法辖区 |
| **设备情报** | 同一设备指纹重复参与奖励活动，同一主体关联多个设备指纹 |
| **欺诈预防** | 通过共享设备指纹实现跨不同主体的多账户操作 |
| **加密监控** | 涉及混币器或混淆服务，高风险地址（暗网、受制裁、被盗资金） |
| **加密筛查** | 资金来源高风险暴露（>30%），多个高风险交易对手，恐怖融资和儿童剥削自动拒绝，筛查待定暂挂，中等钱包风险评分标记 |
| **责任博彩** | 短时间窗口内快速连续存款 |
| **电子商务** | 电子商务特定交易模式 |

## 规则来源

每条规则都有一个 `source`，用于标明由谁管理：

| 来源 | 说明 |
| - | - |
| **预设** | 从 Didit 内置库安装的规则。您可以选择要安装的预设（或整个规则包），并控制每个已安装预设的模式（`Active`、`Test`、`Disabled`）。其条件和阈值是固定的，如需覆盖，请创建自定义规则；预设通过卸载移除，而不是删除。 |
| **自定义** | 由您的团队在业务控制台中创建的规则。您可以完全控制自定义规则，按需创建、编辑和删除。 |

## 规则结构

每条规则包含以下组成部分：

| 组成部分 | 说明 |
| - | - |
| **标题与描述** | 便于阅读的名称，以及对规则检测内容的说明 |
| **类别** | 逻辑分组（例如 `finance`、`aml_ctf`、`crypto_monitoring`、`device_intelligence`） |
| **模式** | `Active`（实时评估）、`Disabled`（跳过）或 `Test`（评估，但结果不影响交易） |
| **评估模式** | `All`（所有条件都必须匹配）或 `Any`（至少一个条件必须匹配） |
| **范围** | 限定规则适用的交易。键包括 `transaction_types`、`directions`（`INBOUND`/`OUTBOUND`）、`action_types`，为空或缺失表示不做限制 |
| **条件** | 字段级检查，使用 `eq`、`lt`、`gte`、`in`、`contains_any`、`exists` 等运算符，将交易字段与值进行比较 |
| **聚合** | 速率窗口，在一段时间内聚合历史交易（例如 1 小时、7 天、30 天内的计数、求和或去重计数） |
| **操作** | 规则匹配时执行的操作（见下文） |

## 操作

当规则匹配某笔交易时，将执行一项或多项操作。每条规则可以包含多项操作，这些操作会一起生效：

| 操作 | `type` | 键 | 说明 |
| - | - | - | - |
| **添加评分** | `add_score` | `value`（整数，可以为负数） | 为交易的风险评分增加分值。所有匹配规则的累计评分决定交易是否达到审核阈值或拒绝阈值。 |
| **更改状态** | `change_status` | `value`（`APPROVED`\|`IN_REVIEW`\|`DECLINED`\|`AWAITING_USER`，别名 `status`），`workflow_id`（别名 `remediation_workflow_id`） | 无论评分如何，直接设置交易状态。当 `value` 为 `AWAITING_USER` 时必须提供 `workflow_id`，缺少该参数会返回 `400`。 |
| **添加标签** | `add_tags` | `tag_uuid` 或 `tag_name`（二选一），`tag_color` | 为交易添加标签，便于分类和筛选。可填写已有标签的 `tag_uuid`，也可填写 `tag_name`，首次使用时会创建该标签（名称以大写形式存储）。`tag_color` 用于设置新建标签的十六进制颜色。 |
| **添加备注** | `add_note` | `note`（别名 `value`） | 为交易附加一条自动生成的文本备注，供分析人员参考。 |
| **添加到列表** | `add_to_list` | `list_id` | 将主体的 `vendor_data` 添加到黑名单、白名单或自定义名单中。 |
| **创建案件** | `open_case` | `blueprint`（案件蓝图 UUID，可选），`grouping`（`by_applicant`\|`by_rule_and_applicant`），`attach_matched_transaction`（布尔值） | 创建（或加入）调查案件。规则中只有第一个 `open_case` 操作会生效。 |

大多数预设规则会将**添加评分**与**更改状态**组合使用。例如，制裁交易对手规则会增加 90 分，并*同时*立即拒绝该交易。

### 要求用户验证 (`AWAITING_USER`)

**更改状态 → `AWAITING_USER`** 操作不只是设置状态。规则触发时，Didit 会自动为该交易的主体（即相同的 `vendor_data`）创建一个托管验证会话。
该会话会出现在交易的 `action_required` 块中（同时也在 `remediation` 对象中），包含在创建响应和之后的每次读取中，并且会随两个交易 Webhook 一并发送。这样您可以立即将用户重定向到验证页面，详见[所需的用户操作](https://docs.didit.me/zh/transaction-monitoring/sdk-transaction-submission.md#用户所需操作)。

自定义规则必须在操作本身中指定工作流（`workflow_id`），控制台规则构建器和规则 API 都要求如此。
内置规则库中的规则不携带工作流。对于这些规则，验证会话的工作流按以下顺序确定：

1. 在[交易设置](https://docs.didit.me/zh/transaction-monitoring/settings.md#补救工作流)中配置的**补救工作流**。
2. 您应用的**生物识别认证**工作流，前提是该主体已有来自已通过验证且已存储的参考人脸。
3. 您应用的默认工作流。

这意味着 `AWAITING_USER` 规则库规则开箱即可生成可操作的会话：对于您已验证过的用户，进行生物识别二次验证；其他情况则进行完整验证。
对于 Travel Rule 交易，不适用此自动回退机制，因为其 `AWAITING_USER` 等待是为了证明钱包所有权，该流程有[其专属流程](https://docs.didit.me/zh/transaction-monitoring/wallet-ownership-widget.md)。

对于高风险交易，最佳选择是**生物识别认证**工作流：该主体就是您已完成 KYC 的用户，因此 Didit 会复用其入驻时已验证的参考人脸（已通过的活体自拍照、护照芯片照片或证件人像）。用户只需拍摄一张实时自拍照，Didit 即可对其进行活体检测，并与开户时的身份进行 1:1 人脸比对。
被盗的凭证、钓鱼获取的一次性验证码和 SIM 卡换绑都无法通过这一关。
完整操作步骤：[高价值提现的生物识别二次验证操作指南](https://docs.didit.me/zh/transaction-monitoring/sdk-transaction-submission.md#示例：为高额提现进行生物识别升级验证)。

会话作出决策后，交易会自动跟随该结果，并触发 `transaction.status.updated` Webhook：已通过的会话会使交易通过（`decision_reason_code: user_action_approved`），已拒绝的会话会使交易被拒绝（`user_action_declined`），结束于审核中的会话会使交易进入 `IN_REVIEW`（`user_action_in_review`）。
已过期或已放弃的会话会使交易保持在 `AWAITING_USER` 状态。

> [!NOTE]
>
> 除 KYB 以外的任何工作流类型都可以用作补救操作。
> 生物识别认证工作流（以及人脸比对先于证件验证执行的工作流）还要求该主体已有存储的参考人脸：已通过的活体自拍照、护照芯片照片、证件人像或手动录入的个人资料人脸。
> 如果不存在参考人脸，则会要求用户改为完成您应用的默认工作流，该流程同时也会录入其人脸，供下次使用。交易上的备注会记录此次替换。
> 只有在也不存在合适的默认工作流时，会话才会被跳过，并附上说明原因的备注。

## 评分

当交易匹配一条或多条规则时，各项评分会被合并：

1. 每次规则匹配都会通过 `add_score` 操作为交易的总体**风险评分**贡献分值。
2. 最终评分根据您应用的**评分阈值**决定交易状态。
3. 如果任何规则包含 `change_status` 操作，则直接应用该状态，**`DECLINED` 始终优先**。

默认评分阈值（可在控制台中配置）：

| 设置 | 默认值 | 说明 |
| - | - | - |
| **审核阈值** | 75 | 评分大于或等于该值时触发 `IN_REVIEW` |
| **拒绝阈值** | 500 | 评分大于或等于该值时触发 `DECLINED`。默认值（`500`）永远不会因评分而拒绝 |

## 创建自定义规则

可以在 **业务控制台** 中创建自定义规则，也可以通过 **管理 API** 创建（也可通过 [Didit MCP](https://docs.didit.me/zh/integration/mcp/tools.md) 以及任何连接 MCP 的 AI 助手访问）。

> [tab] 控制台
>
> 1. 在控制台中前往 **交易** > **规则**
> 2. 点击 **创建规则**
> 3. 定义规则标题、描述和类别
> 4. 设置 **模式**：`Active` 表示实时运行，`Test` 表示仅评估而不影响交易
> 5. 选择 **评估模式**：`All`（每个条件都必须匹配）或 `Any`（至少一个条件匹配）
> 6. 设置 **适用范围**：规则适用于哪些交易类型或方向
> 7. 添加 **条件**：字段比较，例如金额阈值、国家代码、自定义属性检查
> 8. 可选添加 **聚合**：按时间窗口进行的频次检查（计数、求和、去重计数等）
> 9. 定义一个或多个 **操作**：增加分数、更改状态、添加标签、添加备注、添加到列表或打开案件
> 10. 保存并启用规则

> [tab] API
>
> 使用相同字段调用 [`POST /v3/transactions/rules/`](https://docs.didit.me/zh/management-api/transactions/rules-create)：`title`、`category`、`mode`、`evaluation_mode`、`scope`、`conditions`、`aggregation`、`actions`。完整的字段、运算符和操作参考见本页，[通过 API 和 MCP 管理规则](https://docs.didit.me/zh/transaction-monitoring/rules-api.md)介绍了推荐的创建 -> 回测 -> 激活工作流，包括迁移其他服务商 CSV 导出的规则集。

处于 `Active` 模式的规则会立即对所有新交易生效。规则标题在每个应用内唯一。

## 回测

激活规则之前，可以使用历史数据进行验证：

* 将规则设置为 **测试** 模式：规则会对每笔新交易进行评估，但结果不影响交易的状态或分数。执行统计（匹配数、受影响实体）会持续累积，便于在正式上线前评估影响。
* 使用 **回测** 功能（在控制台中，或通过 [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/zh/management-api/transactions/rules-backtest)）对指定时间段内的交易，追溯评估规则的条件和聚合。回测会返回已评估的交易数、已匹配的交易数以及受影响实体，且不会修改任何历史数据。请发送与计划激活的规则相同的 `conditions`、`aggregation`、`evaluation_mode` **并且** `scope`：省略适用范围表示不做限制，这样回测会统计已保存规则会跳过的交易。

## 速率窗口（聚合）

速率规则会在一段时间内聚合历史交易数据，以发现单笔交易检查可能漏掉的模式：

| 指标 | 说明 |
| - | - |
| `count` | 窗口内符合过滤器的交易数量 |
| `sum` | 窗口内数值 `field`（例如 `preferred_currency_amount`）的总和 |
| `max` / `min` / `avg` | 窗口内数值 `field` 的最大值、最小值或平均值 |
| `distinct_count` | 窗口内 `field` 的唯一值数量（例如不同设备指纹的数量）（`unique_count` 为可接受的别名） |

每个聚合需指定：

* **时间窗口**：`<N>m`（分钟）、`<N>h`（小时）或 `<N>d`（天），例如 `30m`、`6h`、`7d`、`30d`。注意：`m` 表示**分钟**，而不是月。
* **过滤器**：用于缩小纳入的历史交易范围。键为[字段目录](#字段目录)中的字段路径；特殊值 `"__current__"` 会解析为正在评估的交易中同一字段的值（例如 `"subject_vendor_data": "__current__"` 将窗口限定为同一主体）；列表值表示匹配列表中的值。过滤器**仅**支持等值或成员匹配，没有 `lt`/`gte` 过滤器，因此无法表达类似*金额低于 10,000 的交易*这样的范围。请将范围放在指标上（例如下方的 `max` 低于 10,000、`min` 高于 1,000），并谨记：条件约束的是正在评估的交易，而不是时间窗口。
* **运算符和阈值**：`eq`、`ne`、`gt`、`gte`、`lt`、`lte` 与 `value` 比较，例如计数 >= 20。

### 示例模式

| 模式 | 运作方式 |
| - | - |
| **拆分交易** | 同一主体在 30 天内的交易计数 >= 20，且同一窗口内 `max` 金额低于 \$10,000 |
| **高频交易** | 同一主体在 7 天内的转入交易计数 >= 20 |
| **快进快出** | 当前交易为转出，且同一主体在 6 小时内的转入交易计数 >= 1 |
| **多账户** | 7 天内共享同一设备指纹的主体去重计数 >= 3 |
| **休眠主体重新激活** | 距离主体上一笔交易的天数 >= 365，并且金额 >= \$1,000 |

## 字段目录

条件和聚合过滤器通过路径引用交易字段：

| 字段 | 说明 |
| - | - |
| `amount`, `currency` | 交易金额及货币代码 |
| `preferred_currency_amount`, `default_currency_code` | 按应用首选货币折算后的金额（若不可用，则回退为 `amount_in_default_currency`） |
| `direction` | `INBOUND` 或 `OUTBOUND` |
| `action_type` | 您的操作类型，例如 `withdrawal`、`deposit`、`bet` |
| `transaction_type` | `finance`、`kyc`、`travelRule`、`userPlatformEvent` |
| `payment_details` | 自由文本的付款备注（关键词规则中 `contains_any` 的匹配目标） |
| `score`, `severity` | 该交易当前的风险评分和严重程度 |
| `subject_vendor_data`, `counterparty_vendor_data` | 您为交易双方设定的标识符 |
| `subject_country`, `counterparty_country` | 各方的国家代码（同时接受 ISO-2 和 ISO-3；比较前会先进行标准化） |
| `subject_device_fingerprint`, `counterparty_device_fingerprint` | 设备指纹或持久设备 ID |
| `subject_browser_family`, `subject_browser_version`, `subject_platform`, `subject_accept_language`, `subject_session_age_ms` | 设备上下文详情（同时可用 `counterparty_browser_family`） |
| `subject_ip_address`, `subject_ip_country`, `counterparty_ip_address`, `counterparty_ip_country` | 网络上下文 |
| `subject_payment_method_type`, `subject_payment_method_country`, `subject_payment_method_fingerprint`, `subject_payment_method_account_id` | 主体一方的付款方式（`counterparty_payment_method_*` 同样有这四个字段） |
| `travel_rule_status`, `travel_rule_required`, `travel_rule_obligations_count` | Travel Rule 检查状态 |
| `counterparty_dd_status`, `counterparty_risk_level`, `counterparty_jurisdiction`, `counterparty_responsiveness` | 关于 Travel Rule 信息交换联系到的交易对手 VASP 的已知信息：您对其作出的决定（`APPROVED`、`RESTRICTED`、`BLOCKED`）、其风险等级（`LOW`、`MEDIUM`、`HIGH`；当您自己的交易对手筛查被标记时为 `HIGH`）、其所在国家/地区，以及其响应性（`RESPONSIVE`、`UNRESPONSIVE`、`UNKNOWN`）。参见 [Travel Rule 交易对手尽职调查](https://docs.didit.me/zh/transaction-monitoring/travel-rule.md#规则字段与预设) |
| `subject_days_since_previous_transaction` | 距该主体上一笔同类型交易的天数（用于休眠规则） |
| `tags` | 交易的标签名称 |
| `custom_values.<key>` | 您在创建交易时于 `custom_properties` 中提交的任意键 |

## 条件运算符

规则支持以下条件比较运算符：

| 运算符 | 说明 | 示例 |
| - | - | - |
| `eq` / `ne` | 等于 / 不等于 | `direction eq "OUTBOUND"` |
| `gt` / `gte` / `lt` / `lte` | 数值和日期比较；任一侧缺失时永不匹配 | `preferred_currency_amount gte 25000` |
| `in` / `not_in` | 属于列表中的某个值（也接受单个标量值） | `counterparty_country in ["IRN", "PRK", "SYR"]` |
| `contains` / `not_contains` | 对字符串值进行不区分大小写的子串匹配 | `payment_details contains "refund"` |
| `contains_any` | 列表中的任一字符串都是该字段不区分大小写的子串 | `payment_details contains_any ["terror", "weapon"]` |
| `regex` | 值模式与字段匹配 | `subject_vendor_data regex "^guest-"` |
| `fuzzy_match` | 模糊字符串相似度；条件上必须设置 `score` 阈值（0-100） | `counterparty_name fuzzy_match "Acme Corp"` 并设置 `score: 85` |
| `exists` / `is_not_empty` / `is_not_null` | 字段存在（别名；`value` 会被忽略） | `subject_device_fingerprint exists` |
| `not_exists` / `is_empty` / `is_null` | 字段不存在或为空（别名；`value` 会被忽略） | `subject_ip_address is_empty` |

其他所有运算符都需要非空的 `value`，否则 API 返回 `400`。
`contains`、`not_contains` 和 `regex` 接受单个字符串，不接受列表或对象；`contains_any` 接受字符串列表。

### 条件值类型

条件上可选的 `value_type` 用于改变 `value` 的解释方式：

| `value_type` | 含义 |
| - | - |
| `list` | `value` 是列表的 UUID。黑名单、白名单或自定义名单中的条目将作为比较值，因此规则可以匹配“交易对手位于我的自定义观察名单中”。 |
| `field` | `value` 是另一个字段路径。该条件比较两个交易字段，例如 `subject_payment_method_account_id ne counterparty_payment_method_account_id`。 |
| `relative_date` | `value` 是相对日期，例如 `{"direction": "past", "unit": "days", "amount": 30}`，用于 `txn_date` 等日期字段。 |

### 分组条件

平铺的条件列表会按规则的 `evaluation_mode`（`ALL`/`ANY`）组合。如需混合逻辑，可为条件设置 `group_index`：具有相同索引的条件构成一组，`group_logic`（`AND`/`OR`，默认 `AND`）组合组内的条件，第一个条件上的 `groups_logic`（`AND`/`OR`，默认 `OR`）组合各组的结果。只要有任一条件带有 `group_index`，分组评估就会取代 `evaluation_mode`。

### 引用自定义属性

通过 [`POST /v3/transactions/`](https://docs.didit.me/zh/transaction-monitoring/transactions) 的 `custom_properties` 对象提交的每个键，都会以 `custom_values` 的形式存储在交易上，并可在条件中使用字段路径 `custom_values.<key>` 引用。例如，提交的交易带有 `"custom_properties": {"channel": "mobile_app"}`，则会匹配条件 `custom_values.channel eq "mobile_app"`。上述所有运算符都适用于自定义属性，它们也可以与其他字段进行比较，或用于交易频率过滤器。

在控制台规则构建器中，近期接收的交易中出现过的键会自动显示在条件字段选择器的 **自定义属性** 下。您也可以在任何交易携带该键之前先引用它：在同一分组中选择 **输入自定义属性**，并按集成发送的方式准确输入该键（键区分大小写）。在携带该键的交易到达之前，规则会直接判定为不匹配。

## 黑名单自动拒绝

在评估任何规则之前，Didit 会将交易的实体与您应用的黑名单进行核对。如果发现 **任何** 匹配，交易将被 **立即拒绝**，不再评估规则。

系统会检查以下实体：

| 实体 | 黑名单类型 | 检查内容 |
| - | - | - |
| **用户（申请人）** | 用户黑名单 | 申请人的 `vendor_data` 标识符 |
| **企业** | 企业黑名单 | 企业的 `vendor_data` 标识符 |
| **钱包地址** | 钱包地址黑名单 | 加密钱包支付方式的 `account_id` |
| **银行账户** | 银行账户黑名单 | 银行转账支付方式的 `account_id` |
| **IP 地址** | IP 地址黑名单 | 来自当事方设备上下文的 IP 地址（支持 CIDR 范围） |
| **设备指纹** | 设备指纹黑名单 | 设备指纹或持久设备 ID |

发生黑名单匹配时：

* 交易状态被设置为 `DECLINED`
* 决策原因被设置为 `blocklisted`
* 会创建一条活动记录，用于审计追踪

> [!NOTE]
>
> 黑名单检查先于规则评估执行。被列入黑名单的实体无论规则配置或分数阈值如何，始终会被拒绝。

## 交易筛查

Didit 与外部 AML 和区块链分析服务商集成，为交易补充风险情报。提交交易时，系统可以：

* **筛查交易对手**，比对全球制裁和观察名单数据库
* **评估钱包地址**（适用于加密交易），比对区块链情报数据，包括与混币器的关联、与受制裁实体的关联以及与高风险服务的交互
* **检查申请人的 AML 状态**，将交易关联的用户与其最新的 AML 筛查结果进行交叉比对

筛查结果会附加到交易上，并纳入规则引擎的评分。如果交易对手或钱包与制裁名单匹配，相应规则会自动标记或拒绝该交易。

## 后续步骤

> [card] [提交交易](https://docs.didit.me/zh/transaction-monitoring/transactions.md)
>
> 介绍交易数据如何组织，以便进行规则评估。

> [card] [加密货币筛查](https://docs.didit.me/zh/transaction-monitoring/aml-screening.md)
>
> 加密货币筛查结果，以及预设规则如何使用这些结果。

> [card] [设置](https://docs.didit.me/zh/transaction-monitoring/settings.md)
>
> 配置评分阈值和处置工作流。

> [card] [API 参考](https://docs.didit.me/zh/management-api/transactions/create.md)
>
> 创建交易 API endpoint。


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