Unhosted Wallet Verification API
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}}/
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.
{
"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.
{
"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).
{
"reference": "sp-tr-wv-001",
"event": "request.pending",
"verification_url": "https://{{VERIFICATION_DOMAIN}}/travel-rule/wallet-verification/TOKEN",
"email": null,
"country": null
}
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.
Wallet Verification Object (returned by Read / Detail)
Querying the Read endpoint returns the full wallet-verification object with these fields:
| Parameter | Description |
|---|---|
| _id | Unique identifier of the wallet verification. |
| reference | Your own reference from the create request, attached by Shufti for correlation. |
| wallet_verification_id | Alternative unique identifier (UUID format). |
| address | Wallet address being verified. |
| asset | Cryptocurrency asset code. |
| blockchain | Blockchain network name. |
| status | Verification status: pending, verified, or failed. |
| allowed_flows | Array of available verification flow types. |
| allowed_languages | Array of available language codes. |
| satoshi_flow | Satoshi test configuration (deposit_address, amount); empty object if not configured. |
| metadata | Custom metadata you supplied on create (may be null). |
| token | JWT token for the verification form. Typically expires in 24 hours. |
| url | Complete URL for users to complete verification (surfaced as verification_url on create). |
| origin | Origin recorded for the verification session (may be null). |
| redirect_url | URL the user is redirected to after completion (may be null). |
| created_by | Identifier of the user/system that created the verification. |
| created_at | Creation timestamp (RFC 2822 format). |
| updated_at | Last update timestamp (RFC 2822 format). |
Read Wallet Verifications
Retrieve your own wallet verification records, scoped to your account. Results are paginated and filterable by asset, blockchain, status, and date range.
Endpoint
GET {{BASE_URL}}/travel-rule/wallet-verification/read
Query Parameters
All parameters are optional. Without parameters, returns the first 25 verifications.
| Parameter | Required | Type | Description |
|---|---|---|---|
| page | No | integer | Page number. Defaults to 1. |
| per_page | No | integer | Results per page. Defaults to 25, max 100. |
| search | No | string | Search by wallet address or _id. Your reference is included in every result for correlation. |
| start_date | No | string | Filter by creation date, on or after. DD-MM-YYYY format. |
| end_date | No | string | Filter by creation date, on or before. DD-MM-YYYY format. |
| assets[] | No | array | Filter by one or more asset codes (e.g. BTC, ETH). Repeat the parameter for multiple values. |
| blockchains[] | No | array | Filter by one or more blockchain names (e.g. Bitcoin, Ethereum). Repeat the parameter for multiple values. |
| statuses[] | No | array | Filter by verification status: pending, verified, failed. Repeat the parameter for multiple values. |
Response
{
"error": false,
"status": "SUCCESS",
"message": "",
"data": {
"wallet_verifications": [ ],
"pagination": {
"page": 1,
"per_page": 25,
"total_count": 0,
"total_pages": 0,
"has_next": false,
"has_prev": false
}
}
}
Delete Wallet Verification
Permanently delete a wallet verification record owned by your account.
Endpoint
POST {{BASE_URL}}/travel-rule/wallet-verification/delete
Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| wallet_verification_id | Yes | string | Identifier of the wallet verification to delete. Accepts either the UUID wallet_verification_id or the _id returned by Read. |
Sample Request
{
"wallet_verification_id": "WALLET_VERIFICATION_ID"
}
Response
{
"data": {},
"error": false,
"message": "Wallet verification deleted successfully",
"status": "SUCCESS"
}