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!

Get the rates

Call GET/v3/pairs/:pairId/rates to get 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;

Place the swap order

Send the fromAmount you want to swap along with the toAmount you expect to receive based on the first step. Remember that the fromAmount needs to be between the rate’s min and max values.

Broadcast the transaction

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.

Then, send the transaction id to update the order by calling PATCH/v3/orders/:orderId. That will start the verification process to confirm when the order is fullfilled.

Check the order status

Call GET/v3/orders/:orderId to check the order status after broadcasting the transaction (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

Name	Description
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.