Skip to main content
POST
Create a new Bitcoin (on-chain) to Arkade swap request

Body

application/json
arkade_htlc_script_version
integer<int64>
required

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

btc_htlc_script_version
integer<int64>
required

Bitcoin HTLC 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 (20-byte hex string, no 0x prefix). The client generates a secret and computes HASH160(secret) = RIPEMD160(SHA256(secret)). This hash is used for both the on-chain Bitcoin HTLC (OP_HASH160) and the Arkade VHTLC. Client will use the secret to claim the Arkade VHTLC later.

refund_pk
string
required

User's refund public key for the on-chain Bitcoin HTLC

sats_receive
integer<int64>
required

Amount the user wants to receive on Arkade in satoshis

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

Optional referral code for fee exemption

Response

Swap created successfully

BTC → 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

asset_amount
integer<int64>
required

Amount user must send in satoshis Deprecated: please use [target_amount]

btc_htlc_address
string
required

On-chain Bitcoin HTLC P2WSH address (user sends BTC here)

btc_htlc_script_version
integer<int64>
required
btc_refund_locktime
integer<int64>
required

On-chain refund locktime (unix timestamp)

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 (32-byte hex, no 0x prefix)

id
string
required

Unique swap identifier

network
string
required

Bitcoin network

sats_receive
integer<int64>
required

Amount user will receive on Arkade in satoshis

server_vhtlc_pk
string
required

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

source_amount
string
required

Amount user must send 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

target_arkade_address
string
required

User's target Arkade address

target_token
object
required

Target token info

unilateral_claim_delay
integer<int64>
required

Unilateral claim delay in seconds

unilateral_refund_delay
integer<int64>
required

Unilateral refund delay in seconds

unilateral_refund_without_receiver_delay
integer<int64>
required

Unilateral refund without receiver delay in seconds

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

btc_claim_txid
string | null

On-chain claim transaction ID (server claim)

btc_fund_txid
string | null

On-chain funding transaction ID