Create a chain-agnostic EVM-to-Arkade swap.

curl --request POST \
  --url https://api.satora.io/swap/evm/arkade \
  --header 'Content-Type: application/json' \
  --data '
{
  "arkade_htlc_script_version": 123,
  "evm_chain_id": 1,
  "hash_lock": "<string>",
  "receiver_pk": "<string>",
  "target_address": "<string>",
  "token_address": "<string>",
  "user_address": "<string>",
  "user_id": "<string>",
  "amount_in": "<string>",
  "amount_out": 1,
  "bridge_source_chain": "<string>",
  "bridge_source_token_address": "<string>",
  "extra_fees": 1,
  "gasless": true,
  "referral_code": "<string>"
}
'

import requests

url = "https://api.satora.io/swap/evm/arkade"

payload = {
    "arkade_htlc_script_version": 123,
    "evm_chain_id": 1,
    "hash_lock": "<string>",
    "receiver_pk": "<string>",
    "target_address": "<string>",
    "token_address": "<string>",
    "user_address": "<string>",
    "user_id": "<string>",
    "amount_in": "<string>",
    "amount_out": 1,
    "bridge_source_chain": "<string>",
    "bridge_source_token_address": "<string>",
    "extra_fees": 1,
    "gasless": True,
    "referral_code": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    arkade_htlc_script_version: 123,
    evm_chain_id: 1,
    hash_lock: '<string>',
    receiver_pk: '<string>',
    target_address: '<string>',
    token_address: '<string>',
    user_address: '<string>',
    user_id: '<string>',
    amount_in: '<string>',
    amount_out: 1,
    bridge_source_chain: '<string>',
    bridge_source_token_address: '<string>',
    extra_fees: 1,
    gasless: true,
    referral_code: '<string>'
  })
};

fetch('https://api.satora.io/swap/evm/arkade', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.satora.io/swap/evm/arkade",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'arkade_htlc_script_version' => 123,
    'evm_chain_id' => 1,
    'hash_lock' => '<string>',
    'receiver_pk' => '<string>',
    'target_address' => '<string>',
    'token_address' => '<string>',
    'user_address' => '<string>',
    'user_id' => '<string>',
    'amount_in' => '<string>',
    'amount_out' => 1,
    'bridge_source_chain' => '<string>',
    'bridge_source_token_address' => '<string>',
    'extra_fees' => 1,
    'gasless' => true,
    'referral_code' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.satora.io/swap/evm/arkade"

	payload := strings.NewReader("{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.satora.io/swap/evm/arkade")
  .header("Content-Type", "application/json")
  .body("{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.satora.io/swap/evm/arkade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "arkade_htlc_script_version": 123,
  "arkade_server_pk": "<string>",
  "btc_vhtlc_address": "<string>",
  "chain": "<string>",
  "client_evm_address": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "evm_chain_id": 123,
  "evm_coordinator_address": "<string>",
  "evm_expected_sats": "<string>",
  "evm_funding_confirmations": 1,
  "evm_htlc_address": "<string>",
  "evm_htlc_kind": "erc20",
  "evm_htlc_version": 123,
  "evm_refund_locktime": 123,
  "fee_sats": 123,
  "gasless": true,
  "hash_lock": "<string>",
  "id": "<string>",
  "network": "<string>",
  "receiver_pk": "<string>",
  "sender_pk": "<string>",
  "server_evm_address": "<string>",
  "source_amount": "<string>",
  "source_token": {
    "chain": "Arkade",
    "decimals": 1,
    "name": "<string>",
    "symbol": "<string>",
    "token_id": "btc"
  },
  "status": "pending",
  "target_amount": "<string>",
  "target_arkade_address": "<string>",
  "target_token": {
    "chain": "Arkade",
    "decimals": 1,
    "name": "<string>",
    "symbol": "<string>",
    "token_id": "btc"
  },
  "unilateral_claim_delay": 123,
  "unilateral_refund_delay": 123,
  "unilateral_refund_without_receiver_delay": 123,
  "vhtlc_refund_locktime": 123,
  "bridge_source_chain": "<string>",
  "bridge_source_token_address": "<string>",
  "btc_claim_txid": "<string>",
  "btc_fund_txid": "<string>",
  "evm_claim_txid": "<string>",
  "evm_fund_txid": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

POST

swap

evm

arkade

Create a chain-agnostic EVM-to-Arkade swap.

curl --request POST \
  --url https://api.satora.io/swap/evm/arkade \
  --header 'Content-Type: application/json' \
  --data '
{
  "arkade_htlc_script_version": 123,
  "evm_chain_id": 1,
  "hash_lock": "<string>",
  "receiver_pk": "<string>",
  "target_address": "<string>",
  "token_address": "<string>",
  "user_address": "<string>",
  "user_id": "<string>",
  "amount_in": "<string>",
  "amount_out": 1,
  "bridge_source_chain": "<string>",
  "bridge_source_token_address": "<string>",
  "extra_fees": 1,
  "gasless": true,
  "referral_code": "<string>"
}
'

import requests

url = "https://api.satora.io/swap/evm/arkade"

payload = {
    "arkade_htlc_script_version": 123,
    "evm_chain_id": 1,
    "hash_lock": "<string>",
    "receiver_pk": "<string>",
    "target_address": "<string>",
    "token_address": "<string>",
    "user_address": "<string>",
    "user_id": "<string>",
    "amount_in": "<string>",
    "amount_out": 1,
    "bridge_source_chain": "<string>",
    "bridge_source_token_address": "<string>",
    "extra_fees": 1,
    "gasless": True,
    "referral_code": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    arkade_htlc_script_version: 123,
    evm_chain_id: 1,
    hash_lock: '<string>',
    receiver_pk: '<string>',
    target_address: '<string>',
    token_address: '<string>',
    user_address: '<string>',
    user_id: '<string>',
    amount_in: '<string>',
    amount_out: 1,
    bridge_source_chain: '<string>',
    bridge_source_token_address: '<string>',
    extra_fees: 1,
    gasless: true,
    referral_code: '<string>'
  })
};

fetch('https://api.satora.io/swap/evm/arkade', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.satora.io/swap/evm/arkade",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'arkade_htlc_script_version' => 123,
    'evm_chain_id' => 1,
    'hash_lock' => '<string>',
    'receiver_pk' => '<string>',
    'target_address' => '<string>',
    'token_address' => '<string>',
    'user_address' => '<string>',
    'user_id' => '<string>',
    'amount_in' => '<string>',
    'amount_out' => 1,
    'bridge_source_chain' => '<string>',
    'bridge_source_token_address' => '<string>',
    'extra_fees' => 1,
    'gasless' => true,
    'referral_code' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.satora.io/swap/evm/arkade"

	payload := strings.NewReader("{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.satora.io/swap/evm/arkade")
  .header("Content-Type", "application/json")
  .body("{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.satora.io/swap/evm/arkade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"arkade_htlc_script_version\": 123,\n  \"evm_chain_id\": 1,\n  \"hash_lock\": \"<string>\",\n  \"receiver_pk\": \"<string>\",\n  \"target_address\": \"<string>\",\n  \"token_address\": \"<string>\",\n  \"user_address\": \"<string>\",\n  \"user_id\": \"<string>\",\n  \"amount_in\": \"<string>\",\n  \"amount_out\": 1,\n  \"bridge_source_chain\": \"<string>\",\n  \"bridge_source_token_address\": \"<string>\",\n  \"extra_fees\": 1,\n  \"gasless\": true,\n  \"referral_code\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "arkade_htlc_script_version": 123,
  "arkade_server_pk": "<string>",
  "btc_vhtlc_address": "<string>",
  "chain": "<string>",
  "client_evm_address": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "evm_chain_id": 123,
  "evm_coordinator_address": "<string>",
  "evm_expected_sats": "<string>",
  "evm_funding_confirmations": 1,
  "evm_htlc_address": "<string>",
  "evm_htlc_kind": "erc20",
  "evm_htlc_version": 123,
  "evm_refund_locktime": 123,
  "fee_sats": 123,
  "gasless": true,
  "hash_lock": "<string>",
  "id": "<string>",
  "network": "<string>",
  "receiver_pk": "<string>",
  "sender_pk": "<string>",
  "server_evm_address": "<string>",
  "source_amount": "<string>",
  "source_token": {
    "chain": "Arkade",
    "decimals": 1,
    "name": "<string>",
    "symbol": "<string>",
    "token_id": "btc"
  },
  "status": "pending",
  "target_amount": "<string>",
  "target_arkade_address": "<string>",
  "target_token": {
    "chain": "Arkade",
    "decimals": 1,
    "name": "<string>",
    "symbol": "<string>",
    "token_id": "btc"
  },
  "unilateral_claim_delay": 123,
  "unilateral_refund_delay": 123,
  "unilateral_refund_without_receiver_delay": 123,
  "vhtlc_refund_locktime": 123,
  "bridge_source_chain": "<string>",
  "bridge_source_token_address": "<string>",
  "btc_claim_txid": "<string>",
  "btc_fund_txid": "<string>",
  "evm_claim_txid": "<string>",
  "evm_fund_txid": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Body

application/json

Request to create an EVM-to-Arkade swap.

User sends any ERC-20 token on EVM, receives BTC on Arkade.

arkade_htlc_script_version

integer<int64>

required

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

evm_chain_id

integer<int64>

required

Numeric EVM chain ID: 1 (Ethereum), 137 (Polygon), 42161 (Arbitrum).

Required range: x >= 0

hash_lock

string

required

Hash lock (0x-prefixed 32-byte hex). Client generates secret, computes SHA256(secret).

receiver_pk

string

required

User's Arkade VHTLC claim key (receiver).

target_address

string

required

Arkade address where the user wants to receive BTC.

token_address

string

required

ERC-20 contract address of the source token on the EVM chain.

user_address

string

required

User's EVM address (sender of the ERC-20 token).

user_id

string

required

User ID derived from wallet for recovery purposes.

amount_in

string | null

Source token amount in smallest units (mutually exclusive with amount_out).

amount_out

integer<int64> | null

Desired BTC output in sats (mutually exclusive with amount_in).

Required range: x >= 0

bridge_source_chain

string | null

Optional: CCTP bridge source chain (e.g., "Ethereum", "Optimism", "Solana"). When set, the user's source USDC originates on this chain and hops through CCTPv2 to Arbitrum before the HTLC is created. The backend pads deposit_amount by the fast-transfer fee at UserOp-calldata time.

bridge_source_token_address

string | null

Optional: USDC address on the bridge source chain (0x address on EVM chains, base58 mint on Solana).

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

gasless

boolean

Whether to use gasless relay for funding (server submits tx on behalf of user).

referral_code

string | null

Optional referral code for tracking.

Response

Swap created successfully

EVM → Arkade (generic) swap response

arkade_htlc_script_version

integer<int64>

required

arkade_server_pk

string

required

btc_vhtlc_address

string

required

chain

string

required

client_evm_address

string

required

created_at

string<date-time>

required

evm_chain_id

integer<int64>

required

evm_coordinator_address

string

required

The coordinator this swap is pinned to (the HTLC refundAddress).

evm_expected_sats

string

required

evm_funding_confirmations

integer<int64>

required

Blocks the deposit must be buried under before the server acts on it (funding finality on this chain). With the funding receipt's block and the chain head a client can show the confirmation progress.

Required range: x >= 0

evm_htlc_address

string

required

evm_htlc_kind

enum<string>

required

HTLC family of the lock: erc20 (HTLCErc20 + HTLCCoordinator) or native (HTLCNative + HTLCNativeCoordinator).

Available options:

erc20,

native

evm_htlc_version

integer<int64>

required

HTLCErc20 contract VERSION of the deployment this swap lives on — the EIP-712 domain version string for redeem/refund signatures.

evm_refund_locktime

integer<int64>

required

fee_sats

integer<int64>

required

gasless

boolean

required

Whether this swap was created with gasless relay (Permit2)

hash_lock

string

required

string

required

network

string

required

receiver_pk

string

required

sender_pk

string

required

server_evm_address

string

required

source_amount

string

required

source_token

object

required

Show child attributes

status

enum<string>

required

Atomic swap state machine for BTC --> Target Asset swaps using HTLCs.

Overview

This enum tracks the state of an atomic swap between Bitcoin (via Lightning/Arkade) and Target Asset (on Polygon, Ethereum, etc). The swap uses Hash Time-Locked Contracts (HTLCs) to ensure atomicity without requiring trust.

Normal Flow

Pending → ClientFunded → ServerFunded → ClientRedeemed → ServerRedeemed

Client creates swap request → Pending
Client sends BTC → ClientFunded
Server locks WBTC in Polygon HTLC → ServerFunded
Client reveals secret to claim Target Asset → ClientRedeemed
Server uses secret to claim BTC → ServerRedeemed (terminal)

Refund Flows

Pending → Expired (no funding)
ClientFunded → ClientRefunded (client refunds before server funds)
ServerFunded → ClientFundedServerRefunded (HTLC timeout)

State Diagram

See swap_states.md for a complete state diagram and detailed documentation.

Security

Bitcoin HTLC timeout must be longer than Polygon HTLC timeout
Secret becomes public when client claims TargetAsset on Polygon
ClientRefundedServerFunded is an error state that should never occur

Available options:

pending,

clientfundingseen,

clientfunded,

clientrefunded,

serverfunded,

clientredeeming,

clientredeemed,

serverredeemed,

clientfundedserverrefunded,

clientrefundedserverfunded,

clientrefundedserverrefunded,

expired,

clientinvalidfunded,

clientfundedtoolate,

serverwontfund,

clientredeemedandclientrefunded

target_amount

string

required

target_arkade_address

string

required

target_token

object

required

Show child attributes

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

bridge_source_chain

string | null

CCTP bridge source chain. Set when the source USDC originated on another CCTP chain and hopped to Arbitrum via CCTPv2 before the HTLC was created. source_token still reports the post-hop Arbitrum USDC; this field tells the SDK what chain the user is expected to burn from.

bridge_source_token_address

string | null

Native USDC address on the bridge source chain (base58 mint on Solana).

btc_claim_txid

string | null

btc_fund_txid

string | null

evm_claim_txid

string | null

evm_fund_txid

string | null

General

Quotes & Tokens

BTC → EVM Swaps

EVM → BTC Swaps

BTC ↔ Arkade

Swap Management

Refunds

Delegate

Support

Create a chain-agnostic EVM-to-Arkade swap.

Body

Response

Overview

Normal Flow

Refund Flows

State Diagram

Security