Skip to main content
The wallet-ownership widget is a hosted page that proves one of your customers controls a specific crypto wallet address. Under the EU TFR, a VASP must verify ownership of a self-hosted (unhosted) wallet before releasing funds to or from it above the sunrise threshold - the widget is how Didit collects that proof without you building signing flows yourself. A verified proof marks the matching wallet address book entry as is_ownership_verified: true, which lets a linked Travel Rule transfer advance out of UNCONFIRMED_OWNERSHIP.

When Didit mints it for you

You rarely need to mint a session yourself. When auto_wallet_verification is on in your Travel Rule settings (the default), Didit auto-mints a widget session at transaction creation whenever a transfer needs end-user proof of wallet control:
  • The transfer is in UNCONFIRMED_OWNERSHIP - the counterparty wallet was declared self-hosted at submission.
  • The transfer is outbound and in COUNTERPARTY_VASP_NOT_FOUND - no counterparty VASP could be identified, so ownership proof is the remaining path to completion.
The auto-minted session is returned in the transaction’s action_required block (type: "wallet_ownership", with the url to open), and the SDKs launch it automatically on client-side submission. Inbound transfers that Didit creates for you (a sunrise registration, an inbound TRP inquiry, or the INTERNAL-rail inbound leg) never get an auto-minted session, even when they land in UNCONFIRMED_OWNERSHIP. Mint manually with POST /v3/travel-rule/widget-session/ when you want to pre-verify a wallet before any transfer exists, when you have auto_wallet_verification turned off, or for one of those inbound transfers.

What it proves

The widget offers up to four proof methods. Which ones appear depends on how you minted the session and your Travel Rule settings:

Message signing verify contract

Submitting the signature returns 200 with status: "VERIFIED" once it proves control of the wallet. It returns 400 and leaves the proof open, so the customer can sign again, with one of these code values:

Satoshi test verify contract

Verifying a Satoshi test deposit is asynchronous, because the transaction has to be seen on-chain and then be confirmed. Submitting the deposit’s txid returns 200 with status: "PENDING" while the deposit is not yet confirmed on-chain - the txid is retained, not discarded. It returns 200 with status: "VERIFIED" once the deposit confirms. It returns 400 with status: "REJECTED" for a genuinely wrong deposit: sent from another wallet, not the expected amount to the deposit address, older than the challenge, or a transaction that already proved another wallet. The proof is closed and the customer can start a new one while the session has attempts left. A deposit that is not indexed yet also returns 200 with status: "PENDING", and a lookup that fails on Didit’s side returns 400 with code DEPOSIT_LOOKUP_FAILED: in both cases the proof stays open and Didit keeps checking. It returns 410 if the test window expires before a valid deposit is seen. Once a txid has been submitted, a background job rechecks the pending deposit every five minutes and completes the proof after the transaction confirms, so the customer does not need to resubmit the txid. When you pass a satoshi_deposit_address, the widget session’s own expires_at is extended to at least the 24-hour Satoshi test window, giving the deposit time to confirm before the session itself expires.

Flow

1

Mint a widget session

Call POST /v3/travel-rule/widget-session/ with the wallet you need verified. Optionally link it to a transfer so the transfer advances automatically once ownership is proven.
2

Open the returned URL

Send your customer to the url from the response. They complete a proof there - no Didit account or API key needed; the token in the URL is the authentication.
3

Detect completion

When a proof is verified, the widget marks the address-book entry verified and, if the session is linked to a transfer, advances it. Watch for travel_rule.status.updated (linked transfers) or poll the widget context.

Mint a widget session

This example links the session to the declared self-hosted transfer from the Travel Rule guide, so wallet_address is that transfer’s destination wallet. A session linked to a transfer only accepts proofs for the transfer’s counterparty wallet.
Always open the url returned in the response verbatim - do not construct it yourself.

Open the returned URL

The widget is web-only in this release. Open the url in the system browser or a custom tab - never inside a Didit mobile SDK webview.Message signing works with wallets installed in the customer’s browser, which the widget discovers through the EIP-6963 and Wallet Standard protocols. Pairing a separate mobile wallet app, for example by QR code, is not available today, so the widget does not hand off to another app. An in-app webview, such as the Didit Web/Flutter/React Native/iOS/Android SDK webview, cannot reach the customer’s browser wallets, so a widget opened there leaves the customer without a way to sign.On mobile, launch the url with the OS browser (SFSafariViewController / Chrome Custom Tabs, or the default browser) instead of rendering it in a webview. On web, a normal tab or popup is fine.

Detect completion

The widget exposes a public read endpoint keyed by the token - poll it to see progress, or rely on webhooks when the session is linked to a transfer:
  • completed_at becomes non-null once a proof is verified.
  • Each entry in proofs carries the fields its method needs: a SATOSHI_TEST proof adds deposit_address, expected_amount, and its own expires_at; a MESSAGE_SIGNING proof adds challenge, the string the customer signs.
  • A SATOSHI_TEST proof can sit at status: "PENDING" while its deposit is seen on-chain but unconfirmed, with no action needed from you or the customer - see Satoshi test verify contract above.
  • When the session was minted with a transaction_id, verifying the proof advances the linked transfer, and on a live application a travel_rule.status.updated webhook fires. Prefer the webhook over polling. An inbound TRP inquiry is approved back to the sender and moves to COMPLETED once that approval is delivered. Any other transfer in UNCONFIRMED_OWNERSHIP (or an inbound one ON_HOLD) moves to COMPLETED, or to COUNTERPARTY_MISMATCHED_DATA when the beneficiary name does not match the wallet holder, and a settled sunrise deposit that completes continues to FINISHED. An outbound transfer in COUNTERPARTY_VASP_NOT_FOUND moves to COMPLETED.
  • A SCREENSHOT proof keeps status: "PENDING" in this context even after you confirm ownership. You approve it with POST .../travel-rule/ownership/, which only accepts a transfer awaiting ownership confirmation. A screenshot therefore has no approval path on a session with no linked transfer, or on a session linked to an outbound transfer in COUNTERPARTY_VASP_NOT_FOUND: turn off allow_screenshot_proof if those sessions must not offer it.
  • After a rejected proof the session takes a new attempt while attempts remain. max_attempts, attempts_used, and attempts_remaining report the count, a rejected proof carries rejection_reason, and when attempts_remaining is 0 starting another proof answers 409 and you mint a new session.
  • The context endpoint returns 404 for an unknown token and 410 once the session has expired without completing.
There are no one-shot dependencies here: the widget and your backend both converge on the same durable state (the verified address-book entry and the transfer status), so a dropped webhook or a closed tab is always recoverable by re-reading the transfer or the widget context.

Localization and branding

The widget renders in 54 languages, following the language path of the link (or the browser default). When whitelabel is enabled for your application, the widget inherits your verification-flow branding automatically: logo, brand colors, button and panel styling, custom font, favicon, and your app’s public name in the title. No separate configuration - the same customization you set up for KYC sessions applies here. A user who returns to an already-completed link sees the completion screen again; if you passed a callback_url, the widget returns them there. Expired links show a branded expiry screen prompting them to request a new link. Mint a new session with POST /v3/travel-rule/widget-session/ for them: resending a transfer with action: "resend" does not mint one.

Next steps

Travel Rule

The full exchange lifecycle, rails, settings, and receiving flows.

Wallet address book

Register the wallets you control so inbound transfers resolve against them.

Webhooks

Subscribe to travel_rule.status.updated to react when a proof advances a transfer.

Native SDKs

Open the widget URL with the system browser, not the SDK webview.
Last modified on October 28, 2026