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

# Create travel-rule widget session

`POST /widget/sessions`

## Request

- Base URL: `https://sandbox.striga.com/api/v1/travel-rule`
- URL: `https://sandbox.striga.com/api/v1/travel-rule/widget/sessions`
- Auth: API key in header `api-key` and API key in header `Authorization`

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.dev/striga/apis/travel-rule.md) - [All operations](https://skmtc.dev/striga/apis/travel-rule/llms.txt) - [OpenAPI document](https://skmtc.dev/striga/apis/travel-rule/revisions/c82fbc1ad95b?raw)