向 Sumsub KYT…

需要把一笔法币/加密货币支付、Travel Rule 转账或用户平台事件提交到 Sumsub Transaction Monitoring（KYT）时使用。

适用场景

解决思路

1. 把用户意图映射为紧凑 spec：绝大多数交易是 type: finance（一笔支付），此时用户真正要提供的是金额 + 币种 + 方向 + applicant + counterparty。
2. 校验必填项：txnId 非空、applicant.externalUserId 非空；按 type 校验——finance/travelRule 需要 info.amount、info.currencyCode、info.direction（OpenAPI 将这三者标记为 KytTxnInfo 必填）；userPlatformEvent 需要 userPlatformEvent.type；枚举（direction、currencyType、applicant.type、nameType 等）提前校验，失败时给出完整允许值列表。
3. 用 ${CLAUDE_SKILL_DIR}/scripts/build_transaction.py 生成完整 payload（stdin 传紧凑 spec，stdout 输出完整 KytTxnData payload）。
4. 用 ${CLAUDE_SKILL_DIR}/scripts/post_transaction.sh 发起 POST——根据 spec 中是否设置了 _applicantId（不是 payload 中）自动路由到 existing-applicant 或 non-existing-applicant URL。
5. 路由选择：applicant 已存在时 POST https://api.sumsub.com/resources/applicants/{applicantId}/kyt/txns/-/data；applicant 不存在时 POST https://api.sumsub.com/resources/applicants/-/kyt/txns/-/data?levelName=<levelName>（Sumsub 会用 applicant.externalUserId 创建 applicant）。
6. 签名时对带 query string 的解析后路径签名：读取 builder 产出的 sidecar route 文件，取 URI（/resources/applicants/{id}/… 或 /resources/applicants/-/…?levelName=…），对动态段做 URL 编码，并签名与实际发送完全相同的字节。
7. 若绕过脚本手动签名，记住：签名你放到线上的路径——编码形式、包含 query string；签名的 body 字节必须等于发送的字节（不要重新排版空白）。
8. 认证使用 App Token + secret：环境变量 SUMSUB_APP_TOKEN（形如 sbx:...）、SUMSUB_SECRET_KEY，可选 SUMSUB_BASE（默认 https://api.sumsub.com）。
9. 只使用 sandbox token：拒绝生产 App Token（交易监控会作用于真实 applicant 数据并触发真实 KYT 告警）；若用户提供生产 token，拒绝并要求其在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成 sandbox 配对（Connect Sumsub to your AI agent -> Build & configure -> Generate token）；token 与 secret 只显示一次，关闭对话框前复制两者；helper 脚本会拒绝不以 sbx: 开头的 token。
10. 若用户已在对话中提供凭据则复用，否则运行前询问一次；绝不回显 secret。
11. 构造 dashboard 链接：从响应体读取 id（服务端分配的标识符，不是你提供的 txnId）和 clientId，格式为 https://cockpit.sumsub.com/checkus/kyt/txns/<id>?clientId=<clientId>&sbx=true；URL 中放的是服务端 id 而非你提供的 txnId；sbx=true 指向 Sandbox 工作区。
12. 报告时输出：txnId（你的）、服务端 id、applicant externalUserId、direction + amount + currency、counterparty（如有）、响应中的 score / reviewAnswer / riskLabels（如有），以及可点击的 markdown dashboard 链接。
13. 失败时报告 HTTP 状态码 + Sumsub 的 description/errorName；常见 4xx：409 Entity already exists（txnId 冲突，换新 id 或用 bulk-import 方法更新）、400 缺少必填字段（典型为 info.amount、info.currencyCode、info.direction 或 applicant.externalUserId）、400 levelName 未知（使用 non-existing-applicant 流程时）。
14. 紧凑 spec 顶层字段：txnId（必填，你系统中唯一字母数字）、txnDate（可选，格式 yyyy-MM-dd HH:mm:ss+XXXX）、zoneId（可选时区字符串）、type（finance | travelRule | kyc | userPlatformEvent | iGamingSession，默认 finance）。
15. 路由字段二选一：_applicantId（发往已存在 applicant，是路径 id 而非 payload 字段）或 _levelName（发往 non-existing-applicant URL 并带 ?levelName=...）。
16. finance/travelRule 的 info 字段：amount、currency（ISO-4217 法币或 BTC/ETH 等加密货币 ticker）、currencyType（fiat | crypto，默认 fiat）、direction（in | out）、amountInDefaultCurrency（可选）、defaultCurrencyCode、paymentDetails、mcc（可选 4 位商户类别码）。
17. 加密货币专用块（currencyType=crypto 时）：crypto.chain（ETH | BTC | TRX 等，代币必填，原生币留空）、contract、paymentTxnId（链上哈希）、fingerprint（替代区块链标识）、attemptId（可选，重试时）、outputIndex（UTXO 链）。
18. applicant（必填）：externalUserId（必填，你的稳定用户 id）、type（individual | company，默认 individual）、fullName（company 必填，non-existing-applicant 流程建议填）、dob、email、phone、placeOfBirth、address（country/town/street/formatted）、paymentMethod（type 为 bankCard | bankAccount | crypto | cryptoWallet | eWallet | unhostedWallet | card | other，accountId、issuingCountry、3dsUsed、2faUsed、memo）、idDoc（number/country/idDocType）、device（fingerprint/userAgent/ipInfo）。
19. counterparty（finance + travelRule 常见，形状同 applicant 外加若干字段）：externalUserId、type、fullName、registrationNumber、leiCode、residenceCountry、address、institution（code/name/internalId，internalId 为目录中的 VASP id）、ceo（仅 company counterparty 用于 Travel Rule，含 firstName/lastName）。
20. userPlatformEvent 专用（type=userPlatformEvent 时）：userPlatformEvent.type（login | failedLogin | signup | passwordReset | twoFaReset | general）、twoFaUsed、passwordHash。
21. 可选逃生舱：sourceKey（隔离键）、props（自定义 string-string map，如 customField、dailyOutLimit）。
22. 枚举校验表：type 顶层为 finance/travelRule/kyc/auditTrailEvent/userPlatformEvent/scheduledEvent/iGamingSession；direction 为 in/out；currencyType 为 crypto/fiat；applicant.type 与 counterparty.type 为 individual/company；applicant.nameType 为 aliasName/birthName/maidenName/legalName/shortName/tradingName/other；userPlatformEvent.type 为 login/failedLogin/signup/passwordReset/twoFaReset/general。
23. paymentMethod.type 故意不做枚举校验：OpenAPI 只列 smartContract/bankCard/bankAccount，但文档与线上数据接受更多（crypto、eWallet、unhostedWallet 等），builder 原样转发调用方提供的值。

适用边界 · 注意事项

• 不要用于编辑已存在交易的任意字段、批量导入（/kyt/misc/txns/import）、获取/批准/拒绝交易、KYT 规则管理，或非交易创建的 Travel Rule 数据交换流程。
• 不要使用生产 App Token——交易监控会作用于真实 applicant 数据并触发真实 KYT 告警。
• 不要绕过脚本手动签名时对未编码或未含 query string 的路径签名，也不要让签名 body 字节与实际发送字节不一致。