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
Token Generation (
/calculate)When a user initiates a swap request by navigating to the
/calculateendpoint, 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.
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.
Token Usage During Swap Process
The
X-Trade-Session-Idmust 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.
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
User initiates a swap request:
Calls
/calculate, receives a token (X-Trade-Session-Id).
User continues or modifies the swap:
Uses the same token in subsequent requests.
User submits the transaction:
Calls
/submit-tx, and upon success, the token is removed.
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.
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
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.
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.
Last updated