Swap

Swap PSBT

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

post

/v0/pool/swap/psbt

Authorizations

Body

poolIdThe identifier of the poolrequired

The identifier of the pool.

Pattern: ^[0-9a-fA-F]+$

amountInThe amount of input token to swaprequired

The amount of input token to swap.

Pattern: ^[1-9][0-9]*$

amountOutThe amount of output token expectedrequired

The amount of output token expected.

Pattern: ^[1-9][0-9]*$

feeRateThe fee rate for the transaction (in sats per byte)required

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

zeroToOneA boolean indicating whether to swap from token0 to token1required

A boolean indicating whether to swap from token0 to token1.

exactInA boolean indicating whether the swap is exact inrequired

A boolean indicating whether the swap is exact in.

splitRunePsbtThe split rune PSBT in base64 format

The split rune PSBT in base64 format.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

runePubkeyThe public key of the rune address of the user initiating the requestrequired

The public key of the rune address of the user initiating the request.

Pattern: ^[0-9a-fA-F]+$

paymentPubkeyThe public key of the bitcoin address of the user initiating the request

The public key of the bitcoin address of the user initiating the request. If the user doesn't have a bitcoin address, the runePubkey will be used

Pattern: ^[0-9a-fA-F]+$

runeAddressThe rune address of the user. It must be a taproot address. (P2TR)required

The rune address of the user. It must be a taproot address. (P2TR). If no bitcoin address is provided, the rune address will be used for bitcoin too.

paymentAddressThe bitcoin address of the user

The bitcoin address of the user.

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api-dev.saturnbtc.io/v0/pool/swap/psbt' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"poolId":"text","amountIn":"text","amountOut":"text","feeRate":1,"zeroToOne":true,"exactIn":true,"runePubkey":"text","runeAddress":"text"}'

201

400

401

403

500

201

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

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

Swap Message

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

post

/v0/pool/swap/message

Authorizations

Body

signedPsbtThe signed PSBT in base64 formatrequired

The signed PSBT in base64 format.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

splitRunePsbtThe split rune PSBT in base64 format

The split rune PSBT in base64 format.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

poolIdThe identifier of the poolrequired

The identifier of the pool.

Pattern: ^[0-9a-fA-F]+$

amountInThe amount of input token to swaprequired

The amount of input token to swap.

Pattern: ^[1-9][0-9]*$

amountOutThe amount of output token expectedrequired

The amount of output token expected.

Pattern: ^[1-9][0-9]*$

feeRateThe fee rate for the transaction (in sats per byte)required

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

zeroToOneA boolean indicating whether to swap from token0 to token1required

A boolean indicating whether to swap from token0 to token1.

exactInA boolean indicating whether the swap is exact inrequired

A boolean indicating whether the swap is exact in.

runePubkeyThe public key of the rune address of the user initiating the requestrequired

The public key of the rune address of the user initiating the request.

Pattern: ^[0-9a-fA-F]+$

paymentPubkeyThe public key of the bitcoin address of the user initiating the request

The public key of the bitcoin address of the user initiating the request. If the user doesn't have a bitcoin address, the runePubkey will be used

Pattern: ^[0-9a-fA-F]+$

runeAddressThe rune address of the user. It must be a taproot address. (P2TR)required

The rune address of the user. It must be a taproot address. (P2TR). If no bitcoin address is provided, the rune address will be used for bitcoin too.

paymentAddressThe bitcoin address of the user

The bitcoin address of the user.

shardPubkeysstring · min: 64 · max: 66[]

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

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api-dev.saturnbtc.io/v0/pool/swap/message' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"signedPsbt":"text","poolId":"text","amountIn":"text","amountOut":"text","feeRate":1,"zeroToOne":true,"exactIn":true,"runePubkey":"text","runeAddress":"text","shardPubkeys":[null]}'

201

400

401

403

500

201

text

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

Swap

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

post

/v0/pool/swap

Authorizations

Body

signedPsbtThe signed PSBT in base64 formatrequired

The signed PSBT in base64 format.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

splitRunePsbtThe split rune PSBT in base64 format

The split rune PSBT in base64 format.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

poolIdThe identifier of the poolrequired

The identifier of the pool.

Pattern: ^[0-9a-fA-F]+$

amountInThe amount of input token to swaprequired

The amount of input token to swap.

Pattern: ^[1-9][0-9]*$

amountOutThe amount of output token expectedrequired

The amount of output token expected.

Pattern: ^[1-9][0-9]*$

feeRateThe fee rate for the transaction (in sats per byte)required

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

zeroToOneA boolean indicating whether to swap from token0 to token1required

A boolean indicating whether to swap from token0 to token1.

exactInA boolean indicating whether the swap is exact inrequired

A boolean indicating whether the swap is exact in.

runePubkeyThe public key of the rune address of the user initiating the requestrequired

The public key of the rune address of the user initiating the request.

Pattern: ^[0-9a-fA-F]+$

paymentPubkeyThe public key of the bitcoin address of the user initiating the request

The public key of the bitcoin address of the user initiating the request. If the user doesn't have a bitcoin address, the runePubkey will be used

Pattern: ^[0-9a-fA-F]+$

signatureThe user's signature of the swap messagerequired

The user's signature of the swap message.

Pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$

runeAddressThe rune address of the user. It must be a taproot address. (P2TR)required

The rune address of the user. It must be a taproot address. (P2TR). If no bitcoin address is provided, the rune address will be used for bitcoin too.

paymentAddressThe bitcoin address of the user

The bitcoin address of the user.

shardPubkeysstring · min: 64 · max: 66[]

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

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api-dev.saturnbtc.io/v0/pool/swap' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"signedPsbt":"text","poolId":"text","amountIn":"text","amountOut":"text","feeRate":1,"zeroToOne":true,"exactIn":true,"runePubkey":"text","signature":"text","runeAddress":"text","shardPubkeys":[null]}'

201

400

401

403

500

201

{
  "archTxId": "text",
  "bitcoinTxIds": [
    "text"
  ]
}

The Arch Network transaction ID of the swap.

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.