Wallet Verification

The Wallet Verification API enables you to verify ownership of wallet addresses through multiple verification flows. This supports compliance requirements and fraud prevention.

Create Wallet Verification

Create a new wallet verification request. Users prove ownership through SATOSHI_TEST, VISUAL_PROOF, SELF_DECLARED, or SIGNATURE_PROOF flows.

Create Wallet Verification is dispatched through Shufti's main verification endpoint by including a travel_rule block with type set to wallet_verification.

Endpoint

POST {{BASE_URL}}/

note

This is the same / endpoint used by other Shufti verification services. Authenticate using Basic Auth with your client_id and secret_key (or an Access Token), exactly as described in Get Started - Authentication.

Request Parameters

Parameter	Required	Type	Description
travel_rule.type	Yes	string	Must be set to `wallet_verification` to route this request as a wallet verification.
travel_rule.asset	Yes	string	Cryptocurrency asset code to verify (e.g., `BTC`, `ETH`).
travel_rule.blockchain	Yes	string	Blockchain network name (e.g., `Bitcoin`, `Ethereum`).
travel_rule.address	Yes	string	Wallet address to verify.
travel_rule.allowed_flows	No	array	Verification flow types to allow. See Verification Flows. If omitted or empty, all flows are allowed — which includes `SATOSHI_TEST`, so `satoshi_flow` then becomes required.
travel_rule.allowed_languages	No	array	Language codes for the verification form (e.g., `en`, `es`). If omitted, all languages are allowed.
travel_rule.metadata	No	string	Custom metadata or notes.
travel_rule.satoshi_flow	Cond.	object	Configuration for `SATOSHI_TEST` flow. Required when `SATOSHI_TEST` is in `allowed_flows`.
travel_rule.satoshi_flow.deposit_address	Cond.	string	Deposit address. Required if using `SATOSHI_TEST`.
travel_rule.satoshi_flow.amount	Cond.	number	Deposit amount, in the asset's smallest unit (e.g., satoshis for BTC, wei for ETH). Required if using `SATOSHI_TEST`.

Verification Flows

Flow	Description
`SATOSHI_TEST`	User sends a small amount to a deposit address to prove wallet ownership.
`VISUAL_PROOF`	User provides visual proof of wallet ownership (screenshot, etc.).
`SELF_DECLARED`	User self-declares wallet ownership.
`SIGNATURE_PROOF`	User signs a message with the wallet's private key to prove ownership.

Supported Languages

Code	Language
en	English
es	Spanish
fr	French
de	German
it	Italian
pt	Portuguese
ru	Russian
zh	Chinese
ja	Japanese
ko	Korean
et	Estonian
cs	Czech
hu	Hungarian
pl	Polish
uk	Ukrainian

Sample Request - SELF_DECLARED (minimal)

The wallet verification payload is sent as a travel_rule block (with type: "wallet_verification") inside the standard Shufti verification envelope. This minimal example uses only the SELF_DECLARED flow.

create-wallet-verification-self-declared
{
  "reference": "sp-tr-wv-001",
  "callback_url": "https://webhook.site/your-unique-id",
  "travel_rule": {
    "type": "wallet_verification",
    "asset": "BTC",
    "blockchain": "Bitcoin",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "allowed_flows": ["SELF_DECLARED"]
  }
}

Sample Request - SATOSHI_TEST (full)

When SATOSHI_TEST is included in allowed_flows, the satoshi_flow object with deposit_address and amount is required.

create-wallet-verification-satoshi-test
{
  "reference": "sp-tr-wv-satoshi-001",
  "callback_url": "https://webhook.site/your-unique-id",
  "travel_rule": {
    "type": "wallet_verification",
    "asset": "BTC",
    "blockchain": "Bitcoin",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "allowed_flows": ["SATOSHI_TEST", "VISUAL_PROOF", "SELF_DECLARED", "SIGNATURE_PROOF"],
    "allowed_languages": ["en", "es"],
    "metadata": "test wallet verification",
    "satoshi_flow": {
      "deposit_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "amount": 100
    }
  }
}

Response

POST / returns the standard Shufti envelope with event: request.pending. The hosted verification form the end user must open is returned as the top-level verification_url (this is the most important field — redirect your user there). The verification then resolves asynchronously; the outcome is delivered to your callback_url (see Responses › Callbacks).

create-wallet-verification-response
{
  "reference": "sp-tr-wv-001",
  "event": "request.pending",
  "verification_url": "https://{{VERIFICATION_DOMAIN}}/travel-rule/wallet-verification/TOKEN",
  "email": null,
  "country": null
}

info

verification_url is the hosted form — share it with the end user to complete verification (the embedded token typically expires in 24 hours). customer_unique_id is also echoed when you supply it.