Skip to main content
POST
Build a BIP 321 payment URI

Authorizations

Authorization
string
header
required

Base64url-encoded auth token

Query Parameters

uppercase
boolean

Upper-case the returned bip321 URI for compact QR encoding. Defaults to false. Fails with 400 if the URI carries case-sensitive data (a label, message, or base58 address).

Body

application/json

Request to build a BIP 321 unified payment URI.

An Ark address is always included. A BOLT11 invoice is only included when amount_sat is given (an amount is required to create one). An on-chain address is included only when onchain is true.

amount_sat
integer<int64> | null

Optional amount (in satoshis) to request. When set, it is embedded in the URI and used to create the BOLT11 invoice. Any server-configured LightningReceiveFees [blocked] are deducted from the amount the client ultimately receives over Lightning.

Required range: x >= 0
label
string | null

Optional label describing the payment, recorded in the URI's label.

message
string | null

Optional message describing the payment, recorded in the URI's message.

onchain
boolean | null

Whether to include a fresh on-chain address as a payment destination. Defaults to false.

Response

Returns the BIP 321 URI and its destinations

A BIP 321 unified payment URI together with its individual destinations.

The bip321 field is the combined bitcoin: URI; the other fields expose each generated destination separately for convenience. A field is null when that destination was not requested or could not be produced.

bip321
string
required

The combined BIP 321 bitcoin: URI.

ark
string | null

The generated Ark address, if any.

bolt11
string | null

The generated BOLT11 invoice, included only when an amount was given.

onchain
string | null

The generated on-chain address, included only when onchain was set.