OpenOcean
Launch AppGitHubReferral programMedia
Search
⌃K
Links

Aggregator SDK

​

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 web3va

​

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. 1.
    Choose a chain.
  2. 2.
    Choose your wallet.
  3. 3.
    Choose the token pair.
  4. 4.
    Input the amount you want to trade.
  5. 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
})