XO Swap API

This API allows you to: fetch available pairs, get their current rates, and place swaps orders.

Please note that if some requests (excluding requests to the assets endpoints) are made from a server, the end client’s IP address should be forwarded in the Forwarded header.

Steps to execute a swap

🚀

Checkout our Playground to see how the flow would look like!

Pick a pair

In order to prepare your swap “from” an asset into a “to” asset, we need first to identify the pair {FROM_ASSET_TICKET}_{TO_ASSET_TICKER} (e.g BTC_ETH).
Most of the time our tickers will match the tickers you’ll find on other services (like coingecko or coinmarketcap). If you don’t find any quotes for the your pair, it is probably due to a malformed pair id.
You can get all the pairs to list all the pair ids and see what is available to swap.

Get the rates

Fetch a list of rates for the pair. Given a rate, you can calculate the output amount based on the amount and minerFee.

const toAmount = inputAmount * rate.amount.value - rate.minerFee.value;

Create the order

Having defined the amount and address of the “from” and “to” assets you want to swap, you can go ahead and create the order. Remember that the fromAmount needs to be between the rate’s min and max values. Note the orderId part of the response so you can update and fetch your order later.

Send the “from” amount

Send the funds to the swap provider. You do that by creating a normal SEND transaction from the user’s wallet to the payInAddress provided in the order details of the previous step. The transaction would be on the source asset network.

For example if you’re swapping Bitcoin to Ethereum, you need to broadcast a Bitcoin transaction to send the funds to the provider, and the provider will send you an Ethereum transaction with your expected amount.

Update the order

Use the id of the previous (from asset) send transaction to update your order (identified with orderId). This will start the verification process to confirm when the order is fullfilled.

Check the order status

Re-fetch your order with your particular orderId to check its status (it takes some time until the order is confirmed on-chain).

Authorization

All the requests require a header mostly for identifying the source of each order, which is not a private key and can be shared publicly.

# Use your company as the `App-Name`.
App-Name: acme-inc
 
# (Optional) Send your app version for identifying orders.
App-Version: 23.5.5

For the App-Name we ask you to use a kebab-case format. The name itself doesn’t need to be created by use before, but please let us know which one you used before going live.

App-Version is really any string that may be helpful to identify the source of the requests.

Terminology

Pair: A pair is a set of two exchangeable assets.
Asset: A digital currency or token. Keep in mind that not all the assets can be exchanged, make sure that the pair you want to exchange is available.
Rate: The rate is the exchange rate between the two assets in a pair.
Order: A swap order is a request to exchange one asset for another.