Skip to main content
POST
curl

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Body

application/json
wallet_address
string

The wallet address to verify. Optional; when empty, the address must be supplied when a proof is started.

Maximum string length: 128
chain
string

Chain token for the address, for example ETH, BTC or SOL. Use the same token as in your wallet address book. Message signing and the Satoshi test are offered only for a supported chain. The address book entry the proof verifies stores it under its canonical identifier (ETH, BTC, SOL, TRX).

Maximum string length: 32
holder_name
string

Name of the wallet holder, used for the beneficiary name match.

Maximum string length: 255
vendor_data
string

Your internal identifier for the holder, carried onto the created address-book entry.

Maximum string length: 255
transaction_id
string<uuid> | null

Optional. Didit transaction UUID of a Travel Rule transfer to advance when the proof verifies.

satoshi_deposit_address
string

Optional. A deposit address you control; supplying it enables the SATOSHI_TEST proof method.

Maximum string length: 128
callback_url
string

Optional. Absolute http(s) URL where the widget returns the customer after completion.

Maximum string length: 512
expires_in_minutes
integer
default:60

Optional. Lifetime of the minted link, in minutes. Automatically extended to cover the Satoshi test window when SATOSHI_TEST is offered.

Required range: 5 <= x <= 10080
wallet_entry_id
string<uuid>

Optional. Request the ownership proof of this address book entry instead of passing wallet_address and chain. The entry must be a customer wallet with a holder (holder_vendor_data), an address and a chain; the saved wallet and holder are always used and a conflicting wallet_address, chain, holder_name or vendor_data is rejected. Cannot be combined with transaction_id.

request_action
enum<string>
default:ensure

Only with wallet_entry_id. ensure and resend return the entry's active link when it has one (200) and create one otherwise (201). new revokes the active link and creates another; it needs request_key.

Available options:
ensure,
resend,
new
request_key
string<uuid>

Only with request_action: new. An idempotency key: repeating the call with the same key returns the same link while it is active, and 410 once it has been revoked or has expired.

Response

An existing active proof link for the wallet address book entry, returned again (wallet_entry_id requests only).

widget_session_id
string<uuid>
token
string

Opaque session token embedded in the widget URL.

url
string

The hosted wallet-ownership widget URL. Open it verbatim in the system browser (never inside a mobile SDK webview).

expires_at
string<date-time>
Last modified on November 1, 2026