sumsub-manage-wallet-address-book

Sumsub — 钱包地址簿

告知 Sumsub 哪些加密货币地址属于你的组织，以及每个地址属于你的哪位用户。这些数据可以将旅行规则问询从人工队列变为自动处理。

这比看起来更重要

当另一个 VASP 发起涉及你某位用户的旅行规则交换时，Sumsub 会问你两个问题：这个钱包是你们的吗？以及它属于谁？ 两个问题都可以根据已存储的数据回答，而不必由人工处理——但前提是该地址已注册。

注册内容	预先回答的问题
Wallet Address Book 中的地址	“这个钱包是我们的吗？”
作为申请人付款方式的地址	两个问题

任何未注册的内容都需要人工处理，而人工处理无法应对大量请求——交易对手可以将确认时限设为几秒。关于预先回答的请求如何到达以及应读取哪些标记，请参阅 sumsub-integrate-travel-rule；本技能仅介绍如何录入数据。

🚧 最常见的错误是只上传充值地址。 结算之后创建的交换会询问资金的发送方地址——也就是用户用于提现的地址。如果地址簿里只有收款地址，这类请求就会悄然转为人工审核。请明确询问用户，其导出内容是否涵盖两个方向。

端点

动词	路径	用途
POST	/resources/kyt/walletAddress/import	批量注册由你的组织控制的地址。请求体为钱包条目的 JSON 数组。每次最多 10 000 条。
POST	/resources/api/applicants/{applicantId}/payments	将一个地址注册到特定申请人名下，作为 cryptoWallet 付款方式。

Wallet Address Book 没有公开的列表、更新或删除端点。要查看或移除条目，请让用户前往控制台（Transactions and travel rule → Wallet address book）。

两项会导致错误难以理解的前提条件

• 组织必须关联到 VASP。 导入操作会根据令牌的客户端 ID 查找你的 VASP；如果没有关联，则会失败并返回 Your organization is not yet linked to a VASP. Please contact your Customer Success Manager（HTTP 404）。这不是权限问题，重试也无济于事——请转达此消息并停止操作。
• 租户必须具备旅行规则权限。构建负载前，请通过 sumsub-check-permissions 检查；如果缺少权限，请报告问题，而不是让调用返回 403。
• 导入端点还要求令牌主体具有 admin 角色。受限 Agent 令牌可能没有该角色——如果权限检查已通过，但调用仍返回 403，原因就在这里；用户必须使用具有 admin 权限的令牌，或通过控制台执行导入。

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

此技能会调用 Sumsub 公共 API，并按照身份验证参考为每个请求签名。完整的工作原理说明位于 sumsub-api-auth 技能中——如果遇到 401 Invalid signature，请阅读该说明。

⚠️ 仅限沙盒令牌。 请勿在此接受或使用生产环境 App Token。钱包地址属于可识别业务身份的数据，在生产环境中错误导入会影响对真实 Travel Rule 请求的响应。如果用户提供了生产环境令牌，请拒绝并让他们前往 https://cockpit.sumsub.com/checkus/home?sbx=true 生成一组沙盒令牌（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。令牌和密钥仅显示一次——关闭对话框前请复制两者。辅助脚本会强制执行此要求——除非设置了 SUMSUB_ALLOW_PROD=1，否则它会拒绝不以 sbx: 开头的令牌。

变量	示例
SUMSUB_APP_TOKEN	sbx:... — 控制面板中的沙盒 App Token。
SUMSUB_SECRET_KEY	创建令牌时显示一次的配对密钥。
SUMSUB_BASE	可选。默认值为 https://api.sumsub.com。

如果用户已在对话中提供凭据，请重复使用；否则，在运行前询问一次。切勿复述密钥。

操作步骤

1. 确认用户要注册哪些地址，尤其要确认这些地址的用途方向。如果用户只说“我们的钱包”，请询问列表是否包含提现地址。
2. 确定适用的端点。
   • 多个地址，所有权归属组织级别 → 导入。
   • 一个属于已知申请人的地址 → 支付方式。只要申请人已知，优先使用此方式；它可以预先回答两个问题，而非只回答一个。
3. 使用 sumsub-check-permissions 检查权限（查找 TRAVEL_RULE）。
4. 使用 ${CLAUDE_SKILL_DIR}/scripts/build_wallet_import.py 构建导入请求体（通过标准输入传入精简规范 → 通过标准输出输出 JSON 数组）。该脚本会验证下方的地址／哈希规则，并拒绝超过 10 000 条的批次。
5. 发送请求。
   • ${CLAUDE_SKILL_DIR}/scripts/import_wallet_addresses.sh <payload.json>
   • ${CLAUDE_SKILL_DIR}/scripts/add_payment_method.sh <applicantId> <payload.json>
6. 如实报告结果。 导入会返回 {successCount, errorCount, errors[]}，并且设计上允许部分成功——errorCount 非零并不意味着 HTTP 调用失败。务必说明 errorCount 并列出前几条 errors[]；切勿仅凭 HTTP 200 就报告“已导入”。

精简规范 — 导入

# Defaults applied to every entry unless overridden per address
defaults:
  asset: BTC          # optional — currency code
  chain: BTC          # optional — network

addresses:
  - walletAddress: "bc1qmdld6jk0r3tvh39yqmet790t5vl3up2rcfzh0d"
  - walletAddress: "0x7DF6AF1C17AC9F86F8B3FBBC25253B8B5DF2F3A1"
    asset: ETH
    chain: ETH
  # privacy-preserving variant — see below
  - walletAddressHash: "9f2c...64"

字段	必填	说明
walletAddress	两者之一	明文地址。
walletAddressHash	两者之一	不想发送地址本身时使用。
asset	否	货币代码，例如 BTC、ETH、USDT。
chain	否	网络，例如 BTC、ETH、TRX。

📘 必须提供 walletAddress 或 walletAddressHash 其中之一。 如果同时发送两者，服务端会根据地址重新计算哈希；如果两者不一致，则会拒绝该条目——因此，只有在有意验证自己的哈希计算时才同时发送两者。如有疑问，只发送 walletAddress。

📘 条目中的 source 字段会被忽略——服务端无论如何都会将导入地址标记为 api。这一点很重要：只有来源为 api、dashboard、此前已确认的交易所或已注册支付方式的地址，才会被信任并自动确认所有权。Sumsub 仅通过归因或你的交易数据推断出的地址则不会。

精简规范 — 支付方式

externalId: "wallet-btc-user-001"   # optional, your own identifier
data:
  type: cryptoWallet                 # cryptoWallet | bankCard | bankAccount | eWallet | other
  accountIdentifier: "bc1qmdld6jk0r3tvh39yqmet790t5vl3up2rcfzh0d"
  fullName: "John Smith"             # the holder, as you know them
  currencyCode: "BTC"
  cryptoChain: "BTC"
  memo: ""                           # for chains that use one (XRP, XLM, …)

data.type 为必填项，且必须是上述枚举值之一；对于 Travel Rule，它始终为 cryptoWallet。accountIdentifierHash 可以按照与导入相同的条件， 替代 accountIdentifier 发送。

applicantId 应放在路径中，而非请求体中——它是 Sumsub 的内部申请人 ID，不是你的 externalUserId。如果用户只有 externalUserId，请先通过 GET /resources/applicants/-;externalUserId={externalUserId}/one 查询。

输出

• 导入 — successCount、errorCount，以及 errors[]；其中每个条目都包含 失败的地址（或哈希）和原因。请报告计数和不同的原因，而不是直接输出 10 000 行原始数据。
• 支付方式 — 已持久化的支付方式实例，包括服务端分配的 ID。

示例

• examples/deposit-addresses.json — 一个小型多链导入示例。
• examples/withdrawal-addresses.json — 集成时常被忘记的方向；结构相同，地址不同。
• examples/hashed-only.json — 仅通过哈希注册，不披露地址。
• examples/payment-method-crypto.json — 将一个地址绑定到一个申请人。

另请参阅

• references/wallet-address-schema.md — 字段级架构、来源类型优先级、错误格式。
• sumsub-integrate-travel-rule — 此数据所馈送到的流程。
• Sumsub 文档：钱包地址簿、Travel Rule 设置。