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

Body

application/json
arkade_htlc_script_version
integer<int64>
required

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

claim_pk
string
required

User's claim public key for the Arkade VHTLC

hash_lock
string
required

Hash lock provided by the client (0x-prefixed 32-byte hex). The client generates a secret and computes SHA256(secret); the hold invoice and the Arkade VHTLC both lock on this hash.

target_arkade_address
string
required

User's target Arkade address to receive VTXOs

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
invoice_description
string | null

Optional BOLT11 invoice description (max 639 bytes).

referral_code
string | null

Optional referral code for fee exemption

source_amount_sats
integer<int64> | null

Amount the user wants to send via Lightning in satoshis (fees are deducted from it — use this for send-max flows). Mutually exclusive with target_amount_sats.

target_amount_sats
integer<int64> | null

Amount the user wants to receive on Arkade in satoshis (fees are added on top of it). Mutually exclusive with source_amount_sats.

Response

Swap created successfully

Lightning → Arkade 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 server funds

bolt11_invoice
string
required

BOLT11 hold invoice the user must pay

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; sha256 of the client's secret)

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 receive fee is paid out of fee_sats + network_fee_sats

receiver_pk
string
required

User's claim public key (receiver in the VHTLC)

sender_pk
string
required

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

source_amount
string
required

Amount the user must pay via Lightning 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 the user will receive on Arkade in satoshis

target_arkade_address
string
required

User's target Arkade address

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 (user claim)

arkade_fund_txid
string | null

Arkade VHTLC fund transaction ID (server funding)