curl --request POST \
--url https://api.satora.io/swap/evm/lightning \
--header 'Content-Type: application/json' \
--data '
{
"evm_chain_id": 1,
"token_address": "<string>",
"user_address": "<string>",
"user_id": "<string>",
"amount_in": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"extra_fees": 1,
"gasless": true,
"lightning_address": "<string>",
"lightning_invoice": "<string>",
"lnurl": "<string>",
"referral_code": "<string>",
"target_amount_sats": 123
}
'import requests
url = "https://api.satora.io/swap/evm/lightning"
payload = {
"evm_chain_id": 1,
"token_address": "<string>",
"user_address": "<string>",
"user_id": "<string>",
"amount_in": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"extra_fees": 1,
"gasless": True,
"lightning_address": "<string>",
"lightning_invoice": "<string>",
"lnurl": "<string>",
"referral_code": "<string>",
"target_amount_sats": 123
}
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({
evm_chain_id: 1,
token_address: '<string>',
user_address: '<string>',
user_id: '<string>',
amount_in: '<string>',
bridge_source_chain: '<string>',
bridge_source_token_address: '<string>',
extra_fees: 1,
gasless: true,
lightning_address: '<string>',
lightning_invoice: '<string>',
lnurl: '<string>',
referral_code: '<string>',
target_amount_sats: 123
})
};
fetch('https://api.satora.io/swap/evm/lightning', 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/lightning",
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([
'evm_chain_id' => 1,
'token_address' => '<string>',
'user_address' => '<string>',
'user_id' => '<string>',
'amount_in' => '<string>',
'bridge_source_chain' => '<string>',
'bridge_source_token_address' => '<string>',
'extra_fees' => 1,
'gasless' => true,
'lightning_address' => '<string>',
'lightning_invoice' => '<string>',
'lnurl' => '<string>',
'referral_code' => '<string>',
'target_amount_sats' => 123
]),
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/lightning"
payload := strings.NewReader("{\n \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\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/lightning")
.header("Content-Type", "application/json")
.body("{\n \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.satora.io/swap/evm/lightning")
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 \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\n}"
response = http.request(request)
puts response.read_body{
"chain": "<string>",
"client_evm_address": "<string>",
"client_lightning_invoice": "<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>",
"invoice_expires_at": 123,
"lightning_payment_settled": true,
"network": "<string>",
"network_fee_sats": 123,
"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_token": {
"chain": "Arkade",
"decimals": 1,
"name": "<string>",
"symbol": "<string>",
"token_id": "btc"
},
"wbtc_address": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"evm_claim_txid": "<string>",
"evm_fund_txid": "<string>",
"evm_htlc_locked_amount": "<string>",
"evm_htlc_sender": "<string>",
"evm_htlc_token": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Create a chain-agnostic EVM-to-Lightning swap.
Flow:
- User funds the HTLCErc20 (via the coordinator; locked to the invoice’s payment hash)
- Once the funding is final, the server pays the invoice; the settled payment reveals the preimage
- Server claims the HTLC with the preimage
If the payment fails the swap becomes ServerWontFund and the user
reclaims their tokens via the collaborative EVM refund endpoint (or
unilaterally after the refund locktime).
curl --request POST \
--url https://api.satora.io/swap/evm/lightning \
--header 'Content-Type: application/json' \
--data '
{
"evm_chain_id": 1,
"token_address": "<string>",
"user_address": "<string>",
"user_id": "<string>",
"amount_in": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"extra_fees": 1,
"gasless": true,
"lightning_address": "<string>",
"lightning_invoice": "<string>",
"lnurl": "<string>",
"referral_code": "<string>",
"target_amount_sats": 123
}
'import requests
url = "https://api.satora.io/swap/evm/lightning"
payload = {
"evm_chain_id": 1,
"token_address": "<string>",
"user_address": "<string>",
"user_id": "<string>",
"amount_in": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"extra_fees": 1,
"gasless": True,
"lightning_address": "<string>",
"lightning_invoice": "<string>",
"lnurl": "<string>",
"referral_code": "<string>",
"target_amount_sats": 123
}
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({
evm_chain_id: 1,
token_address: '<string>',
user_address: '<string>',
user_id: '<string>',
amount_in: '<string>',
bridge_source_chain: '<string>',
bridge_source_token_address: '<string>',
extra_fees: 1,
gasless: true,
lightning_address: '<string>',
lightning_invoice: '<string>',
lnurl: '<string>',
referral_code: '<string>',
target_amount_sats: 123
})
};
fetch('https://api.satora.io/swap/evm/lightning', 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/lightning",
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([
'evm_chain_id' => 1,
'token_address' => '<string>',
'user_address' => '<string>',
'user_id' => '<string>',
'amount_in' => '<string>',
'bridge_source_chain' => '<string>',
'bridge_source_token_address' => '<string>',
'extra_fees' => 1,
'gasless' => true,
'lightning_address' => '<string>',
'lightning_invoice' => '<string>',
'lnurl' => '<string>',
'referral_code' => '<string>',
'target_amount_sats' => 123
]),
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/lightning"
payload := strings.NewReader("{\n \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\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/lightning")
.header("Content-Type", "application/json")
.body("{\n \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.satora.io/swap/evm/lightning")
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 \"evm_chain_id\": 1,\n \"token_address\": \"<string>\",\n \"user_address\": \"<string>\",\n \"user_id\": \"<string>\",\n \"amount_in\": \"<string>\",\n \"bridge_source_chain\": \"<string>\",\n \"bridge_source_token_address\": \"<string>\",\n \"extra_fees\": 1,\n \"gasless\": true,\n \"lightning_address\": \"<string>\",\n \"lightning_invoice\": \"<string>\",\n \"lnurl\": \"<string>\",\n \"referral_code\": \"<string>\",\n \"target_amount_sats\": 123\n}"
response = http.request(request)
puts response.read_body{
"chain": "<string>",
"client_evm_address": "<string>",
"client_lightning_invoice": "<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>",
"invoice_expires_at": 123,
"lightning_payment_settled": true,
"network": "<string>",
"network_fee_sats": 123,
"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_token": {
"chain": "Arkade",
"decimals": 1,
"name": "<string>",
"symbol": "<string>",
"token_id": "btc"
},
"wbtc_address": "<string>",
"bridge_source_chain": "<string>",
"bridge_source_token_address": "<string>",
"evm_claim_txid": "<string>",
"evm_fund_txid": "<string>",
"evm_htlc_locked_amount": "<string>",
"evm_htlc_sender": "<string>",
"evm_htlc_token": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Body
Request to create an EVM-to-Lightning swap.
User sends any ERC-20 token on EVM, receives BTC on a Lightning invoice.
Response
Swap created successfully
EVM → Lightning swap response.
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
ClientRefundedServerFundedis an error state that should never occur
pending, clientfundingseen, clientfunded, clientrefunded, serverfunded, clientredeeming, clientredeemed, serverredeemed, clientfundedserverrefunded, clientrefundedserverfunded, clientrefundedserverrefunded, expired, clientinvalidfunded, clientfundedtoolate, serverwontfund, clientredeemedandclientrefunded Amount actually locked in the EVM HTLC, in base units of the lock
token (evm_htlc_token; the chain's native coin for native locks),
as a decimal string. Read from the lock's SwapCreated event, so it
can differ from evm_expected_sats (DEX slippage). This is the
amount a unilateral refund (refund / refundTo) must pass.
null until the lock is observed.
The sender the EVM lock is keyed under, i.e. the address it refunds
to. From HTLCErc20 v7 / HTLCNative v2 this is the depositor, which
calls the HTLC's refund itself. On older versions it is the
coordinator (evm_coordinator_address), refunded via its refundTo
(the native coordinator's takes no token), except for an HTLCNative v1
lock without a coordinator (zero evm_coordinator_address): that is
the client's own, refunded with the HTLC's refund from this address.
null until the lock is accepted.