How to Use Swap API

About Swap API​

Swap API is the recommended way of interacting with Orion Protocol for retail trade. Under the hood, the API performs three tasks:

• Queries prices of ERC20 assets from multiple centralized and decentralized exchanges.

• Aggregates the liquidity from the queried sources to provide the best price possible.

• Returns the trade in a format that can be easily executed using the Web3 library of your choice.

1. Set a Token Allowance

A token allowance is required if you want a third-party to move funds on your behalf. In short, you are allowing them to move your tokens.

In our case, we would like the Orion Exchange contract to trade our ERC20 tokens for us, so we will need to approve an allowance (a certain amount) for this contract to move a certain amount of our ERC20 tokens on our behalf.

When setting the token allowance, make sure to provide enough allowance for the buy or sell amount as well as the gas.

TIP

When setting the token allowance, make sure to provide enough allowance for the buy or sell amount as well as the gas; otherwise, you may receive a 'Gas estimation failed' error.

TODO:

For implementation details, see 'How to set token allowances'

2. Retrieve Swap quote

The Swap API provides information about a swap between two different assets. The information includes the amount of the incoming and outgoing assets, price, and alternative paths.

Here are the examples on how to retrieve swap info.

Golang

package main

import (
    "net/http"
    "io/ioutil"
    "fmt"
)

func main() {
    url := "https://trade-exp.orionprotocol.io/backend/api/v1/swap?assetIn=BNB&assetOut=ORN&amountIn=0.050559"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("accept", "*/*")
    req.Header.Add("accept-language", "en-US,en;q=0.9,ru;q=0.8")
    req.Header.Add("origin", "https://trade.orionprotocol.io")
    req.Header.Add("referer", "https://trade.orionprotocol.io/")
    req.Header.Add("user-agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

JavaScript

const qs = require('qs');

const rq = {
    assetIn: "ORN",
    assetOut: "BTC",
    amountIn: 100
};

const headers = {}
const endpoint = `https://testing.orionprotocol.io/bsc-testnet/backend/api/v1/swap?assetIn=${rq.assetIn}&amountIn=${rq.amountIn}&assetOut=${rq.assetOut}`;

const response = await fetch(endpoint, { headers });
console.log(await response.json());

Response example

{
  "id": "959cf378-4eab-46cd-8044-ca2fd2d3ed1e",
  "assetIn": "BNB",
  "amountIn": 100,
  "assetOut": "BTC",
  "amountOut": 0.08011817,
  "price": 0.00080118,
  "marketAmountOut": 0.08035714,
  "marketAmountIn": null,
  "marketPrice": 0.00080357,
  "minAmountIn": 1e-8,
  "minAmountOut": 1e-8,
  "availableAmountIn": 100,
  "availableAmountOut": null,
  "exchanges": [
    "ORION_POOL"
  ],
  "path": [
    "BNB",
    "ORN",
    "BTC"
  ],
  "isThroughPoolOptimal": true,
  "orderInfo": {
    "assetPair": "BNB-BTC",
    "side": "SELL",
    "amount": 100,
    "safePrice": 0.0008,
    "pessimisticPriceBD": 0.0008
  },
  "executionInfo": "ORION_POOL: BNB -> ORN -> BTC (length = 2): 100.0 BNB -> 0.08011817 BTC, market amount out = 0.08035714 BTC, price = 8.0118E-4 BTC/BNB (order SELL 100.0 @ 0.0008 (safe price 0.0008) on BNB-BTC), available amount in = 100.0 BNB, steps: {[1] BNB -> ORN (BUY on ORN-BNB), pair reserves: {5181.56622453 - 16.096614590896522661}, [2] ORN -> BTC (SELL on ORN-BTC), pair reserves: {273483.91335728 - 5.02119686}}",
  "alternatives": [],
  "addressToErc20Names": null
}

3. Send the Transaction to the Network

// your sender address
const address = "0x..1f"

const receipt = await web3.eth.sendTransaction(quote);