Overview

Use this method to import wallet addresses of your users for further transaction processing.

When submitting the wallet data, you can send:

• Only walletAddress, if you are ready to share the wallet addresses with Sumsub.
• Only walletAddressHash, if you do not want to share direct wallet addresses for security reasons. Calculate the hash as described below.
• Both walletAddressHash and walletAddress, so you can check if your hashing function is the same as in Sumsub. In case the functions differ, the response returns an error.

Calculate walletAddressHash

Calculate the hash as follows:

1. Take the wallet address as a string. Do not add spaces or other characters.
2. Convert all letters to lowercase.
3. Calculate the SHA-256 hash of the UTF-8 bytes of the string.
4. Encode the 32-byte result using standard Base64 (RFC 4648, with = padding). The result has 44 characters. Do not use hex or URL-safe Base64.

Example:

0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed → 0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed → t3XoKE2dQrJrF4sdPtgFDcTBrwg1EAPYKYhqdPyOCfw=

Python:

base64.b64encode(hashlib.sha256(address.lower().encode("utf-8")).digest()).decode()

Required permissions

To use this method:

• Your app token must be assigned your account's admin role (not a scoped/limited-permission role) — this is a separate check from the usual permission system.
• Your account must be registered as a VASP, with Travel Rule enabled.

Both conditions are required — missing either one returns a 403 Forbidden.

Request example

curl -X POST \
     'https://api.sumsub.com/resources/kyt/walletAddress/import' \
     -H 'content-type: application/json' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \
     -d '[
            {
              "walletAddress": "0x52908400098527886e0f7030069857d2e4169ee7",
              "chain": "ETH"
            },
            {
              "walletAddressHash": "t3XoKE2dQrJrF4sdPtgFDcTBrwg1EAPYKYhqdPyOCfw="
            }
         ]'

Response explained

The response is a JSON file that contains the number of imported wallet records. If some records failed to be imported, it will be specified in the response.

The following tables explain the fields of the response body.

Root fields

errors[] element fields

Response examples

If the request is successfully sent and all records are imported without errors, you will get a response like the following:

{
  "importedCount": 2,
  "failedCount": 0
}

If some records fail to import while others succeed, failedCount and errors reflect the failures:

{
  "importedCount": 2,
  "failedCount": 1,
  "errors": [
    {
      "error": "Either walletAddress or walletAddressHash must not be empty",
      "walletAddressHash": "",
      "walletAddress": ""
    }
  ]
}

If the request itself fails (for example, malformed JSON or an unauthorized caller), you wil lreceive an HTTP response containing an error code along with a message explaining the error. For example:

{
  "code": 400,
  "description": "Human-readable description",
  "correlationId": "0d3457fdac54803edf23c90000000000"
}