Skip to main content
POST
Create a pay-through order

Authorizations

Authorization
string
header
required

Secret organization API key from the partner panel, for servers. Sent on swap creation as Authorization: Bearer <key> to attribute the swap to your organization. Optional; an invalid key is rejected. Never use it in client-side code.

Headers

Idempotency-Key
string | null

Optional secret, caller-generated key (random UUIDv4 or 32-byte hexadecimal value). Reuse the same key and request to recover the original creation response.

Body

application/json

Body of POST /v2/swap/pay.

destination
string
required

Where the maker delivers: a Liquid address (confidential or explicit), a Bitcoin address, or an Arkade address. The layer is inferred from the address; it must belong to the maker's network.

asset
string | null

Destination asset, when the layer carries more than one (Liquid: L-BTC or L-USDT). Optional: with several routes to the layer the maker delivers the one that does not convert the payer's bitcoin, so naming an asset is how a payer asks for a conversion rather than something they have to know to say.

invoiceAmount
integer<int64> | null

Sats the payer sends over Lightning (the hold invoice's amount). Exactly one of invoiceAmount / payoutAmount is required.

Required range: x >= 0
pairHash
string | null

Optional pairHash rate-lock against the reverse rate card the payer quoted from; a mismatch is 400 pair_hash_mismatch.

payoutAmount
integer<int64> | null

What the destination must receive, in the destination asset's smallest unit. The maker inverts the rate card to find the invoice amount; the delivered amount is the card's own net output for that input, so it is at least this value.

Required range: x >= 0
webhook
object | null

Optional HTTPS callback for status changes (Boltz webhook shape).

Response

Swap created; hold invoice minted.

POST /v2/swap/pay response — a pay-through swap.

destination
string
required

The destination, as accepted.

destinationLayer
string
required

Destination layer: BTC_L1, BTC_LIQUID, LIQUID_LIQUID or BTC_ARKADE.

expiresAt
integer<int64>
required

Unix timestamp after which the unpaid hold invoice expires.

fees
object
required

The fee snapshot a pay-through was priced at, in the destination asset's smallest unit.

id
string
required
invoice
string
required

BOLT11 hold invoice the payer pays.

invoiceAmount
integer<int64>
required

Sats the payer sends on Lightning.

Required range: x >= 0
pairId
string
required

The reverse pair the swap was priced on.

paymentHash
string
required

The hold invoice's payment hash (hex). Maker-generated: the maker settles the hold with the matching preimage after the payout is out.

payoutAmount
integer<int64>
required

What the destination receives, in its asset's smallest unit.

Required range: x >= 0
payoutAsset
string
required

Destination asset ticker (BTC, L-BTC, L-USDT).

swapAuth
string
required

Per-swap taker credential, 32 bytes hex — see swapAuth.