Skip to main content
POST
Create a new Arkade to Lightning swap request

Body

application/json
arkade_htlc_script_version
integer<int64>
required

Arkade VHTLC script version. New swaps must use version 1.

refund_pk
string
required

User's refund public key for the Arkade VHTLC (sender role).

user_id
string
required

User ID derived from wallet for recovery purposes

extra_fees
integer<int32> | null

Optional per-swap fee surcharge in basis points (0..=max_extra_fee_bps configured on the matching developer key).

Required range: x >= 0
lightning_address
string | null

Lightning address (user@domain) to resolve into an invoice over the payout amount. Mutually exclusive with the other destination fields.

lightning_invoice
string | null

BOLT11 invoice the user wants paid. Must carry an amount (which pins the payout — source_amount_sats cannot be combined with it). Mutually exclusive with lightning_address and lnurl.

lnurl
string | null

LNURL-pay string to resolve into an invoice over the payout amount. Mutually exclusive with the other destination fields.

referral_code
string | null

Optional referral code for fee exemption

source_amount_sats
integer<int64> | null

Total amount the user wants to lock on Arkade in satoshis (fees are deducted from the Lightning payout — use this for send-max flows). Only valid with lightning_address/lnurl; mutually exclusive with target_amount_sats.

target_amount_sats
integer<int64> | null

Amount the recipient should receive over Lightning in satoshis (fees are added on top). Required with lightning_address/lnurl unless source_amount_sats is given; optional with lightning_invoice, where it must match the invoice amount.

Response

Swap created successfully

Arkade → Lightning swap response.

arkade_htlc_script_version
integer<int64>
required
arkade_server_pk
string
required

Arkade server's public key

arkade_vhtlc_address
string
required

Arkade VHTLC address the user must fund

client_lightning_invoice
string
required

BOLT11 invoice the server will pay once the VHTLC is funded

created_at
string<date-time>
required

Timestamp of when the swap was created

fee_sats
integer<int64>
required

Protocol fee in satoshis

hash_lock
string
required

Hash lock (0x-prefixed 32-byte hex; the invoice's payment hash)

id
string
required

Unique swap identifier

invoice_expires_at
integer<int64>
required

Unix timestamp after which the invoice can no longer be paid

network
string
required

Bitcoin network

network_fee_sats
integer<int64>
required

Flat network fee in satoshis; the provider's actual Lightning send fee is paid out of fee_sats + network_fee_sats, never on top

receiver_pk
string
required

Server's VHTLC public key (receiver in the VHTLC)

sender_pk
string
required

User's refund public key (sender in the VHTLC)

source_amount
string
required

Amount the user must lock in the Arkade VHTLC in satoshis

source_token
object
required

Source token info

status
enum<string>
required

Current status of the swap

Available options:
pending,
clientfundingseen,
clientfunded,
clientrefunded,
serverfunded,
clientredeeming,
clientredeemed,
serverredeemed,
clientfundedserverrefunded,
clientrefundedserverfunded,
clientrefundedserverrefunded,
expired,
clientinvalidfunded,
clientfundedtoolate,
serverwontfund,
clientredeemedandclientrefunded
target_amount
string
required

Amount paid out on the user's Lightning invoice in satoshis

target_token
object
required

Target token info

unilateral_claim_delay
integer<int64>
required
unilateral_refund_delay
integer<int64>
required
unilateral_refund_without_receiver_delay
integer<int64>
required
vhtlc_refund_locktime
integer<int64>
required

VHTLC refund locktime (unix timestamp)

arkade_claim_txid
string | null

Arkade VHTLC claim transaction ID (server claim)

arkade_fund_txid
string | null

Arkade VHTLC fund transaction ID (user funding)