> ## 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 与 MCP - 编程式 KYT 规则管理

> 使用 Didit 的管理 API 端点、MCP 工具及创建-回测-激活工作流，以编程方式创建、调优、回测和迁移 KYT 规则。

业务控制台的每项规则功能也都可以通过编程方式使用：借助你的应用 API 密钥调用 **管理 API**，或为以已登录控制台用户身份行事的 AI 代理调用 **Didit MCP**。你可以用它们在代码中管理规则、将规则集保存在版本控制中，或让 AI 助手为你构建和迁移规则。

## 何时使用哪个入口

| 入口 | 认证方式 | 适用场景 |
| - | - | - |
| **业务控制台** | 控制台登录 | 人工审核每项变更；可视化构建规则并进行回测 |
| **管理 API** | `x-api-key` | 从你的后端实现自动化、以代码管理规则集、由 CI 管理的规则部署 |
| **Didit MCP** | 使用 Didit 登录（OAuth） | AI 助手和代理：Didit 控制台 Copilot、Claude、Cursor 或任意 MCP 客户端 |

## Endpoints

| Endpoint | 用途 |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/zh/management-api/transactions/rules-list) | 按过滤条件和性能排序列出规则 |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/zh/management-api/transactions/rules-create) | 创建自定义规则 |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/zh/management-api/transactions/rules-get) | 读取单条规则及其执行计数 |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/zh/management-api/transactions/rules-update) | 更新自定义规则；切换任意规则的模式 |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/zh/management-api/transactions/rules-delete) | 删除自定义规则（永久删除） |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/zh/management-api/transactions/rules-backtest) | 针对你的历史数据评估假设性规则 |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/zh/management-api/transactions/rules-library) | 浏览包含 150+ 个预设的规则库及其安装状态 |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/zh/management-api/transactions/rules-install) | 按键、套件或两者的交集安装预设 |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/zh/management-api/transactions/rules-uninstall) | 按键、套件或两者的交集卸载预设 |

对应的 MCP 工具包括 `didit_transaction_rule_list`、`didit_transaction_rule_get`、`didit_transaction_rule_create`、`didit_transaction_rule_update`、`didit_transaction_rule_delete`、`didit_transaction_rule_backtest`、`didit_transaction_rule_library_list`、`didit_transaction_rule_install` 和 `didit_transaction_rule_uninstall`，请参阅 [MCP 工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)。

完整的架构（包括字段目录、全部 19 个条件运算符、速率窗口、分组条件以及六种操作类型）记录在 [Rules & Scoring](https://docs.didit.me/zh/transaction-monitoring/rules.md) 页面中，并嵌入在 API 参考中。

## 创建、回测、启用

任何新规则的安全上线流程如下：

**1. 以 TEST 模式创建规则**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Structuring - inbound (custom)",
    "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
    "category": "finance",
    "mode": "TEST",
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "actions": [{"type": "add_score", "value": 35}]
  }'
```

分两部分阅读 payload。`scope` 和 `conditions` 描述**被评估的交易**：币种为欧元且原始 `amount` 低于 10,000 的入账金融交易。`aggregation` 条目描述**同一主体**的**30 天窗口**：至少 20 笔入账欧元金融交易，且其中没有一笔金额达到 10,000 欧元或以上。无论 `evaluation_mode` 设置为何，两个 aggregation 条目都必须成立；该设置只作用于 conditions。

本示例使用原始 `amount`，并在两部分中都将 `currency` 固定为 EUR，因此不依赖汇率标准化。若要对沙盒测试数据进行回测，请为同一主体在 30 天内提交至少 20 笔入账欧元金融交易，每笔的 `amount` 都低于 10,000。`preferred_currency_amount` 和 `amount_in_default_currency` 都不是必需的。沙盒数据摄取流程会存储这些交易；回测需要显式运行。

`TEST` 规则会评估每一笔新交易并记录其本应命中的结果，但绝不会改动交易的分数或状态。

> [!NOTE]
>
> **聚合过滤器不是条件。** 条件只会读取正在被评估的交易；聚合过滤器只会缩小历史窗口，并且只按相等或列表成员关系进行比较。没有 `lt` 过滤器，因此无法只统计**金额低于 10,000 的转账**。
>
> `max ... lt 10000` 条目是支持的窗口上限设置方式：它要求窗口内**每一笔**交易都低于 10,000，这比只统计小额交易更严格。即使二十笔中只有一笔 12,000 的转账，也会使规则无法触发。如果你更希望计数独立成立，可以删除该条目，并在标题中写明这一点：删除后，规则会统计任意金额的入账转账，因此先出现十九笔 50,000 的转账、随后再出现一笔小额转账，也会命中该规则。

**2. 对历史数据进行回测**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "period_days": 90
  }'
```

```json theme={null}
{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }
```

如果 `matched` 计数出乎意料，说明在规则能够真正采取行动之前，需要先调整阈值。

> [!WARNING]
>
> 回测的必须是你即将启用的**完全相同的配置**：相同的 `conditions`、`aggregation`、`evaluation_mode` 和 `scope`。省略 `conditions`、`aggregation` 和 `scope` 本身不会增加任何约束；去掉 scope 可能会纳入已保存规则会跳过的方向或交易类型。省略 `evaluation_mode` 时默认为 `ALL`，因此对于 `ANY` 规则省略它可能会减少命中数。省略 `period_days` 时默认为 90 天；它并不表示不限历史时长。

**3. 启用**

```bash theme={null}
curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "ACTIVE"}'
```

规则会立即应用于**生产环境**应用的所有新交易。

> [!WARNING]
>
> **沙盒应用从不评估规则。** 沙盒交易只会被存储，不做其他处理，因此在沙盒应用上启用规则不会产生任何你可以观察到的变化。在规则上线前，回测是受支持的验证方式，请参阅[沙盒中的交易监控](https://docs.didit.me/zh/integration/sandbox-testing.md#沙盒中的交易监控)。

## 从其他服务商迁移规则

由于规则创建是一次普通的 API 调用，且其架构有完整文档说明，AI 助手可以将其他服务商的规则导出文件转换为 Didit 规则。

1. **导出**您当前服务商的规则。大多数工具可导出为 CSV 或 Excel 格式。
2. **将文件拖入** Didit 控制台助手（或任何已连接 [Didit MCP](https://docs.didit.me/zh/integration/mcp/overview.md) 的 MCP 智能体，例如已连接 Didit MCP 的 Claude）。电子表格会自动转换为文本。
3. 助手会**逐行映射**到 Didit 架构（条件、频率窗口、操作），并在创建任何内容之前向您展示映射结果，同时标出没有 Didit 对应项的内容。
4. 您确认后，它会**以测试模式创建规则**，基于您自己的交易历史进行回测，并报告已创建、失败和无法映射的行。
5. **检查数据并激活**符合预期的规则，可在控制台中操作，也可使用 `PATCH {"mode": "ACTIVE"}` 激活。

服务商导出的文件如下所示：

```csv theme={null}
Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline
```

转换后的规则如下所示：

```json theme={null}
{
  "title": "Structuring - Small Transfers",
  "description": "20+ outbound EUR transfers, all under 10,000 EUR, 30 days",
  "category": "finance",
  "mode": "TEST",
  "evaluation_mode": "ALL",
  "scope": {
    "transaction_types": ["finance"],
    "directions": ["OUTBOUND"]
  },
  "conditions": [
    {"field": "currency", "operator": "eq", "value": "EUR"},
    {"field": "amount", "operator": "lt", "value": 10000}
  ],
  "aggregation": [
    {
      "metric": "count", "operator": "gte", "value": 20,
      "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    },
    {
      "metric": "max", "field": "amount",
      "operator": "lt", "value": 10000, "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    }
  ],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}
```

CSV 行中注明了交易方向和币种，因此规则的两部分都需要体现这两项：`scope` 和 `conditions` 将被评估的交易限定为金额低于 10,000 的欧元转出交易，聚合过滤器则将 30 天窗口限定为同一主体的欧元转出交易。原始 `amount` 只能在同一币种内比较，因此请如上所述保持币种限定。跨币种上限要求窗口内每笔交易都具备标准化金额。仅切换到 `preferred_currency_amount` 并不能确保数据可用：缺失的历史标准化金额可能会被数值聚合视为零。

由于聚合过滤器无法表达*低于 10,000*，因此 `max` 条目可将窗口保持在 10,000 欧元以下。关于它所做的取舍，请参阅上方[创建步骤](#创建、回测、启用)中的说明。对于架构无法精确表达的内容，最好在规则的 `description` 中明确说明，而不是悄悄做近似处理。

> [!TIP]
>
> 在将服务商的规则重新创建为自定义规则之前，请先查看[规则库](https://docs.didit.me/zh/management-api/transactions/rules-library.md)。Didit 提供 150+ 个预设，涵盖常见的风险类型（拆分交易、高频交易、制裁风险敞口、设备复用、加密货币风险），安装一个预设只需一次调用。

## 校验错误有意保持精确

创建和更新端点会根据规则引擎可接受的内容，校验条件、聚合和 scope 值：未知的运算符或指标、格式错误的窗口（例如使用 `"30days"` 而非 `"30d"`）、无效的 scope 方向、没有列表的 `contains_any`、没有 `score` 的 `fuzzy_match`，以及没有 `workflow_id` 时将 `change_status` 设为 `AWAITING_USER`，都会返回 `400`，并指明索引和问题，而不会保存一条悄无声息地永远无法匹配的规则。智能体和脚本应读取错误正文并修正 payload。除 `transaction_types`、`directions` 和 `action_types` 之外的额外 scope 键会被保存，但会被引擎忽略，与 Business Console 一直以来保存这些键的方式相同。

## 后续步骤

> [card] [规则与评分](https://docs.didit.me/zh/transaction-monitoring/rules.md)
>
> 完整的规则架构：字段、运算符、频率窗口、操作。

> [card] [创建规则 API](https://docs.didit.me/zh/management-api/transactions/rules-create.md)
>
> 包含请求和响应架构的端点参考。

> [card] [规则库](https://docs.didit.me/zh/transaction-monitoring/rules-library.md)
>
> 150+ 个预设目录及其套件。

> [card] [MCP 概览](https://docs.didit.me/zh/integration/mcp/overview.md)
>
> 将 AI 智能体连接到您的 Didit 工作区。


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