curl --request POST \
--url https://maker.signet.kaleidoswap.com/v2/swap/reverse \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"invoiceAmount": 1,
"address": "<string>",
"addressSignature": "<string>",
"beneficiary": "<string>",
"bolt12Refund": "<string>",
"claimPublicKey": "<string>",
"from": "<string>",
"pairHash": "<string>",
"pairId": "<string>",
"preimageHash": "<string>",
"to": "<string>",
"webhook": {
"url": "<string>",
"hashSwapId": true,
"status": [
"<string>"
]
}
}
'import requests
url = "https://maker.signet.kaleidoswap.com/v2/swap/reverse"
payload = {
"invoiceAmount": 1,
"address": "<string>",
"addressSignature": "<string>",
"beneficiary": "<string>",
"bolt12Refund": "<string>",
"claimPublicKey": "<string>",
"from": "<string>",
"pairHash": "<string>",
"pairId": "<string>",
"preimageHash": "<string>",
"to": "<string>",
"webhook": {
"url": "<string>",
"hashSwapId": True,
"status": ["<string>"]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
invoiceAmount: 1,
address: '<string>',
addressSignature: '<string>',
beneficiary: '<string>',
bolt12Refund: '<string>',
claimPublicKey: '<string>',
from: '<string>',
pairHash: '<string>',
pairId: '<string>',
preimageHash: '<string>',
to: '<string>',
webhook: {url: '<string>', hashSwapId: true, status: ['<string>']}
})
};
fetch('https://maker.signet.kaleidoswap.com/v2/swap/reverse', 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://maker.signet.kaleidoswap.com/v2/swap/reverse",
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([
'invoiceAmount' => 1,
'address' => '<string>',
'addressSignature' => '<string>',
'beneficiary' => '<string>',
'bolt12Refund' => '<string>',
'claimPublicKey' => '<string>',
'from' => '<string>',
'pairHash' => '<string>',
'pairId' => '<string>',
'preimageHash' => '<string>',
'to' => '<string>',
'webhook' => [
'url' => '<string>',
'hashSwapId' => true,
'status' => [
'<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://maker.signet.kaleidoswap.com/v2/swap/reverse"
payload := strings.NewReader("{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://maker.signet.kaleidoswap.com/v2/swap/reverse")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://maker.signet.kaleidoswap.com/v2/swap/reverse")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"invoice": "<string>",
"lockupAddress": "<string>",
"onchainAmount": 1,
"refundPublicKey": "<string>",
"swapAuth": "<string>",
"swapTree": {
"claimLeaf": {
"output": "<string>",
"version": 1
},
"refundLeaf": {
"output": "<string>",
"version": 1
}
},
"timeoutBlockHeight": 123,
"assetId": "<string>",
"blindingKey": "<string>",
"feeAssetId": "<string>",
"rgb": {
"amount": 1,
"assetId": "<string>",
"blinding": "<string>",
"htlcSat": 1,
"minConfirmations": 1,
"recipientId": "<string>",
"scriptPubkey": "<string>",
"transportEndpoints": [
"<string>"
],
"claimFeeRate": 1,
"cooperativeRefund": "<string>"
}
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}Create a reverse swap
Lightning → on-chain. You send the hash of your preimage and your claim public key; the maker returns a hold invoice locked to that hash, the lockup address it will fund, the swap tree, and its timeout. Verify that the invoice commits to your hash and that the lockup is claimable with your key before paying. The response carries swapAuth, issued once: store it with the swap.
curl --request POST \
--url https://maker.signet.kaleidoswap.com/v2/swap/reverse \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"invoiceAmount": 1,
"address": "<string>",
"addressSignature": "<string>",
"beneficiary": "<string>",
"bolt12Refund": "<string>",
"claimPublicKey": "<string>",
"from": "<string>",
"pairHash": "<string>",
"pairId": "<string>",
"preimageHash": "<string>",
"to": "<string>",
"webhook": {
"url": "<string>",
"hashSwapId": true,
"status": [
"<string>"
]
}
}
'import requests
url = "https://maker.signet.kaleidoswap.com/v2/swap/reverse"
payload = {
"invoiceAmount": 1,
"address": "<string>",
"addressSignature": "<string>",
"beneficiary": "<string>",
"bolt12Refund": "<string>",
"claimPublicKey": "<string>",
"from": "<string>",
"pairHash": "<string>",
"pairId": "<string>",
"preimageHash": "<string>",
"to": "<string>",
"webhook": {
"url": "<string>",
"hashSwapId": True,
"status": ["<string>"]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
invoiceAmount: 1,
address: '<string>',
addressSignature: '<string>',
beneficiary: '<string>',
bolt12Refund: '<string>',
claimPublicKey: '<string>',
from: '<string>',
pairHash: '<string>',
pairId: '<string>',
preimageHash: '<string>',
to: '<string>',
webhook: {url: '<string>', hashSwapId: true, status: ['<string>']}
})
};
fetch('https://maker.signet.kaleidoswap.com/v2/swap/reverse', 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://maker.signet.kaleidoswap.com/v2/swap/reverse",
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([
'invoiceAmount' => 1,
'address' => '<string>',
'addressSignature' => '<string>',
'beneficiary' => '<string>',
'bolt12Refund' => '<string>',
'claimPublicKey' => '<string>',
'from' => '<string>',
'pairHash' => '<string>',
'pairId' => '<string>',
'preimageHash' => '<string>',
'to' => '<string>',
'webhook' => [
'url' => '<string>',
'hashSwapId' => true,
'status' => [
'<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://maker.signet.kaleidoswap.com/v2/swap/reverse"
payload := strings.NewReader("{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://maker.signet.kaleidoswap.com/v2/swap/reverse")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://maker.signet.kaleidoswap.com/v2/swap/reverse")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"invoiceAmount\": 1,\n \"address\": \"<string>\",\n \"addressSignature\": \"<string>\",\n \"beneficiary\": \"<string>\",\n \"bolt12Refund\": \"<string>\",\n \"claimPublicKey\": \"<string>\",\n \"from\": \"<string>\",\n \"pairHash\": \"<string>\",\n \"pairId\": \"<string>\",\n \"preimageHash\": \"<string>\",\n \"to\": \"<string>\",\n \"webhook\": {\n \"url\": \"<string>\",\n \"hashSwapId\": true,\n \"status\": [\n \"<string>\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"invoice": "<string>",
"lockupAddress": "<string>",
"onchainAmount": 1,
"refundPublicKey": "<string>",
"swapAuth": "<string>",
"swapTree": {
"claimLeaf": {
"output": "<string>",
"version": 1
},
"refundLeaf": {
"output": "<string>",
"version": 1
}
},
"timeoutBlockHeight": 123,
"assetId": "<string>",
"blindingKey": "<string>",
"feeAssetId": "<string>",
"rgb": {
"amount": 1,
"assetId": "<string>",
"blinding": "<string>",
"htlcSat": 1,
"minConfirmations": 1,
"recipientId": "<string>",
"scriptPubkey": "<string>",
"transportEndpoints": [
"<string>"
],
"claimFeeRate": 1,
"cooperativeRefund": "<string>"
}
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>",
"details": "<string>"
}Authorizations
Secret organization API key from the partner panel, for servers. Sent on swap creation as Authorization: Bearer <key> to attribute the swap to your organization. Optional; an invalid key is rejected. Never use it in client-side code.
Body
Body of POST /v2/swap/reverse — Boltz-shaped, camelCase.
Amount, in sats, the taker pays via the hold invoice (Boltz
convention: invoiceAmount on Reverse). v0 BTC/BTC is 1:1 so this
is also what the taker receives on-chain.
x >= 0Optional taker-owned Liquid destination for an L-BTC Magic Routing
Hint. Must be paired with addressSignature.
BIP-340 signature by claimPublicKey over SHA256(address UTF-8).
A kaleidoswap: beneficiary handoff, in place of preimageHash +
claimPublicKey. This is how a payer pays someone else without having to take the
recipient's hash and key apart: the recipient's wallet emits one
string, the payer's passes it through. The maker checks the request's
network, expiry, destination layer and asset against the route it
resolves, and refuses to under-deliver what the recipient asked for.
BOLT12: an lnr1… refund (a BOLT12 invoice request not tied to
an offer) the taker's node created for invoiceAmount. When present
the maker answers it — instead of minting a BOLT11 hold invoice —
with a BOLT12 invoice locked to preimageHash, holds it identically,
and delivers it back over the refund's onion-message paths; the
response's invoice is then that lni1…. The refund's amount must
equal invoiceAmount.
The 33-byte compressed claim public key, hex — the key that claims
the maker's lockup. Optional only when beneficiary carries it.
Boltz: Lightning currency symbol (e.g. "BTC"). Combined with to.
Optional pairHash rate-lock: the hash the taker quoted against. Verified against the pair's current rate card when present;
a mismatch is rejected with 400 pair_hash_mismatch.
Trading-pair key, e.g. "BTC/BTC". Optional when from+to are given.
The BOLT11 payment hash — SHA256(preimage), 32 bytes hex. The hold
invoice is locked to this hash; whoever holds the preimage reveals it
on-chain when claiming the maker's lockup. Optional only when beneficiary carries it instead.
Boltz: on-chain currency symbol the taker receives (e.g. "BTC").
Optional HTTPS callback for status changes (Boltz webhook shape).
Show child attributes
Show child attributes
Response
Swap created; hold invoice minted.
POST /v2/swap/reverse response.
BOLT11 hold invoice the taker pays.
Maker's on-chain (or Liquid/Arkade) lockup address.
On-chain amount the maker locks for the taker to claim.
x >= 033-byte compressed maker refund pubkey (hex).
Per-swap taker credential, 32 bytes hex — see
swapAuth.
swapTree returned on every swap creation + status response.
Show child attributes
Show child attributes
Block height (BTC/Liquid) or unix-ts (Arkade) at which the maker's refund branch opens.
null for Liquid; absent for Bitcoin, which has no such field. The maker mints its Liquid HTLC lockups unconfidential on
purpose, so no output blinding key exists to return: treat
lockupAddress as explicit — fund it with an unblinded output
where the taker funds, and build claims against an explicit
prevout where the taker claims.
RGB routes only (to on rgb_l1): how to find and claim the
RGB asset the maker locks in the swap tree's P2TR lockupAddress. onchainAmount is then the asset amount in the contract's units,
not sats.
Show child attributes
Show child attributes
Was this page helpful?