SDK

https://github.com/openocean-finance/openocean-apigithub.com

Install OpenOcean Aggregator SDK

You can install the SDK by npm.n

npm i @openocean.finance/openocean-sdk

Or, if you use yarn as your module management tool.

yarn add @openocean.finance/openocean-sdk

Or, if you want to build up a jwallet and contract object by yourself, you will need web3 and bignumber.js.

npm install bignumber.js
npm install web3

How to use the sdk in your project

import { OpenoceanSdk } from '@openocean.finance/openocean-sdk'
const openoceanSdk = new OpenoceanSdk()
const { api, swapSdk, config } = openoceanSdk

You can then use all the functions explored by the SDK (API and swapSdk).

Start programing now!

Before you start developing a DeFi trading project, you should understand the industry’s most general DeFi trading workflow. Here is the process we designed for the user to make a transaction:

1. Choose a chain.

2. Choose your wallet.

3. Choose the token pair.

4. Input the amount you want to trade.

5. Swap. To make this process successful, we recommend using the Open API and Wallet plugin we provide to achieve DeFi trading.

Full vue example

<template>
  <div id="app">
    <div style="color:blue">
      <div v-if="chain">chain:{{ chain.chainName }}</div>
      <div v-if="myWallet"> walletName:{{ myWallet.name }}</div>
      <div v-if="myWallet">address:{{ myWallet.address }}</div>
      <div v-if="inToken">
        inToken:{{ inToken.symbol }} Balance:{{ inTokenBalance }}
      </div>
      <div v-if="outToken">
        outToken:{{ outToken.symbol }} Balance:{{ outTokenBalance }}
      </div>
    </div>
    <div>
      <div>
        <h3>ConnectWallet</h3>
        <button @click="connectWallet('eth')" style="margin-right:10px">connectWallet eth</button>
        <button @click="connectWallet('bsc')" style="margin-right:10px">connectWallet bsc</button>
        <button @click="connectWallet('polygon')" style="margin-right:10px">connectWallet polygon</button>
      </div>
      <div>
        <h3>Quote</h3>
        
        
        
        
        
        
        
        <div v-if="this.inToken && this.outToken">
          {{ this.inAmount }}{{ this.inToken.symbol }} swap to {{ outAmount }} {{ this.outToken.symbol }}
        </div>
        <button @click="quote">quote</button>
      </div>
      <div>
        <h3>Swap</h3>
        <button @click="swap">swap</button>
      </div>
      <div>
        <h3>GetBalance</h3>
        <button @click="getBalance">GetBalance</button>
      </div>
    </div>
  </div>
</template>

<script>
import { OpenoceanSdk } from '@openocean.finance/openocean-sdk';
import BigNumber from 'bignumber.js';

import VConsole from 'vconsole';
const vConsole = new VConsole({ theme: 'dark' });


const genSdk = new OpenoceanSdk()
const { api, swapSdk, config } = genSdk

export default {
  name: 'App',
  components: {
  },
  data () {
    return {
      chainName: 'bsc',
      walletName: 'MetaMask',
      inToken: null,
      outToken: null,
      gasPrice: 5,
      inTokenBalance: null,
      outTokenBalance: null,
      inAmount: 1,
      outAmount: null,

      myWallet: null,
      chain: null,
    }
  },


  async created () {

  },
  methods: {
    async getGasPrice () {
      this.gasPrice = await api.getGasPrice({
        chain: this.chainName,
      })
    },
    async getTokenList () {
      let { data } = await api.getTokenList(
        { chain: this.chainName }
      )
      this.inToken = data.find(item => item.symbol == 'USDC')
      this.outToken = data.find(item => item.symbol == 'BUSD')
      this.getBalance()
    },
    async quote () {
      let response = await api.quote({
        chain: this.chainName,
        inTokenAddress: this.inToken.address,
        outTokenAddress: this.outToken.address,
        amount: this.inAmount,
        gasPrice: this.gasPrice
      })
      if (response.code == 200) {
        this.outAmount = new BigNumber(response.data.outAmount).div(10 ** this.outToken.decimals).toFixed(4)
        // alert('outAmount:' + this.outAmount)
      } else {
        alert('Error:' + response.message)
      }
    },
    async swap () {
      if (!this.myWallet) {
        alert('Please connect the wallet.')
        return
      }
      if (this.inTokenBalance < this.inAmount) {
        alert(`${this.inToken.symbol} Insufficient balance.`)
        return
      }
      let { data } = await api.exchange({
        chain: this.chainName
      })
      let allowance = await this.getAllowance(data.approveContract)
      if (new BigNumber(allowance).lt(this.inAmount)) {
        await this.approve(data.approveContract)
        return
      }
      let response = await swapSdk.swapQuote({
        chain: this.chainName,
        inTokenAddress: this.inToken.address,
        outTokenAddress: this.outToken.address,
        amount: this.inAmount,
        gasPrice: this.gasPrice,
        slippage: 1, // 1%
        account: this.myWallet.address,
      })
      if (response.code == 200) {
        swapSdk.swap(response.data)
          .on('error', (error) => {
            debugger
          })
          .on('transactionHash', (hash) => {
            debugger
          })
          .on('receipt', (data) => {
            debugger
            this.getBalance()
          })
          .on('success', (data) => {
            debugger
          })
      } else {
        alert('Error:' + response.message)
      }

    },
    async connectWallet (chainName) {
      try {
        let AllChainNames = config.chains.chainNames
        let AllWalletNames = config.wallets.walletList.map(item => item.key)
        // ["MetaMask","CryptoCom","TrustWallet","OKXWallet","BscWallet","UnstoppableDomains","WalletConnect","CoinbaseWallet","SafePalWallet","BraveWallet","BitKeepWallet","XDEFIWallet","OntoWallet","Coin98Wallet","TokenPocket","CloverWallet","ImTokenWallet","MathWallet","Cyano","OntoMobile","TronLink","Sollet","SolflareWallet","Phantom","TerraStation","GnosisSafeWallet","SlopeWallet","KeplrWallet","BloctoWallet","PetraWallet","MartianWallet","PontemWallet","NearWallet","MyNearWallet","MeteorWallet","SenderWallet"]
        // ["eth","ropsten","rinkeby","bsc","solana","flow","polygon","avax","fantom","arbitrum","terra","xdai","boba","ont","ontevm","metis","tron","heco","okex","optimism","harmony","dot","neo","aurora","cronos","moonriver","bsctest","aptos","near","cosmos","osmosis","iris","kava","celo","klaytn","zksync"]
        if (chainName) this.chainName = chainName
        let data = await swapSdk.connectWallet({
          chainName: this.chainName,
          walletName: this.walletName
        })
        if (data) {
          this.myWallet = data.wallet
          this.chain = data.chain

          this.getTokenList()
          this.getGasPrice()
        }
      } catch (error) {
        this.myWallet = null
        this.chain = null
      }
    },
    async getBalance () {
      if (!this.myWallet) {
        alert('Please connect the wallet.')
        return
      }
      let inBalance = await swapSdk.getBalance({
        account: this.myWallet.address,
        chain: this.chainName,
        tokenAddressOrSymbol: this.inToken.address,
        decimals: this.inToken.decimals,
      })
      this.inTokenBalance = inBalance.short

      let outBalance = await swapSdk.getBalance({
        account: this.myWallet.address,
        chain: this.chainName,
        tokenAddressOrSymbol: this.outToken.address,
        decimals: this.outToken.decimals,
      })
      this.outTokenBalance = outBalance.short
    },
    async getAllowance (approveContract) {

      let allowance = await swapSdk.getAllowance({
        chain: this.chainName,
        decimals: this.inToken.decimals,
        tokenAddress: this.inToken.address,
        approveContract: approveContract,
        account: this.myWallet.address
      })
      return allowance
    },
    async approve (approveContract) {
      let approve = await swapSdk.approve({
        chain: this.chainName,
        tokenAddress: this.inToken.address,
        approveContract: approveContract,
        gasPrice: this.gasPrice,
        decimals: this.inToken.decimals,
        amount: this.inAmount,
      })
      if (!approve.code) {
        approve.on('error', (error) => {
          debugger
        })
          .on('transactionHash', (hash) => {
            debugger
          })
          .on('receipt', (data) => {
            debugger
          })
          .on('success', (data) => {
            debugger
          })
      }
    }
  }


}

</script>

<style></style>

Choose Pair List

You can call the get Token List API to get all the available tokens we have on the blockchain you choose.

• Method: Get

• URL: https://open-api.openocean.finance/v3/:chain/tokenList

• Parameters:

Parameter	Type	Example	Description
chain	string	avax	The chain name you want to search token

Your request will look like this:

https://open-api.openocean.finance/v3/bsc/tokenList

And your response will look like this:

{
    code: 200,
    data:  [
        {
            "id":2377,
            "code":"grove",
            "name":"GroveCoin",
            "address":"0xf33893de6eb6ae9a67442e066ae9abd228f5290c",
            "decimals":8,
            "symbol":"GRV",
            "icon":"https://s3.openocean.finance/token_logos/logos/1681183267288_9630165967657189.png",
            "chain":"bsc",
            "createtime":"2023-04-11T03:21:09.000Z",
            "hot":null,
            "sort":"2023-04-11T03:21:09.000Z",
            "chainId":null,
            "customSymbol":null,
            "customAddress":null,
            "usd":"0.948606"
        },
        ...
    ...
    ]
}

You need to save the token information you need for further operations.

Here is the SDK method for you to get the token list

async getTokenList () {
  let { data } = await api.getTokenList(
    { chain: 'bsc' }
  )
   this.inToken = data.find(item => item.symbol == 'USDC')
   this.outToken = data.find(item => item.symbol == 'BUSD')
}

Connect Wallet

Connect wallet is the first step you need to participate in DeFi trading. For example, you want to connect to MetaMask, so you have to get the MetaMask wallet constructor from OpenOcean wallet.

Please note that multiple browser wallet will have conflict, please only open a purse, (metaMask trustWallet, coin98Wallet) can't open at the same time.

import { MetaMask } from "@openocean.finance/wallet";

const connectWallet( params ) {
    const myWallet = new MetaMask()
    const result = await myWallet.requestConnect(params.chainId); 
    // you can use the requestConnect function to trigger your wallet
}

Or you can trigger the wallet directly by the SDK.

async connectWallet () {
  try {
    let AllChainNames = config.chains.chainNames
    let AllWalletNames = config.wallets.walletList.map(item => item.key)
    // ["MetaMask","CryptoCom","TrustWallet","OKXWallet","BscWallet","UnstoppableDomains","WalletConnect","CoinbaseWallet","SafePalWallet","BraveWallet","BitKeepWallet","XDEFIWallet","OntoWallet","Coin98Wallet","TokenPocket","CloverWallet","ImTokenWallet","MathWallet","Cyano","OntoMobile","TronLink","Sollet","SolflareWallet","Phantom","TerraStation","GnosisSafeWallet","SlopeWallet","KeplrWallet","BloctoWallet","PetraWallet","MartianWallet","PontemWallet","NearWallet","MyNearWallet","MeteorWallet","SenderWallet"]
    // ["eth","ropsten","rinkeby","bsc","solana","flow","polygon","avax","fantom","arbitrum","terra","xdai","boba","ont","ontevm","metis","tron","heco","okex","optimism","harmony","dot","neo","aurora","cronos","moonriver","bsctest","aptos","near","cosmos","osmosis","iris","kava","celo","klaytn","zksync"]
    
    let data = await swapSdk.connectWallet({
      chainName: this.chainName,
      walletName: this.walletName
    })
    if (data) {
      this.myWallet = data.wallet
      // this.chain = data.chain
      // this.getBalance()
    }
  } catch (error) {
    this.myWallet = null
    this.chain = null
  }
}

Run the contract in project

Once you get your wallet connected, you can use Web3.js or ethers. These are tools to create the operable object for the contract, which serves for token approving, balance checking, and swapping.

• Here is the example to init a contract object for you to call the abi in contract

const { sdk } = myWallet;
contract = new sdk.eth.Contract(Contract_abi, inToken_address);
// For example, by running this code, you get the contract to check the inToken's balance

Or, if you want to use ethers.

const { sdk } = myWallet;
const { currentProvider } = sdk;
myEtherWallet = new ethers.providers.Web3Provider(currentProvider);
//transfer your web3 wallet object to ether
signer = myEtherWallet.getSigner();
contract = new ethers.Contract(ContractAddress, contract.abi, signer);

Get Balance

Once your wallet is connected and the address is displayed, you can use the SDK or directly use wallet object to get the balance from your wallet.

• Use wallet API:

const { sdk } = myWallet;
const contract = new sdk.eth.Contract(ERC20_abi, inToken);
balance = await contract.methods.balanceOf(result.address).call();
//Save the result object which can be used here for balance checking.

• Use Open API:

getBalance() {
    if(this.address) {
        let params = {
            chain:'bsc',
            chainId: 56,
            account: your wallet address,
            inTokenAddress:`${previousTokenAddress},${nextTokenAddress}`
            };
        axios.get(`https://open-api.openocean.finance/v3/${params.chain}/getBalance`, { params }).then(res => {
            const { data } = res.data
            const previousBalance = data[0].balance
            const nextBalance = data[1].balance
        }).catch(e => console.log(e));
    }
},

• Use SDK:

    
async getBalance () {
  if (!this.myWallet) {
    alert('Please connect the wallet.')
    return
  }
  let inBalance = await swapSdk.getBalance({
    account: this.myWallet.address,
    chain: this.chainName,
    tokenAddressOrSymbol: this.inToken.address,
    decimals:this.inToken.decimals,
  })
  this.inTokenBalance = inBalance.short

  let outBalance = await swapSdk.getBalance({
    account: this.myWallet.address,
    chain: this.chainName,
    tokenAddressOrSymbol: this.outToken.address,
    decimals:this.outToken.decimals,
  })
  this.outTokenBalance = outBalance.short
}

GetGasPrice

• Use Open API:

getBalance () {
    let chainName='bsc';
    let data=await axios.get(`https://open-api.openocean.finance/v3/${chainName}/gasPrice`)
}

• Use SDK:

async getGasPrice () {
  this.gasPrice = await api.getGasPrice({
    chain: this.chainName,
  })
}

Approve

Approving assets is necessary for DeFi users to authorize 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.

• Use wallet Function:

const gas = await contract.methods.approve(toContract, approveAmount).estimateGas({ from: account });
// get your gas fee
return await contract.methods.approve(toContract, approveAmount).send({
    from: account,
    gasPrice,
    gas,
});

• Use SDK:

async approve (approveContract) {
  let approve = await swapSdk.approve({
    chain: this.chainName,
    tokenAddress: this.inToken.address,
    approveContract: approveContract,
    gasPrice: this.gasPrice,
    decimals: this.inToken.decimals,
    amount: this.inAmount
  })
  if (!approve.code) {
    approve.on('error', (error) => {
      debugger
    })
      .on('transactionHash', (hash) => {
        debugger
      })
      .on('receipt', (data) => {
        debugger
      })
      .on('success', (data) => {
        debugger
      })
  }
}

Quote

You can directly use Open API to quote the token exchange amount.

• Method: Get

• URL: https://open-api.openocean.finance/v3/:chain/quote

• Parameters:

Parameter	Type	Example	Description
chain	string	bsc, avax, fantom	platform(openoceanv2,1inch,matcha,paraswap)
inTokenAddress	string	0x9029FdFAe9A03135846381c7cE16595C3554e10A	sell token address
outTokenAddress	string	0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE	buy token address
amount	number	10	sell amount
gasPrice	number	5	you can set it yourself or get it through GetGasPrice
slippage	number	1	1 equals 1%, ranges 0.01% to100%

For example, you want to pick up the price between OOE and BNB by Axios.

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

If you call it right, you will get a result like this:

 {
    code: 200,
    data: {
        "inToken": {
            "symbol": "AUSD",
            "name": "Avaware USD",
            "address": "0x783C08b5F26E3daf8C4681F3bf49844e425b6393",
            "decimals": 18
        },
        "outToken": {
            "symbol": "EMBR",
            "name": "EmbrToken",
            "address": "0xD81D45E7635400dDD9c028839e9a9eF479006B28",
            "decimals": 18
        },
        "inAmount": "5000000000000000000",
        "outAmount": "126261357830302882735",
        "estimatedGas": "189669",
        "dexes": [
            {
                "dexIndex": 1,
                "dexCode": "SushiSwap",
                "swapAmount": "0"
            },
            ...
        ],
        "path": {
        }
    }
 }

or the api modules in SDK: For example we quote Ont chain

async quote () {
      let response = await api.quote({
        chain: this.chainName,
        inTokenAddress: this.inToken.address,
        outTokenAddress: this.outToken.address,
        amount: this.inAmount,
        gasPrice: this.gasPrice
      })
      if (response.code == 200) {
        this.outAmount = new BigNumber(response.data.outAmount).div(10 ** this.outToken.decimals).toFixed(4)
        // alert('outAmount:' + this.outAmount)
      } else {
        alert('Error:' + response.message)
      }
    }

Swap

Here is the last step! Now you have several ways to swap the token you selected. You can directly use our swap API to trigger the trade, which will not awaken your personal wallet, but you have to provide your private key to the API. You can also use the swap_quote API to get the transaction body from our API server. Here is a case for you to make a transaction on BNB Chain.

The work flow we recommand for API users, is using Swapquote API to get transaction body, then use the wallet to request your transaction on chain.

async swap() {
    if(this.address && this.inAmount > 0) {
        let params = {
        chain: 'bsc',
        inTokenAddress: '0x9029FdFAe9A03135846381c7cE16595C3554e10A',
        outTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
        amount: 5,
        gasPrice: 5,
        slippage:100,
        };
    const res = await axios.get("https://open-api.openocean.finance/v3/bsc/swap_quote?inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x55d398326f99059ff775485246999027b3197955&amount=5&gasPrice=5&slippage=100&account=0x929B44e589AC4dD99c0282614e9a844Ea9483C69");
    if(res) {
        const {estimatedGas,data,gasPrice} = res.data.data;
        const swapParams = {
            from:this.address,
            to:'0x6352a56caadc4f1e25cd6c75970fa768a3304e64', //this is the only contract you can use if you decide to make transaction by our API.
            gas: estimatedGas,
            gasPrice: gasPrice,
            data
            }; 
        const result = await this.myWallet.sdk.eth.sendTransaction(swapParams)
        };
    else {
       return
    },

On the SDK workflow:

For example, we want make a swap on terra chain.

async swap () {
      if (!this.myWallet) {
        alert('Please connect the wallet.')
        return
      }
      if (this.inTokenBalance < this.inAmount) {
        alert(`${this.inToken.symbol} Insufficient balance.`)
        return
      }
      let { data } = await api.exchange({
        chain: this.chainName
      })
      let allowance = await this.getAllowance(data.approveContract)
      if (new BigNumber(allowance).lt(this.inAmount)) {
        await this.approve(data.approveContract)
        return
      }
      let response = await swapSdk.swapQuote({
        chain: this.chainName,
        inTokenAddress: this.inToken.address,
        outTokenAddress: this.outToken.address,
        amount: this.inAmount,
        gasPrice: this.gasPrice,
        slippage: 1, // 1%
        account: this.myWallet.address,
      })
      if (response.code == 200) {
        swapSdk.swap(response.data)
          .on('error', (error) => {
            debugger
          })
          .on('transactionHash', (hash) => {
            debugger
          })
          .on('receipt', (data) => {
            debugger
            this.getBalance()
          })
          .on('success', (data) => {
            debugger
          })
      } else {
        alert('Error:' + response.message)
      }
    }