sumsub-resolve-currency

Sumsub — 解析币种和链

一个端点同时解决这两方面的问题，但两者截然不同：

type=fiat	type=crypto
ISO 4217 代码的扁平列表，实时获取	数百条链上有数千种资产
没有链、没有合约，也没有歧义	超过一千个符号存在于多条链上
解析 =“是否在列表中”	解析 = (symbol, chain, [contract]) → 唯一确定一种资产

这项技能的大部分内容都围绕加密货币展开，因为交易最容易在这里悄无声息地出错。法币只需检查是否在列表中。

端点

方法	路径	用途
GET	/resources/kyt/currency?type=crypto	加密货币目录。服务端静态数据；可安全地缓存一个会话。
GET	/resources/kyt/currency?type=fiat	实时从汇率提供方获取并整理的法币代码。

省略 type 会返回法币列表。没有公开的链列表端点——请从加密货币目录中提取不重复的 cryptoChain 值。没有汇率端点：Sumsub 在内部进行转换，不会公开所用的汇率。

每个加密货币条目包含 currencyCode、cryptoChain、contractAddress、chainId、name、coinmarketcapId、coingeckoId。

身份验证 — App Token 和密钥（仅限沙盒）

签名方式请参阅身份验证参考；具体机制见 sumsub-api-auth。

⚠️ 仅限沙盒令牌。 除非设置 SUMSUB_ALLOW_PROD=1，否则辅助脚本会拒绝不以 sbx: 开头的令牌。此端点为只读，但这些技能都遵循相同规则——请访问 https://cockpit.sumsub.com/checkus/home?sbx=true 获取一对沙盒凭据（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。

变量	示例
SUMSUB_APP_TOKEN	sbx:...
SUMSUB_SECRET_KEY	配对的密钥。
SUMSUB_BASE	可选。默认为 https://api.sumsub.com。

关键规则

符号不等于资产。 USDT 和 USDC 各自对应目录中十几种不同的资产；ETH 也对应好几种。加密资产的身份由 (currencyCode, cryptoChain) 这一对值确定；如果仍不唯一，还需加上 contractAddress。

📘 空的 cryptoChain 是一个值，不是缺失值。 它表示所属链的原生币——不带链的 BTC 是比特币；cryptoChain: BTC 上的 BTC 也表示同一种资产（服务端会规范化这种常见错误）；而某条封装链上的 BTC 则完全是另一种资产。

🚧 存在歧义时不会解析为默认值，而是解析为空。 查找结果匹配多行时，服务端会记录 Multiple currencies found，且不返回任何币种。因此，缺少链信息时出现的症状不是“汇率错误”，而是“币种无法识别”；依赖该币种的所有后续流程也会在不知不觉中降级。

操作流程

1. 确定类型。 如果代码由三个大写字母组成，且出现在法币列表中，除非用户另有说明，否则将其视为法币。注意意图上的重叠——用户提到“USD”时，几乎从来不是指名为 USD 的代币。

2. 获取目录，使用 ${CLAUDE_SKILL_DIR}/scripts/get_currencies.sh crypto （或 fiat）。将其缓存一个会话；加密货币列表很大且内容静态。

3. 解析，使用 ${CLAUDE_SKILL_DIR}/scripts/resolve_currency.py——传入目录和查询内容。该脚本会转换为大写并去除首尾空格、扩展链别名、将 code == chain 视为原生币；遇到歧义时会报错并列出候选项，而不是擅自选择。

4. 报告要发送的确切字段，不要只说“受支持”：

   "info": {
     "currencyCode": "USDT",
     "currencyType": "crypto",
     "cryptoParams": { "cryptoChain": "TRX" }
   }
   

5. 处理兑换问题——见下文。这是调用方最容易忘记的部分。

amountInDefaultCurrency — 跳过前请先阅读

info.amountInDefaultCurrency + info.defaultCurrencyCode 表示以你的报告货币计价的转账金额。它们看起来是可选的，但在三方面都不是。

🚧 旅行规则阈值会与 amountInDefaultCurrency 比较。 如果缺少该字段，阈值比较会完全跳过，无论转账金额有多小，旅行规则流程都会运行。省略此字段不会损失精度，而是会改变行为。非托管钱包验证阈值也同样如此。

🚧 该值在数据写入时就会冻结。 Sumsub 会在创建交易时计算一次并保存。如果当时使用的汇率有误，记录中的值就会一直有误；之后修正需要回填，而不是重新读取。

📘 如果资产无法解析，就无从转换。 无法识别的 (symbol, chain) 对不会触发转换——这是缺少 cryptoChain 会造成高昂代价的第二个原因。

建议： 如果你知道自己的系统使用的值，请明确发送 amountInDefaultCurrency 和 defaultCurrencyCode。这样，你的账目就能与 Sumsub 的记录保持一致，而且不必依赖你无法控制的某个时刻的第三方汇率。

链别名

链名称会先转换为大写并去除首尾空格，然后再通过固定的别名表映射，之后才进行查找。ETHEREUM、BSC、TRC20、MATIC、POLYGON、BEP20、TRON、SOLANA、AVAX_C 以及另外约二十多个名称都会映射到其规范链名称。别名表之外的名称会按原样使用，因此像 TRON20 或 ERC-20 这样的近似名称无法匹配。

任何端点都不会公开此表——完整列表请参阅 references/crypto-catalogue.md。如果用户的链名称无法解析，请先对照别名表检查，再断定该资产不受支持。

旅行规则的具体说明

除了上述阈值行为，你选择的资产还可能决定能否进行交换。每个目录条目都包含交易对手协议各自使用的词汇映射，而覆盖范围有限。

只有少数目录条目包含针对任一特定协议的映射——Sygna 覆盖最多，其次是 GTR，然后是 CODE；三者的覆盖范围都只占全部条目的一小部分。随着每周的列表任务收录新资产，覆盖范围会不断扩大，因此请先检查，不要想当然。

如果资产没有映射到交易对手所使用的协议，就无法在对方的消息中表示该资产。交换会在发送任何内容之前因验证失败而中止——错误表现为 notEnoughCounterpartyData，看起来像是数据问题，而不是资产支持问题。如果某个小众代币的旅行规则交换以这种方式失败，请先检查词汇覆盖情况，再调试负载。参阅 sumsub-integrate-travel-rule。

输出

• 已解析 — 匹配的条目，以及应发送的准确 currencyCode / currencyType / cryptoChain。如果该符号存在已知冲突，请说明 contractAddress，以便调用方锁定资产。
• 存在歧义 — 列出候选行及其链和合约，并说明用户必须回答的问题。绝不要自行选择。
• 未找到 — 说明是未知的符号，还是仅链未知；在判定不受支持之前，先检查别名表。

示例

• examples/resolve-usdt-tron.json — 常见情况：通过链锁定存在冲突的符号。
• examples/resolve-ambiguous.json — 同一符号但没有链；必须失败，不得猜测。
• examples/resolve-native.json — 原生币示例，展示空链的语义。
• examples/resolve-fiat.json — 成员资格测试。

另请参阅

• references/crypto-catalogue.md — 目录字段、别名表、服务端的解析流程、冲突统计。
• sumsub-create-transaction — 已解析的字段将写入的位置。
• sumsub-integrate-travel-rule — 阈值和协议术语。