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

HTTP Code		Message	Sample Error Message	Description
404	1000	PairNotFound	pair not found	Returned when pair cannot be found in DEX
400	1001	BadInput	bad input: rune_amount must be an integer (0..9999999]	bad address bad amount (base/quote) - negative or 0 bid_asset does not match with one of pair assets
400	1009	BadSwapLimits	swap limits are invalid: max=9999, min=3, provided=2	Returned when /calculate returns [min...max] ask amount, but user supplied any number outside of this range.
403	1002	PairSuspended	pair is suspended	Returned when pair is suspended for swaps, add/rm liquidity
401	1005	PartnerNotActive	partner is not active	Returned when partner's key is deactivated
400	1006	BadNetworkFee	netwrok fee is too small	Returned when the network fee is too small
403	1008	TooManyPendingTxs	too many pending transactions	Returned when users do too many transactions on the same pool and too many of them are in "pending" state (<2 confirmations)
400	1010	NotEnoughBalance	not enough balance: Address='abcde' doesn't have enough rune (ISTHISWORKING): available=333, required=444	Returned when DEX was not able to find enough UTXOs to cover the swap
500	500	InternalError	internal error: a third party API is unavailable	Typically DEX bugs, users should not see/handle them
400	1016	IllegalTrade	illegal trade: calculated ask amount is zero	Returned when the pool state is rendered to be invalid after a given swap
400	1017	BadBidAmount	bad bid amount: bid_amount=0 must be positive int number	Returned when user supplied bad bid amount
400	1018	SatTooSmall	this swap is illegal because of too small sat amount=799, expected at least=800	Users cannot create swap transactions which transfer less than 800 sat in either direction
400	1007	PriceImpactTooHigh	price impact is too high: actual=0.6, expected=0.5	Users cannot make swaps with volume more than 50% of the pool balance