Install OpenOcean Aggregator SDK
You can install the SDK by npm.n
Copy npm i @openocean.finance/openocean-sdk
Or, if you use yarn as your module management tool.
Copy 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.
Copy npm install bignumber.js
npm install web3
How to use the sdk in your project
Copy 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:
Input the amount you want to trade.
Swap. To make this process successful, we recommend using the Open API and Wallet plugin we provide to achieve DeFi trading.
Full vue example
Copy
< 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.
URL: https://open-api.openocean.finance/v3/:chain/tokenList
Parameter Type Example Description The chain name you want to search token
Your request will look like this:
Copy https://open-api.openocean.finance/v3/bsc/tokenList
And your response will look like this:
Copy {
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
Copy 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.
Copy 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.
Copy 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
Copy 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.
Copy 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.
Copy 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.
Copy 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));
}
} ,
Copy
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
Copy
getBalance () {
let chainName = 'bsc' ;
let data =await axios .get ( `https://open-api.openocean.finance/v3/ ${ chainName } /gasPrice` )
}
Copy
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.
Copy 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 ,
});
Copy
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.
URL: https://open-api.openocean.finance/v3/:chain/quote
Parameter Type Example Description platform(openoceanv2,1inch,matcha,paraswap)
0x9029FdFAe9A03135846381c7cE16595C3554e10A
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
you can set it yourself or get it through GetGasPrice
1 equals 1%, ranges 0.01% to100%
For example, you want to pick up the price between OOE and BNB by Axios.
Copy 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:
Copy {
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
Copy
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.
Copy 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.
Copy
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)
}
}
Demo
Please note, API & SDK demo is not available on mobile version.
Check out the link below to our online Demo.
Demo