Swap

Swap PSBT

post

https://api-dev.saturnbtc.iohttps://api.saturnbtc.io

/v0/pool/swap/psbt

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

Authorizations

bearer

x-api-keystringRequired

Body

application/json

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

400

Pool error

application/json

401

Unauthorized

application/json

403

User not found

application/json

500

Internal Server Error

application/json

post

/v0/pool/swap/psbt

HTTPcURLJavaScriptPython

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"
      }
    ]
  },
  "mergeUtxoPsbt": {
    "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

https://api-dev.saturnbtc.iohttps://api.saturnbtc.io

/v0/pool/swap/message

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

Authorizations

bearer

x-api-keystringRequired

Body

application/json

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

mergeUtxoPsbtstringOptional

The merge UTXO 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)

recentBlockhashstringRequired

The recent blockhash of the transaction.

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

400

Pool error

application/json

401

Unauthorized

application/json

403

User not found

application/json

500

Internal Server Error

application/json

post

/v0/pool/swap/message

HTTPcURLJavaScriptPython

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: 301

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

text

Swap

post

https://api-dev.saturnbtc.iohttps://api.saturnbtc.io

/v0/pool/swap

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

Authorizations

bearer

x-api-keystringRequired

Body

application/json

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

mergeUtxoPsbtstringOptional

The merge UTXO 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)

recentBlockhashstringRequired

The recent blockhash of the transaction.

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

400

Pool error

application/json

401

Unauthorized

application/json

403

User not found

application/json

500

Internal Server Error

application/json

post

/v0/pool/swap

HTTPcURLJavaScriptPython

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: 320

{
  "signedPsbt": "text",
  "splitRunePsbt": "text",
  "mergeUtxoPsbt": "text",
  "shardPubkeys": [
    "text"
  ],
  "recentBlockhash": "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.