sumsub-manage-wallet-address-book

Sumsub — ウォレットアドレス帳

どの暗号資産アドレスが組織に属し、各アドレスがどのユーザーに属するかを Sumsub に伝えます。このデータがあれば、Travel Rule への回答を手動キューから自動処理に切り替えられます。

見た目以上に重要な理由

別の VASP があなたのユーザーに関する Travel Rule の情報交換を開始すると、Sumsub は「このウォレットは自社のものですか？」と「誰のものですか？」の 2 つを確認します。保存済みのデータがあれば、人手ではなくデータからどちらの質問にも回答できます。ただし、そのためにはアドレスがすでに登録されている必要があります。

登録するもの	事前に回答できる内容
Wallet Address Book のアドレス	「このウォレットは自社のものですか？」
申請者の payment method として登録したアドレス	両方の質問

未登録のものはすべて手動対応になります。手動対応では件数の増加に耐えられません。取引相手は確認期限を数秒に設定できるためです。事前回答済みのリクエストがどのように届くか、またどのフラグを確認すべきかについては、sumsub-integrate-travel-rule を参照してください。このスキルではデータの登録のみを扱います。

🚧 最もよくある間違いは、入金アドレスだけをアップロードすることです。 決済後に作成された取引では、資金の送金元、つまりユーザーが出金に使用するアドレスについて確認されます。アドレス帳に入金先アドレスしか登録されていない場合、この種のリクエストはすべて通知なく手動審査に回されます。エクスポートに両方の方向のアドレスが含まれているか、ユーザーに明示的に確認してください。

エンドポイント

動詞	パス	目的
POST	/resources/kyt/walletAddress/import	組織が管理するアドレスを一括登録します。本文はウォレットエントリーの JSON 配列 です。1 回の呼び出しで最大 10 000 件です。
POST	/resources/api/applicants/{applicantId}/payments	特定の申請者に対して、1 つのアドレスを cryptoWallet 支払い方法として登録します。

Wallet Address Book には、公開されている一覧表示、更新、削除のエンドポイントはありません。エントリーを確認または削除するには、ユーザーにダッシュボード（Transactions and travel rule → Wallet address book）を案内してください。

混乱を招くエラーにつながる 2 つの前提条件

• 組織が VASP にリンクされている必要があります。 インポートではトークンのクライアント ID から VASP を特定します。VASP がリンクされていない場合は、Your organization is not yet linked to a VASP. Please contact your Customer Success Manager（HTTP 404）で失敗します。これは権限の問題ではなく、再試行しても解決しません。このメッセージを伝えて処理を中止してください。
• テナントに Travel Rule の利用権限 が必要です。ペイロードを作成する前に sumsub-check-permissions で確認し、呼び出しが 403 になるまで待たずに利用権限の不足を報告してください。
• インポートエンドポイントでは、トークンのサブジェクトに admin ロールも必要です。スコープ付きエージェントトークンにはこのロールがない場合があります。利用権限の確認に通ったにもかかわらず 403 が返る場合は、これが原因です。ユーザーは admin 権限のあるトークンを使用するか、ダッシュボードからインポートする必要があります。

認証 — アプリトークン + シークレット（サンドボックス専用）

このスキルは公開 Sumsub API と通信し、認証リファレンスに従って各リクエストに署名します。仕組みの詳細は sumsub-api-auth スキルを参照してください。401 Invalid signature が発生した場合は、こちらをお読みください。

⚠️ サンドボックストークンのみ。 ここでは本番環境のアプリトークンを受け入れたり、使用したりしないでください。ウォレットアドレスは事業者を特定するデータであり、本番環境で誤ったインポートを行うと、実際の 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:... — ダッシュボードから取得したサンドボックス用アプリトークン。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

ユーザーが会話ですでに認証情報を提示している場合は、それを再利用してください。そうでない場合は、実行前に一度だけ確認してください。シークレットを決してそのまま返してはいけません。

手順

1. ユーザーが登録するアドレスと、特にそのアドレスがどちら向きに使われるかを確認します。「自分たちのウォレット」とだけ言われた場合は、出金先アドレスが含まれるかどうかを確認してください。
2. 適切なエンドポイントを選びます。
   • アドレスが多数あり、組織レベルで所有権を管理する場合 → インポート。
   • 既知の申請者に属するアドレスが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	2つのうちいずれか	プレーンなアドレス。
walletAddressHash	2つのうちいずれか	アドレス自体を送信したくない場合に使用します。
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 は必須で、上記の列挙値のいずれかである必要があります。トラベルルールでは、常に cryptoWallet です。インポート時と同じ条件で、accountIdentifier の代わりに accountIdentifierHash を送信できます。

applicantId は本文ではなくパスに指定します。これは Sumsub 内部の applicant 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 — 1 つのアドレスを 1 人の applicant に紐付けます。

関連情報

• references/wallet-address-schema.md — フィールドごとのスキーマ、ソースタイプの優先順位、エラー形式。
• sumsub-integrate-travel-rule — このデータを使用するフロー。
• Sumsub のドキュメント：ウォレットアドレス帳、トラベルルールの設定。