---
title: "Create travel-rule widget session"
method: POST
path: "/widget/sessions"
tags: ["Widget"]
---

# Create travel-rule widget session

`POST /widget/sessions`

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.

## Request body

- CreateWidgetSessionRequest — Provide exactly one of `userId` or `businessId`. Provide exactly one counterparty identifier: `counterpartyAddress` (on-chain), `paymentHash` (Lightning), or `invoice` (a bolt11 Lightning invoice, decoded server-side to its payment hash).
  - `userId` string, uuid — User for whom the widget session is created. Provide exactly one of `userId` or `businessId`.
  - `businessId` string, uuid — Business for whom the widget session is created. Provide exactly one of `userId` or `businessId`.
  - `currency` string, required — Ledger currency ticker (e.g. `SOL`, `POL`, `ETH`). Must be a supported `LedgerCryptoNetworks` key.
  - `network` string, required — Blockchain network for the currency (e.g. `SOL`, `POLYGON`, `ETH`). Must equal the network implied by `currency`.
  - `counterpartyAddress` string — On-chain counterparty wallet address. Provide exactly one of `counterpartyAddress`, `paymentHash`, or `invoice`.
  - `paymentHash` string — Lightning payment hash (64-character hex, `BTC` / `BTC` only). Provide exactly one of `counterpartyAddress`, `paymentHash`, or `invoice`.
  - `invoice` string — A bolt11 Lightning invoice (`BTC` / `BTC` only); decoded server-side to its payment hash. Provide exactly one of `counterpartyAddress`, `paymentHash`, or `invoice`.
  - `forceVerifyOwnership` boolean — 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.
  - `txHash` string — 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.

## Response `201`

success

- object
  - `sessionId` string, required — Widget session identifier.
  - `token` string, required — FusionAuth JWT for the widget session.
  - `widgetUrl` string, required — Widget URL containing `sessionId` and `token`.
  - `expiresAt` string, date-time, required

## Other responses

- `400` — Bad Request. The request was unacceptable, often due to missing a required parameter.
- `401` — Invalid authentication header
- `404` — No pending action, application not found, or counterparty not found
- `409` — Address is already declared
- `422` — Domain validation error (e.g. unsupported currency/network combination, invalid counterparty identifier).
- `500` — Unexpected server error.

---

[API](https://skmtc.net/striga/apis/striga-v1.md) · [All operations](https://skmtc.net/striga/apis/striga-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/striga/striga-v1/revisions/63e57aa7df45/schema)