Guide

An overview guide on how to integrate OpenOcean Swap API

OpenOcean-API-Examples/backend/swap-api-demo at main · openocean-finance/OpenOcean-API-ExamplesGitHub

backend

OpenOcean-API-Examples/frontend at main · openocean-finance/OpenOcean-API-ExamplesGitHub

frontend

OpenOcean Swap API Integration Guide

In the following guide, it will introduce how to use this OpenOcean's swap API in the most efficient way.

Swap Overview

The swap function enables users to seamlessly exchange one asset/token for another directly at the best swap rate. The swap API supports for 30+ on EVM and Non-EVM chains, refer the docs of supported chains to check in details.

The current API supports both V3 and V4, with the following example using V4. For detailed parameter settings, please refer to the Swap API documentation before getting started.

Swap Tokens in 7 Steps​

1. (Optional) Get token info

2. Get gasPrice

3. (Optional) Set a token allowance

4. Set token approvals and signature

5. Price quote

6. Get transaction body

7. Send transaction and signature

1. Get Token Info

You can use the get Token List API to to retrieve all available tokens on the selected blockchain. Next, select input token from the chain to swap. Make sure to save the token information for further use.

Example request

import axios from 'axios';

async function tokenList() {
    const { data } = await axios({
        url: `https://open-api.openocean.finance/v4/bsc/tokenList`,
        method: 'GET',
    });

    const tokenList = data?.data;

    return tokenList;
}

Example response

{
    "code": 200,
    "data": [
        {
            "id": 2908,
            "code": "trustswap",
            "name": "Trust Swap",
            "address": "0x94eafeeef7ffa66203fdc9349c54d601472a79dc",
            "decimals": 18,
            "symbol": "SWAP",
            "icon": "https://s3.openocean.finance/token_logos/logos/1727977942735_22094853568022899.png",
            "chain": "bsc",
            "createtime": "2024-10-03T17:52:30.000Z",
            "hot": null,
            "sort": "2024-10-03T17:52:30.000Z",
            "chainId": null,
            "customSymbol": null,
            "customAddress": null,
            "usd": "0.110158"
        },
```
            ]
}

2. Get gasPrice

Example request

async function gasPrice() {
    const { data } = await axios({
        url: `https://open-api.openocean.finance/v4/bsc/gasPrice`,
        method: 'GET',
    });

    const gasPrice = data?.without_decimals?.standard;
    console.log(`bsc gasPrice is ${gasPrice} Gwei`);

    return gasPrice;
}

Example response

{
    "code": 200,
    "data": {
        "standard": 1000000000,
        "fast": 1000000000,
        "instant": 1000000000
    },
    "without_decimals": {
        "standard": 1,
        "fast": 1,
        "instant": 1
    }
}

3. (Optional) Set a Token Allowance

Before proceeding with the swap, you'll need to set a token allowance. This process is to grant a third party to allow access your tokens on your behalf. In this case, you'll need to specify the amount of tokens, and approve for the swap contract to trade your ERC20 tokens.

Example request

async function allowance() {
    const { data } = await axios({
        url: `https://open-api.openocean.finance/v4/bsc/allowance`,
        method: 'GET',
        params: {
            account: '0xB3cbe...', // wallet address
            inTokenAddress: '0x55d398326f99059ff775485246999027b3197955' // usdt token address
        }
    })
 
    const allowance = data?.data[0]?.allowance;
    console.log(`usdt allowance is ${allowance}`);
    return allowance;
}

Example response

{
     code: 200,
     data: [
       {
         symbol: 'USDT',
         allowance: '115792089237316200000000000000000000000000000000000000000000', // without decimals
         raw: '115792089237316200000000000000000000000000000000000000000000000000000000000000' // wei with decimals
       }
     ]
}

4. Token Approve

Approving assets is necessary for Defi users to grant the contract to use their tokens to swap. As with the getBalance method, you can use the wallet method or directly use our SDK to get a specific token approved for trading. You can use the getAllowance API to query the allowance data from our server.

Example:

import { ethers, Contract } from 'ethers';
async function approve() {
    const rpcUrl = 'https://binance.llamarpc.com';
    let provider = new ethers.JsonRpcProvider(rpcUrl);
    const privateKey = ''; //wallet address;
    const inTokenAddress = '0x55d398326f99059ff775485246999027b3197955'; // token address
    const contractAddress = ''; // contract address
    const wallet = new ethers.Wallet(privateKey, provider);
    const contract = await new Contract(inTokenAddress, abi, wallet); // abi, erc20 abi
    
    try {
      await contract.approve(contractAddress, new BigNumber('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff').toFixed(0, 1));
    } catch (error) {
        return error;
    }
    return true;
}

5. Price Quote

In this API, you are able to fetch the price quote for selected token pairs. In the following, we used token pair of OOE/BNB on BNB chain as an example.

Example request

const res = await axios.get( "https://open-api.openocean.finance/v4/bsc/quote",
 {  chain: 'bsc',
    inTokenAddress: '0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5',
    outTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
    amount: 10,
    gasPrice: 1,
    slippage:1,
}).then((res) => {
    const result = res.data
}).catch((err) => {
    throw new Error(err)
})

Example response:

{
    "code": 200,
    "data": {
        "inToken": {
            "address": "0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5",
            "decimals": 18,
            "symbol": "OOE",
            "name": "OpenOcean",
            "usd": "0.00785727",
            "volume": 0.0785727
        },
        "outToken": {
            "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "decimals": 18,
            "symbol": "BNB",
            "name": "Binance Coin",
            "usd": "597.06",
            "volume": 0.07931000455452637
        },
        "inAmount": "10000000000000000000",
        "outAmount": "132834228644569",
        "estimatedGas": "179172",
        "path": {
            "from": "0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5",
            "to": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "parts": 10,
            "routes": [
                {
                    "parts": 10,
                    "percentage": 100,
                    "subRoutes": [
                        {
                            "from": "0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5",
                            "to": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
                            "parts": 25,
                            "dexes": [
                                {
                                    "dex": "OpenOcean",
                                    "id": "0xC6394f580157D7e8ae16f5fa1F8640d292EEDdB2",
                                    "parts": 25,
                                    "percentage": 100
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "save": 0,
        "price_impact": "0.93%"
    }
}

6. Get Transaction Body

You can use swap quote API to get transaction calldata, then submit the transaction on-chain using your wallet.

Example request

async function swap() {
    const params = {
        chain: 'bsc',
        inTokenAddress: '0x55d398326f99059ff775485246999027b3197955', // usdt token address
        outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d', // usdc token address
        slippage: 1, // 1 means 1%
        amount: 1, // without decimals
        gasPrice: 1, // without decimals, get from gasPrice api
        account: '0xB3cbe...' // wallet address
    }
    const { data } = await axios({
        url: `https://open-api.openocean.finance/v4/bsc/swap`,
        method: 'GET',
        params
    })
    console.log(data)
    return data;
}

Example response

{
    code: 200,
    data: {
      inToken: {
         address: '0x55d398326f99059ff775485246999027b3197955',
         decimals: 18,
         symbol: 'USDT',
         name: 'Tether USD',
         usd: '0.997832',
         volume: 0.997832
       },
       outToken: {
         address: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
         decimals: 18,
         symbol: 'USDC',
         name: 'USD Coin',
         usd: '0.998723',
             volume: 0.997356644511025
      },
       inAmount: '1000000000000000000',
       outAmount: '998631897444061017',
       estimatedGas: 519772,
       minOutAmount: '988645578469620406',
        from: '', // wallet address
       to: '0x6352a56caadC4F1E25CD6c75970Fa768A3304e64', // contract address
        value: '0',
       gasPrice: '1000000000',
         data: '0x90411a32...', // input data
        chainId: 56,
       rfqDeadline: 0,
       gmxFee: 0,
       price_impact: '-0.05%'
     }
 }

7. Send transaction

Once your wallet plugin is triggered, it confirms that the sendTransaction function has been successfully called with all parameters set. When our swap gets processed and executed on chain, the transaction hash will be generated.

Example request

async function send_transaction() {
    const rpcUrl = 'https://binance.llamarpc.com';
    const privateKey = ''; // wallet privateKey
    const provider = new ethers.JsonRpcProvider(rpcUrl);
    // get from swap
    const params: any = {
        from: '', // wallet address, get from swap
        to: '', // contract address, get from swap
        gasPrice: '', // wei, get from swap
        data: '', // input data, get from swap
        value: '', // native token amount, get from swap
        gasLimit: '' // get from swap
    }
    const gasLimit = await provider.estimateGas(params);
    params.gasLimit = gasLimit;
    const wallet = new ethers.Wallet(privateKey, provider);
    const { hash } = await wallet.sendTransaction(params);
    return hash;
}