Swap

Swap PSBT

Generates a PSBT for performing a swap between tokens in a pool.

POSThttps://api-dev.saturnbtc.io/v0/pool/swap/psbt

Authorization

bearer

Body

application/json

The request body containing the swap details.

poolId*The identifier of the pool

The identifier of the pool.

amountIn*The amount of input token to swap

The amount of input token to swap.

amountOut*The amount of output token expected

The amount of output token expected.

feeRate*The fee rate for the transaction (in sats per byte)

The fee rate for the transaction (in sats per byte).

zeroToOne*A boolean indicating whether to swap from token0 to token1

A boolean indicating whether to swap from token0 to token1.

exactIn*A boolean indicating whether the swap is exact in

A boolean indicating whether the swap is exact in.

pubkey*The public key of the user initiating the request

The public key of the user initiating the request.

address*string

The address of the user. If no secondary address is provided, the primary address must be a taproot address. (P2TR)

secondaryAddressstring

The secondary address of the user. Must be a taproot address. (P2TR)

Response

201400401403500

An object containing the PSBT (in base64 format), the fee, the list of UTXOs to sign, and optionally additional swap details.

Body

application/json

splitRunePsbtSplitRunePsbtResponse (object)

shardPubkeysarray of string

psbt*string

fee*number

utxosToSign*array of UtxoToSign (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api-dev.saturnbtc.io/v0/pool/swap/psbt', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "poolId": "text",
      "amountIn": "text",
      "amountOut": "text",
      "feeRate": 0,
      "zeroToOne": false,
      "exactIn": false,
      "pubkey": "text",
      "address": "text"
    }),
});
const data = await response.json();

Response

201400401403500

{
  "splitRunePsbt": {
    "totalAmount": "text",
    "amountToReceive": "text",
    "psbt": "text",
    "fee": 0,
    "utxosToSign": [
      {
        "address": "text",
        "signingIndexes": [
          0
        ],
        "sigHash": 0,
        "utxo": "text"
      }
    ]
  },
  "shardPubkeys": [
    "text"
  ],
  "psbt": "text",
  "fee": 0,
  "utxosToSign": [
    {
      "address": "text",
      "signingIndexes": [
        0
      ],
      "sigHash": 0,
      "utxo": "text"
    }
  ]
}

Swap Message

Generates a message hash for performing a swap, which the user should sign.

POSThttps://api-dev.saturnbtc.io/v0/pool/swap/message

Authorization

bearer

Body

application/json

The request body containing the swap details.

signedPsbt*The signed PSBT in base64 format

The signed PSBT in base64 format.

splitRunePsbtThe split rune PSBT in base64 format

The split rune PSBT in base64 format.

shardPubkeysarray of string

The pubkeys of the shards. Only applicable in the btc=>rune swap. (zeroToOne=false)

poolId*The identifier of the pool

The identifier of the pool.

amountIn*The amount of input token to swap

The amount of input token to swap.

amountOut*The amount of output token expected

The amount of output token expected.

feeRate*The fee rate for the transaction (in sats per byte)

The fee rate for the transaction (in sats per byte).

zeroToOne*A boolean indicating whether to swap from token0 to token1

A boolean indicating whether to swap from token0 to token1.

exactIn*A boolean indicating whether the swap is exact in

A boolean indicating whether the swap is exact in.

pubkey*The public key of the user initiating the request

The public key of the user initiating the request.

address*string

The address of the user. If no secondary address is provided, the primary address must be a taproot address. (P2TR)

secondaryAddressstring

The secondary address of the user. Must be a taproot address. (P2TR)

Response

201400401403500

A hexadecimal string representing the hash of the message to be signed by the user.

Body

application/json

string

Request

JavaScriptCurlPython

const response = await fetch('https://api-dev.saturnbtc.io/v0/pool/swap/message', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signedPsbt": "text",
      "poolId": "text",
      "amountIn": "text",
      "amountOut": "text",
      "feeRate": 0,
      "zeroToOne": false,
      "exactIn": false,
      "pubkey": "text",
      "address": "text"
    }),
});
const data = await response.json();

Response

201400401403500

text

Swap

Finalizes the swap transaction by submitting the signed message and executing the swap on the network.

POSThttps://api-dev.saturnbtc.io/v0/pool/swap

Authorization

bearer

Body

application/json

The request body containing the swap request and signature.

signedPsbt*The signed PSBT in base64 format

The signed PSBT in base64 format.

splitRunePsbtThe split rune PSBT in base64 format

The split rune PSBT in base64 format.

shardPubkeysarray of string

The pubkeys of the shards. Only applicable in the btc=>rune swap. (zeroToOne=false)

poolId*The identifier of the pool

The identifier of the pool.

amountIn*The amount of input token to swap

The amount of input token to swap.

amountOut*The amount of output token expected

The amount of output token expected.

feeRate*The fee rate for the transaction (in sats per byte)

The fee rate for the transaction (in sats per byte).

zeroToOne*A boolean indicating whether to swap from token0 to token1

A boolean indicating whether to swap from token0 to token1.

exactIn*A boolean indicating whether the swap is exact in

A boolean indicating whether the swap is exact in.

pubkey*The public key of the user initiating the request

The public key of the user initiating the request.

signature*The user's signature of the swap message

The user's signature of the swap message.

address*string

The address of the user. If no secondary address is provided, the primary address must be a taproot address. (P2TR)

secondaryAddressstring

The secondary address of the user. Must be a taproot address. (P2TR)

Response

201400401403500

The Arch Network transaction ID of the swap.

Body

application/json

string

Request

JavaScriptCurlPython

const response = await fetch('https://api-dev.saturnbtc.io/v0/pool/swap', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signedPsbt": "text",
      "poolId": "text",
      "amountIn": "text",
      "amountOut": "text",
      "feeRate": 0,
      "zeroToOne": false,
      "exactIn": false,
      "pubkey": "text",
      "signature": "text",
      "address": "text"
    }),
});
const data = await response.json();

Response

201400401403500

text

How to Apply Slippage to Your Swaps

• Understanding Slippage: Slippage refers to the difference between the expected price of a trade and the price at which the trade is executed.

• Applying Slippage:

  • To apply slippage, request less amountOut for the amountIn you are swapping.

  • For example, to apply a 3% slippage tolerance:

    • Subtract 3% from the amountOut value.

    • Use this adjusted amountOut in your swap request.

Swap Processing:

• Program Behavior:

  • The program checks if you are entitled to receive more tokenOut than specified in the transaction.

  • If Yes:

    • Swap from Rune to BTC: The program will include the additional BTC you should receive in the transaction.

    • Swap from BTC to Rune: The program will hold the extra Rune you should have received. In your next call to the program, it will send you your corresponding portion.