Swap

Overview

The /swap endpoint is the core integration point for utilizing RunesDEX as a swap-action provider. Given the constraints of the Bitcoin chain, particularly the locking of UTXOs during transaction processing, we have implemented a time-lock buffer mechanism. This approach ensures robustness, fresh data availability, and a seamless user experience while swapping assets.

Time-Lock Buffers & Token Mechanism

Due to the nature of Bitcoin’s UTXO model, transactions require specific inputs that must be locked during execution. To facilitate this process efficiently, we temporarily lock UTXOs for 30 seconds, providing users with sufficient time to submit transactions. However, to accommodate users who might change the traded amount or cancel the transaction altogether, we have introduced a token-based mechanism that ensures smooth integration and uninterrupted session flow.

How It Works

1. Token Generation (/calculate)

   • When a user initiates a swap request by navigating to the /calculate endpoint, a session token is generated and returned.

   • This token (X-Trade-Session-Id) is included in response headers and must be preserved by the client.

2. Session Continuity

   • If the user cancels the swap and revisits /calculate, the same token is provided to maintain session integrity.

   • This prevents unnecessary disruptions and ensures a consistent experience.

3. Token Usage During Swap Process

   • The X-Trade-Session-Id must be extracted and included in all subsequent requests related to the swap process.

   • This prevents redundant recalculations, reduces API load, and eliminates "quote expired" errors, improving user experience.

4. Finalizing the Swap (/submit-tx)

   • Upon successful transaction submission, the token must be discarded.

   • This ensures session cleanup and prevents stale session data from affecting future transactions.

Implementation Details

Request Headers

Every request in the swap process should include the following header:

X-Trade-Session-Id: <session-token>

Workflow Summary

1. User initiates a swap request:

   • Calls /calculate, receives a token (X-Trade-Session-Id).

2. User continues or modifies the swap:

   • Uses the same token in subsequent requests.

3. User submits the transaction:

   • Calls /submit-tx, and upon success, the token is removed.

The sequence diagram describing the flow

Benefits

• Improved UX: Eliminates unnecessary quote errors.

• Seamless Session Management: Users can modify or cancel swaps without disrupting the process.

• Efficient UTXO Management: Avoids issues caused by Bitcoin UTXO locking mechanics.

• Prevention of Abuse: Maintains system stability while allowing flexibility for users.

This mechanism ensures that users experience a smooth, efficient, and reliable swap process while interacting with RunesDEX on the Bitcoin chain.

Request parameters	Type	Description
bid_asset	String	The asset being offered in the swap.
bid_amount	Number	The amount of the bid asset being offered.
bid_address	String	The address from which the bid asset is being sent.
bid_address_pubkey	String (optional)	The public key associated with the bid address, if available.
ask_address	String	The address to which the ask asset is being sent.
ask_amount	Number	The amount of the ask asset being requested.
fee_address	String	The address to which any fees are being sent.
fee_address_pubkey	String (optional)	The public key associated with the fee address, if available.
rate	Number	The exchange rate for the swap.
slippage	Number	The allowed slippage percentage for the swap.

Response

`200 OK` Response

A valid response body is structured as follows:

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "pair_id": 42,
  "pair": "$RUNE-BTC",
  "base_address": "bc1abc...",
  "quote_address": "bc1xyz...",
  "base_amount": "0.5",
  "quote_amount": "1000",
  "btc_tx_fee": 10000,
  "psbt": "cHNidP8BAHECAAAAAe1f...",
  "raw_tx": "02000000000101b1...",
  "base_inputs": [0, 1, 2],
  "quote_inputs": [3, 4]
}

For more information regarding the fields returned in the response body, reference the table below. In cases where a non 2xx HTTP status code is returned, reference the Error Response tab of this section to identify root causes.

Field Name	Type	Description
request_id	String	A unique identifier for the liquidity change request.
pair_id	Number	The identifier of the trading pair involved in the liquidity change.
pair	String	The name of the trading pair, typically in the format "base/quote".
base_address	String	The address associated with the base asset in the liquidity change.
quote_address	String	The address associated with the quote asset in the liquidity change.
base_amount	Number	The amount of the base asset involved in the liquidity change.
quote_amount	Number	The amount of the quote asset involved in the liquidity change.
btc_tx_fee	Number	The transaction fee in satoshis for the Bitcoin transaction.
psbt	String	The Partially Signed Bitcoin Transaction (PSBT) in base64 format.
raw_tx	String	The raw Bitcoin transaction in hexadecimal format.
base_inputs	List[Number]	A list of input indices for the base asset in the transaction.
quote_inputs	List[Number]	A list of input indices for the quote asset in the transaction.

Error Response