• The organisation must be linked to a VASP. The import resolves your VASP from the token's client id and fails with

  Your organization is not yet linked to a VASP. Please contact your Customer Success Manager

  (HTTP 404) if there is none. This is not a permissions problem and retrying will not help — relay the message and stop.
• Travel Rule entitlement is required on the tenant. Check with

  sumsub-check-permissions

  before building a payload and report the gap rather than letting the call 403.
• The import endpoint additionally requires the admin role on the token subject. A scoped agent token may not have it — if you get a 403 while the entitlement check passed, this is why; the user has to run the import from a token with admin rights or from the dashboard.

sumsub-api-auth

401 Invalid signature

⚠️ Sandbox tokens only. Do not accept or use a production App Token here. Wallet addresses are business-identifying data, and a bad import in production changes how real Travel Rule requests are answered. If the user offers a production token, refuse and ask them to generate a sandbox pair at https://cockpit.sumsub.com/checkus/home?sbx=true (Connect Sumsub to your AI agent -> Build & configure -> Generate token). Token + secret are shown once — copy both before closing the dialog. The helper script enforces this — it rejects tokens that don't start with

sbx:

unless

SUMSUB_ALLOW_PROD=1

is set.

SUMSUB_APP_TOKEN

sbx:...

SUMSUB_SECRET_KEY

SUMSUB_BASE

https://api.sumsub.com

1. Establish which addresses the user is registering and, critically, in which direction they are used. If they say "our wallets" without qualification, ask whether the list includes withdrawal addresses.
2. Decide which endpoint fits.
   • Many addresses, ownership at organisation level → import.
   • One address that belongs to a known applicant → payment method. Prefer this whenever the applicant is known; it pre-answers both questions instead of one.
3. Check entitlements with

   sumsub-check-permissions

   (looking for

   TRAVEL_RULE

   ).
4. Build the import body with

   ${CLAUDE_SKILL_DIR}/scripts/build_wallet_import.py

   (compact spec on stdin → JSON array on stdout). It validates the address / hash rules below and refuses batches over 10 000.
5. Send it.

   • ${CLAUDE_SKILL_DIR}/scripts/import_wallet_addresses.sh <payload.json>

   • ${CLAUDE_SKILL_DIR}/scripts/add_payment_method.sh <applicantId> <payload.json>

6. Report the result honestly. The import returns

   {successCount, errorCount, errors[]}

   and is partially successful by design — a non-zero

   errorCount

   does not fail the HTTP call. Always surface

   errorCount

   and the first few

   errors[]

   entries; never report "imported" on the strength of a 200.

• walletAddress: "bc1qmdld6jk0r3tvh39yqmet790t5vl3up2rcfzh0d"
• walletAddress: "0x7DF6AF1C17AC9F86F8B3FBBC25253B8B5DF2F3A1" asset: ETH chain: ETH

privacy-preserving variant — see below

• walletAddressHash: "9f2c...64"

| Field | Required | Notes |
|---|---|---|
| `walletAddress` | one of the two | The plain address. |
| `walletAddressHash` | one of the two | Use when you do not want to send the address itself. |
| `asset` | no | Currency code, e.g. `BTC`, `ETH`, `USDT`. |
| `chain` | no | Network, e.g. `BTC`, `ETH`, `TRX`. |

📘 **Either `walletAddress` or `walletAddressHash` must be present.** If you
send **both**, the server recomputes the hash from the address and rejects the
entry when they disagree — so only send both if you are deliberately verifying
your own hashing. When in doubt, send just `walletAddress`.

📘 The `source` field on the entry is ignored — the server stamps imported
addresses as `api` regardless. That matters: only addresses whose source is
`api`, `dashboard`, a previously confirmed exchange, or a registered payment
method are trusted for automatic ownership confirmation. Addresses Sumsub
merely inferred (from attribution or from your transaction data) are not.

• import —

  successCount

  ,

  errorCount

  , and

  errors[]

  where each entry carries the failing address (or hash) and a reason. Report the counts and the distinct reasons, not a raw dump of 10 000 rows.
• payment method — the persisted payment-method instance, including its server-assigned id.

• examples/deposit-addresses.json

  — a small multi-chain import.

• examples/withdrawal-addresses.json

  — the direction integrations forget; same shape, different addresses.

• examples/hashed-only.json

  — registering by hash without disclosing the addresses.

• examples/payment-method-crypto.json

  — one address bound to one applicant.

• references/wallet-address-schema.md

  — field-by-field schema, source-type precedence, error shapes.

• sumsub-integrate-travel-rule

  — the flow this data feeds.
• Sumsub docs: Wallet Address Book, Travel Rule settings.