交易监控规则 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/`	按过滤条件和性能排序列出规则
`POST /v3/transactions/rules/`	创建自定义规则
`GET /v3/transactions/rules/{rule_uuid}/`	读取单条规则及其执行计数
`PATCH /v3/transactions/rules/{rule_uuid}/`	更新自定义规则；切换任意规则的模式
`DELETE /v3/transactions/rules/{rule_uuid}/`	删除自定义规则（永久删除）
`POST /v3/transactions/rules/backtest/`	针对你的历史数据评估假设性规则
`GET /v3/transactions/rules/library/`	浏览包含 150+ 个预设的规则库及其安装状态
`POST /v3/transactions/rules/install/`	按键、套件或两者的交集安装预设
`DELETE /v3/transactions/rules/install/`	按键、套件或两者的交集卸载预设

对应的 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 工具参考。完整的架构（包括字段目录、全部 19 个条件运算符、速率窗口、分组条件以及六种操作类型）记录在 Rules & Scoring 页面中，并嵌入在 API 参考中。

创建、回测、启用

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

以 TEST 模式创建规则

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 规则会评估每一笔新交易并记录其本应命中的结果，但绝不会改动交易的分数或状态。

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

对历史数据进行回测

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
  }'

{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }

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

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

启用

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"}'

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

沙盒应用从不评估规则。 沙盒交易只会被存储，不做其他处理，因此在沙盒应用上启用规则不会产生任何你可以观察到的变化。在规则上线前，回测是受支持的验证方式，请参阅沙盒中的交易监控。

从其他服务商迁移规则

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

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

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

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

转换后的规则如下所示：

{
  "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 中明确说明，而不是悄悄做近似处理。

在将服务商的规则重新创建为自定义规则之前，请先查看规则库。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 一直以来保存这些键的方式相同。

后续步骤

规则与评分

完整的规则架构：字段、运算符、频率窗口、操作。

创建规则 API

包含请求和响应架构的端点参考。

规则库

150+ 个预设目录及其套件。

MCP 概览

将 AI 智能体连接到您的 Didit 工作区。

​何时使用哪个入口

​Endpoints

​创建、回测、启用

​从其他服务商迁移规则

​校验错误有意保持精确

​后续步骤

规则与评分

创建规则 API

规则库

MCP 概览

何时使用哪个入口

Endpoints

创建、回测、启用

从其他服务商迁移规则

校验错误有意保持精确

后续步骤