Launch App

Swap

Swap PSBT

post

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

Authorizations
Body
poolIdstring · min: 64 · max: 66Required

The identifier of the pool.

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

The amount of input token to swap.

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

The amount of output token expected.

Pattern: ^[1-9][0-9]*$
feeRateinteger · min: 1Required

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

zeroToOnebooleanRequired

A boolean indicating whether to swap from token0 to token1.

exactInbooleanRequired

A boolean indicating whether the swap is exact in.

splitRunePsbtstringOptional

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})$
runePubkeystring · min: 64 · max: 66Required

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

Pattern: ^[0-9a-fA-F]+$
paymentPubkeystring · min: 64 · max: 66Optional

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]+$
runeAddressstringRequired

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.

paymentAddressstringOptional

The bitcoin address of the user.

Responses
201

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

application/json
post
POST /v0/pool/swap/psbt HTTP/1.1
Host: api-dev.saturnbtc.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "poolId": "text",
  "amountIn": "text",
  "amountOut": "text",
  "feeRate": 1,
  "zeroToOne": true,
  "exactIn": true,
  "splitRunePsbt": "text",
  "runePubkey": "text",
  "paymentPubkey": "text",
  "runeAddress": "text",
  "paymentAddress": "text"
}
{
  "splitRunePsbt": {
    "totalAmount": "text",
    "amountToReceive": "text",
    "psbt": "text",
    "fee": 1,
    "utxosToSign": [
      {
        "address": "text",
        "signingIndexes": [
          1
        ],
        "sigHash": 1,
        "utxo": "text"
      }
    ]
  },
  "shardPubkeys": [
    "text"
  ],
  "psbt": "text",
  "fee": 1,
  "utxosToSign": [
    {
      "address": "text",
      "signingIndexes": [
        1
      ],
      "sigHash": 1,
      "utxo": "text"
    }
  ]
}

Swap Message

post

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

Authorizations
Body
signedPsbtstringRequired

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})$
splitRunePsbtstringOptional

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})$
shardPubkeysstring[]Optional

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

poolIdstring · min: 64 · max: 66Required

The identifier of the pool.

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

The amount of input token to swap.

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

The amount of output token expected.

Pattern: ^[1-9][0-9]*$
feeRateinteger · min: 1Required

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

zeroToOnebooleanRequired

A boolean indicating whether to swap from token0 to token1.

exactInbooleanRequired

A boolean indicating whether the swap is exact in.

runePubkeystring · min: 64 · max: 66Required

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

Pattern: ^[0-9a-fA-F]+$
paymentPubkeystring · min: 64 · max: 66Optional

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]+$
runeAddressstringRequired

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.

paymentAddressstringOptional

The bitcoin address of the user.

Responses
201

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

application/json
Responsestring
post
POST /v0/pool/swap/message HTTP/1.1
Host: api-dev.saturnbtc.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 253

{
  "signedPsbt": "text",
  "splitRunePsbt": "text",
  "shardPubkeys": [
    "text"
  ],
  "poolId": "text",
  "amountIn": "text",
  "amountOut": "text",
  "feeRate": 1,
  "zeroToOne": true,
  "exactIn": true,
  "runePubkey": "text",
  "paymentPubkey": "text",
  "runeAddress": "text",
  "paymentAddress": "text"
}
text

Swap

post

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

Authorizations
Body
signedPsbtstringRequired

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})$
splitRunePsbtstringOptional

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})$
shardPubkeysstring[]Optional

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

poolIdstring · min: 64 · max: 66Required

The identifier of the pool.

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

The amount of input token to swap.

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

The amount of output token expected.

Pattern: ^[1-9][0-9]*$
feeRateinteger · min: 1Required

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

zeroToOnebooleanRequired

A boolean indicating whether to swap from token0 to token1.

exactInbooleanRequired

A boolean indicating whether the swap is exact in.

runePubkeystring · min: 64 · max: 66Required

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

Pattern: ^[0-9a-fA-F]+$
paymentPubkeystring · min: 64 · max: 66Optional

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]+$
signaturestringRequired

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})$
runeAddressstringRequired

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.

paymentAddressstringOptional

The bitcoin address of the user.

Responses
201

The Arch Network transaction ID of the swap.

application/json
post
POST /v0/pool/swap HTTP/1.1
Host: api-dev.saturnbtc.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 272

{
  "signedPsbt": "text",
  "splitRunePsbt": "text",
  "shardPubkeys": [
    "text"
  ],
  "poolId": "text",
  "amountIn": "text",
  "amountOut": "text",
  "feeRate": 1,
  "zeroToOne": true,
  "exactIn": true,
  "runePubkey": "text",
  "paymentPubkey": "text",
  "signature": "text",
  "runeAddress": "text",
  "paymentAddress": "text"
}
{
  "archTxId": "text",
  "bitcoinTxIds": [
    "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.

PreviousRemove LiquidityNextSwap Quotes

Last updated