Skip to main content
POST
Cooperative refund (submarine)

Authorizations

X-Swap-Auth
string
header
required

Per-swap credential returned as swapAuth when the swap is created. Required on the routes that decide a live swap's outcome (re-quotes, cooperative refunds), so knowing the swap ID is not enough.

Path Parameters

id
string
required

Swap id (ULID).

Body

application/json

Body of POST /v2/swap/submarine/{id}/refund — Boltz-shaped. The taker submits their pubNonce and the complete unsigned Bitcoin refund transaction, or the versioned RGB PSBT request. Refunds do not reveal a preimage. Bitcoin hash-only requests are no longer accepted.

pubNonce
string
required

The taker's MuSig2 pub nonce, 66 bytes hex.

index
integer<int32> | null

Refund tx input index (defaults to 0).

Required range: x >= 0
protocol
string | null
psbt
string | null
sessionId
string | null
signatureHash
string | null

Deprecated for refunds. Hash-only requests return transaction_required; ignored when a full transaction is provided.

transaction
string | null

Hex-encoded unsigned refund transaction, required for Bitcoin refunds. The server computes the sighash from actual funding outputs via the Bitcoin chain backend, validating that every input spends this swap's lockup.

Response

Maker's pub nonce + partial signature; refund authorization persisted.

Maker's partial-signature response on the cooperative claim/refund endpoints (submarine refund, reverse claim, reverse refund, chain claim, chain refund).

partialSignature
string
required

Maker's 32-byte partial signature, hex.

pubNonce
string
required

Maker's 66-byte MuSig2 pub nonce, hex.