v1

latestOpenAPI 3.1.02026-07-26165182724.7 KB

Widget

Create travel-rule widget session

Creates (or reuses an unexpired) widget session for the given userId, currency, network, and counterparty identifier within the authenticated application.

Provide exactly one counterparty identifier: counterpartyAddress (on-chain), paymentHash (Lightning), or invoice (a bolt11 Lightning invoice, decoded server-side to its payment hash). Lightning identifiers are valid on BTC / BTC only.

currency and network must be supported and consistent (e.g. SOL / SOL, POL / POLYGON).

Optional forceVerifyOwnership (default false) persists on the session and forces wallet ownership verification for self-hosted OWNED counterparties regardless of Travel Rule thresholds. Reusing an unexpired session can upgrade the flag from false to true but not the reverse.

post/widget/sessions

Request body

userIdstring uuid

User for whom the widget session is created. Provide exactly one of userId or businessId.

businessIdstring uuid

Business for whom the widget session is created. Provide exactly one of userId or businessId.

currencystring required

Ledger currency ticker (e.g. SOL, POL, ETH). Must be a supported LedgerCryptoNetworks key.

networkstring required

Blockchain network for the currency (e.g. SOL, POLYGON, ETH). Must equal the network implied by currency.

counterpartyAddressstring

On-chain counterparty wallet address. Provide exactly one of counterpartyAddress, paymentHash, or invoice.

paymentHashstring

Lightning payment hash (64-character hex, BTC / BTC only). Provide exactly one of counterpartyAddress, paymentHash, or invoice.

invoicestring

A bolt11 Lightning invoice (BTC / BTC only); decoded server-side to its payment hash. Provide exactly one of counterpartyAddress, paymentHash, or invoice.

forceVerifyOwnershipboolean

When true, wallet ownership verification is required for self-hosted OWNED counterparties even if incoming/outgoing thresholds have not been exceeded. Defaults to false when omitted.

txHashstring

Optional on-chain transaction hash of the held deposit this session is resolving. Used to link a specific transaction with VASP counterparty user info. When provided, the session is scoped to that specific held transaction rather than any pending one for the counterparty.

Example request

{
  "userId": "f714f7e8-6ba1-4802-81cc-12040113ff5b",
  "network": "SOL",
  "currency": "SOL",
  "counterpartyAddress": "HfZ2KhxgZcmGbHUREpwj9vMcgBna5Qv1x8qfcMLC2VcY",
  "forceVerifyOwnership": true
}

Response

success

sessionIdstring required

Widget session identifier.

tokenstring required

FusionAuth JWT for the widget session.

widgetUrlstring required

Widget URL containing sessionId and token.

expiresAtstring date-time required

Example response

{
  "sessionId": "widget_session_01jvcnwd02f0tf1p2n5q3f5gdz",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "widgetUrl": "https://widget.example.com/widget_session_01jvcnwd02f0tf1p2n5q3f5gdz?token=eyJhbGciOi...",
  "expiresAt": "2026-05-15T12:00:00.000Z"
}