Integration Guide

How to integrate the Orion Protocol SDK into your UI.

UI

Let's consider integration of Orion Protocol with your UI.

1. Initialization

Orion Protocol's SDK operate with OrionUnit — a chain-in-environment abstraction such as "Ethereum-in-production", "bsc-in-production", "fantom-in-testing", etc.

import { OrionUnit } from "@orionprotocol/sdk";
const orionUnit = new OrionUnit("bsc", "production"); // eth, bsc, ftm available

2. Signer accessing

When your UI connects to a wallet (through Metamask or Wallet Connect, for example), you should get access to a signer. The signer is the API's entity that allows to sign transactions.

Currently, the SDK requires the Ethers.js library. Possibly, in the future, we will consider adding a common signer interface.

For example, you can access the signer through Metamask:

import detectEthereumProvider from "@metamask/detect-provider";
import { BaseProvider } from "@metamask/providers";
import { ethers } from "ethers";

const startApp = async (provider: BaseProvider) => {
  const web3Provider = new ethers.providers.Web3Provider(provider);
  await web3Provider.ready;
  const signer = web3Provider.getSigner(); // ready to go
};

detectEthereumProvider().then((provider) => {
  if (provider) {
    startApp(provider as BaseProvider);
  } else {
    console.log("Please install MetaMask!");
  }
});

3. Getting a list of trading pairs

import { simpleFetch } from "@orionprotocol/sdk";
const pairsList = await simpleFetch(orionUnit.orionAggregator.getPairsList)();

// Response example
// ['ORN-USDT', 'BNB-ORN', 'FTM-ORN', 'ETH-ORN', ...]

That's all. You can easily get tradeable assets this way:

const tradableAssets = pairs.reduce((acc, pair) => {
  const [base, quote] = pair.split("-");
  acc.push(base, quote);
  return acc;
}, []);
const uniqueTradableAssets = [...new Set(tradableAssets).values()];
const sortedTradableAssets = uniqueTradableAssets.sort((a, b) => {
  if (a < b) return -1;
  if (a > b) return 1;
  return 0;
}

4. Getting fee asset info

Orion Protocol charges you only with available fee assets. You can get the fee assets list:

import { simpleFetch } from "@orionprotocol/sdk";
const feeAssets = await simpleFetch(orionUnit.orionBlockchain.getTokensFee)();

// Response example:
// {
//   "ORN": "0.2",
//   "BNB": "0.3",
//   "USDT": "0.3"
// }

• If you choose ORN as fee asset, you will pay 0.2% of your order's amount (quoted in ORN).

• If you choose BNB as fee asset, you will pay 0.3% of your order's amount (quoted in BNB).

• If you choose USDT as fee asset, you will pay 0.3% of your order's amount (quoted in USDT).

5. Get swap info

You can swap one asset for another in two ways:

1. You can specify how much funds you want to spend (exact spend)

2. You can specify how much funds you want to receive (exact receive)

Each time when the user changes form inputs, you should get the swap info:

const {
  swapInfo, // Contains information about swap (e.g. how much you will receive, how much you will spend, price)
  fee, // Contains fee information. You can display it in UI.
  route, // "pool" or "aggregator"
} = await orionUnit.exchange.getSwapInfo({
  type: "exactSpend", // Also "exactReceive" is available
  assetIn: "ORN", // What user selected as input asset
  assetOut: "USDT", // What user selected as output asset
  feeAsset: "ORN", // What user selected as fee asset (that we got from previous step)
  amount: 23.89045345, // How much user want to spend (because we specified "exactSpend" in "type" param)
  options: {
    instantSettlement: true, // Set true to ensure that funds can be instantly transferred to wallet (otherwise, there is a possibility of receiving funds to the balance of the exchange contract)
    poolOnly: false, // Please read note below
  },
});

When you call the getSwapInfo method, the SDK internally makes a request to service, deciding the execution route from either of the two: "pool" or "aggregator".

When you get "pool", that means you just need to call the method on the exchange contract to make the swap (DEX only swap execution). When you get "aggregator", that means you need to send the order to the aggregator and wait for execution (the aggregator can execute order on CEX's and DEX's)

Orion Protocol requires a method to transfer your funds from you. When you swap tokens (not coins on their native chains i.e. ETH on Ethereum for example), we use "approve" to reach this goal. But approve is not always possible. For example, if you want to swap BNB for ORN, you can't approve BNB because BNB is not a token. BNB is the native currency of Binance Smart Chain. So, in a case when the native currency is the desired asset AND the route is "aggregator", you should deposit funds (native cryptocurrency) to the exchange contract.

If you don't want to deposit funds to the exchange contract, you can set "poolOnly" option to true.

6. Swap

The SDK has multiple ways to make a swap:

1. Call orionUnit.exchange.swapMarket. This is the simplest way to swap. All inclusive method. See description
2. Call orionUnit.orionAggregator.placeOrder. This is a method used to place an order to the aggregator. More verbose. See description
3. Call the method swapThroughOrionPool on the exchange contract. This is a method to swap tokens through pool. See code example