API V4
The latest lightning fast API V4
Quote
URL:
https://open-api.openocean.finance/v4/:chain/quoteMethod: get
Params:
inTokenAddress*
string
Input token address
outTokenAddress*
string
Output token address
amountDecimals
string
Token amount with decimals. For example, if 1 USDT is input, use 1000000 (1 USDT * 10^6).
gasPriceDecimals
string
GasPrice with decimals.
slippage
string
Define the acceptable slippage level by inputting a percentage value within the range of 0.05 to 50. e.g. 1% slippage set as 1
default value 1
disabledDexIds
string
Enter the 'index' number of dexs through dexList endpoint to disable single or multiple dexs separated by commas, e.g. disabledDexIds: "2,6,9".
enabledDexIds
string
Enter the 'index' number of dexs through dexList.
P.S. enableDexIds has higher priority compared with disabledDexIds
‼Note:
We are deprecating the use of amount and gasPrice parameters.
They will be replaced by amountDecimals and gasPriceDecimals, respectively.
The previous parameters did not include token decimal, and going forward, all values must be passed with full decimals.
Example:
Request
https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1Response:
{
"code": 200,
"data": {
"inToken": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"decimals": 18,
"symbol": "USDT",
"name": "Tether USD",
"usd": "0.998546",
"volume": 4.99273
},
"outToken": {
"address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
"decimals": 18,
"symbol": "USDC",
"name": "USD Coin",
"usd": "0.999955",
"volume": 4.993697212299812
},
"inAmount": "5000000000000000000",
"outAmount": "4993921938787056372",
"estimatedGas": "129211",
"dexes": [
{
"dexIndex": 0,
"dexCode": "Pancake",
"swapAmount": "4979841669990999203"
},
{
"dexIndex": 1,
"dexCode": "PancakeV2",
"swapAmount": "4974920727654969974"
},
{
"dexIndex": 3,
"dexCode": "Bakery",
"swapAmount": "755767313321589992"
},
...
],
"path": {
"from": "0x55d398326f99059fF775485246999027B3197955",
"to": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"parts": 10,
"routes": [
{
"parts": 10,
"percentage": 100,
"subRoutes": [
{
"from": "0x55d398326f99059fF775485246999027B3197955",
"to": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"parts": 25,
"dexes": [
{
"dex": "PancakeV3",
"id": "0x92b7807bF19b7DDdf89b706143896d05228f3121",
"parts": 25,
"percentage": 100
}
]
}
]
}
]
},
"save": -0.0018,
"price_impact": "0.01%",
"exchange": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
}
}JavaScript Demo
const axios = require('axios');
const chain = 'bsc';
const url = `https://open-api.openocean.finance/v4/${chain}/quote`;
const params = {
inTokenAddress: '0x55d398326f99059ff775485246999027b3197955', // USDT token address
outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',// USDC token address
amount: 1, // without decimals
gasPrice: 3 // without decimals
}
async function main() {
try {
const { data } = await axios.get(url, { params })
if (data?.code === 200) console.log('quote success');
} catch (error) {
console.log(data);
}
}
main();Python Demo
import requests
chain = 'bsc'
url = f'https://open-api.openocean.finance/v4/{chain}/quote'
params = {
'inTokenAddress': '0x55d398326f99059ff775485246999027b3197955',
'outTokenAddress': '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
'amount': 1,
'gasPrice': 3
}
def main():
response = requests.get(url, params=params)
if response.status_code == 200:
data = response.json()
print(data)
else:
print("Error occurred:", response.text)
if __name__ == "__main__":
main()
Go Demo
package main
import (
"fmt"
"net/http"
"encoding/json"
)
func main() {
chain := "bsc"
url := fmt.Sprintf("https://open-api.openocean.finance/v4/%s/quote", chain)
params := map[string]string{
"inTokenAddress": "0x55d398326f99059ff775485246999027b3197955",
"outTokenAddress": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
"amount": "1",
"gasPrice": "3",
}
resp, err := http.Get(url)
if err != nil {
fmt.Println("quote fail")
return
}
defer resp.Body.Close()
var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)
code, ok := data["code"].(float64)
if !ok {
fmt.Println("quote fail")
return
}
if code == 200 {
fmt.Println("quote success")
} else {
fmt.Println("quote fail")
}
}JAVA Demo
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
public class Main {
public static void main(String[] args) {
String chain = "bsc";
String url = "https://open-api.openocean.finance/v4/" + chain + "/quote";
Map<String, Object> params = new HashMap<>();
params.put("inTokenAddress", "0x55d398326f99059ff775485246999027b3197955");
params.put("outTokenAddress", "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d");
params.put("amount", 1);
params.put("gasPrice", 3);
try {
URL apiUrl = new URL(url);
HttpURLConnection connection = (HttpURLConnection) apiUrl.openConnection();
connection.setRequestMethod("GET");
ObjectMapper mapper = new ObjectMapper();
JsonNode data = mapper.readTree(connection.getInputStream());
if (data.has("code") && data.get("code").asInt() == 200) {
System.out.println("quote success");
} else {
System.out.println("quote fail");
}
} catch (IOException e) {
System.out.println("quote fail");
}
}
}ReverseQuote (Optional)
For /reverseQuote, it's a buy flow — you're saying "I want to buy X amount of inToken on the frontend", and we calculate how much outToken you need to sell. In the request url, inToken & outToken reversed to the frontend. To clarify, we suggest using this params as a reference — we use real-time quote price to perform a reverse quote calculation and determine the required intoken amount.
*Read above before use this endpoint.
URL:
https://open-api.openocean.finance/v4/:chain/reverseQuoteMethod: get
Params:
Example:
In the following example, the user on the frontend is trying to swap X USDC to receive 1 BNB. The user inputs “1” as the amount of BNB they want to receive.
On the frontend:
inToken= USDCoutToken= BNB
However, in the /reverseQuote request URL:
inToken= BNB (the token the user wants to receive)outToken= USDC (the token the user will pay)amount= 1 (the target amount of BNB to receive)
This structure allows us to calculate how much USDC is needed to get exactly 1 BNB.
example request:
https://open-api.openocean.finance/v4/bsc/reverseQuote?inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=1&gasPrice=1response:
{
"code": 200,
"data": {
"inToken": {
"address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
"decimals": 18,
"symbol": "BNB",
"name": "Binance Coin",
"usd": "590.65",
"volume": 590.65
},
"outToken": {
"address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
"decimals": 18,
"symbol": "USDC",
"name": "USD Coin",
"usd": "0.999891",
"volume": 590.4153617786928
},
"inAmount": "1000000000000000000",
"outAmount": "590479724068616340527",
"estimatedGas": "174627",
"dexes": [
{
"dexIndex": 0,
"dexCode": "Pancake",
"swapAmount": "105768054842854874312"
},
{
"dexIndex": 1,
"dexCode": "PancakeV2",
"swapAmount": "586740154027055712470"
},
{
"dexIndex": 3,
"dexCode": "Bakery",
"swapAmount": "272826180234288517124"
.........
{
"dexIndex": 62,
"dexCode": "Elk",
"swapAmount": "9154889383782970466"
}
],
"path": {
"from": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
"to": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"parts": 10,
"routes": [
{
"parts": 10,
"percentage": 100,
"subRoutes": [
{
"from":"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
"to": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"parts": 25,
"dexes": [
{
"dex": "PancakeV3",
"id":"0xf2688Fb5B81049DFB7703aDa5e770543770612C4",
"parts": 25,
"percentage": 100,
"fee": 0.0001
}
]
}
]
}
]
},
"save": 0,
"price_impact": "-0.04%",
"reverseAmount": 590548337625246000000
}
}SwapQuote
URL:
https://open-api.openocean.finance/v4/:chain/swapMethod: get
Params:
inTokenAddress
string
0x783C08b5F26E3daf8C4681F3bf49844e425b6393
Input token address
outTokenAddress
string
0xD81D45E7635400dDD9c028839e9a9eF479006B28
Output token address
amountDecimals
string
1000000
Token amount with decimals. For example, if 1 USDT is input, use 1000000 (1 USDT * 10^6).
gasPriceDecimals
string
1000000000
GasPrice with decimals.
slippage
string
1
Define the acceptable slippage level by inputting a percentage value within the range of 0.05 to 50. e.g. 1% slippage set as 1
default value 1
account
string
0xaPbs...D9sh
user's wallet address. *If this param is not included in the request url, the response will only return quotes, without the calldata/transaction body.
referrer
string (Optional)
0xD4eb...37BB
An EOA wallet address used to identify partners and optionally receive a fee from users. If no fee is set up, it serves purely as a tracking tool to help our dev team provide better support and insights.
referrerFee
number (Optional)
1
Specify the percentage of in-token you wish to receive from the transaction, within the range of 0% to 5%, with 1% represented as '1', in the range of 0.01 to 5.
e.g. 1.2% fee set as 1.2
By default, OpenOcean shares 20% of the fee. Please contact us if you wish to modify this rate.
enabledDexIds
string (Optional)
1
Enter the 'index' number of dexs through dexList endpoint to enable the dexs to access.
Note: enableDexIds has higher priority compare with disabledDexIds
disabledDexIds
string (Optional)
1
Enter the 'index' number of dexs through dexList endpoint to disable single or multiple dexs separated by commas, e.g. disabledDexIds: "2,6,9".
sender
string (Optional)
0xaPbs...D9sh
If you want to set the receiving address, you will use the sender field. Sender is the sending address, and account is the receiving address
We are deprecating the use of amount and gasPrice parameters.
They will be replaced by amountDecimals and gasPriceDecimals, respectively.
The previous parameters did not include token decimal, and going forward, all values must be passed with full decimals.
Example:
request:
https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BBhttps://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BBresponse:
{
"code": 200,
"data": {
"inToken": {
"address": "0x55d398326f99059ff775485246999027b3197955",
"decimals": 18,
"symbol": "USDT",
"name": "Tether USD",
"usd": "0.998546",
"volume": 4.99273
},
"outToken": {
"address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
"decimals": 18,
"symbol": "USDC",
"name": "USD Coin",
"usd": "0.999955",
"volume": 4.993697212299812
},
"inAmount": "5000000000000000000",
"outAmount": "4993921938787056372",
"estimatedGas": 516812,
"minOutAmount": "4943982719399185808",
"from": "0x9116780aEf4B376499358fa7dEeC00cCF64fA801",
"to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
"value": "0",
"gasPrice": "1000000000",
"data": "0x90411a32...",
"chainId": 56,
"rfqDeadline": 0,
"gmxFee": 0,
"price_impact": "0.01%"
}
}
The'estimatedGas'in the returned response is only a reference. When sending transactions on-chain, use eth_estimateGas * 1.25 -1.5 as needed. If the ‘estmateGas’ fails, we don't recommend submitting the tx on-chain.
We also recommend updating the 'gasprice' parameter to avoid future failures due to the fluctuations of the on-chain gas price.
Get TokenList
URL:
https://open-api.openocean.finance/v4/:chain/tokenListMethod: get
Params:
Example:
Request:
https://open-api.openocean.finance/v4/bsc/tokenListResponse:
{
"code": 200,
"data": [ {
"id":2737,
"code":"minu",
"name":"Minu",
"address":"0xf48f91df403976060cc05dbbf8a0901b09fdefd4",
"decimals":18,"symbol":"Minu",
"icon":"https://s3.openocean.finance/token_logos/logos/1708980043911_24176891326005867.jpg",
"chain":"bsc","createtime":"2024-02-26T20:40:57.000Z",
"hot":null,"sort":"2024-02-26T20:40:57.000Z",
"chainId":null,
"customSymbol":null,
"customAddress":null,
"usd":"6.38459e-7"}
...
]
}Get Dexes List
URL:
https://open-api.openocean.finance/v4/:chain/dexListMethod: get
Params:
Example:
Request:
https://open-api.openocean.finance/v3/avax/dexListResponse:
{
"code": 200,
"data": [
{
"index": 1,
"code": "SushiSwap",
"name": "SushiSwap"
},
{
"index": 2,
"code": "Pangolin",
"name": "Pangolin"
},
...
] // Response
}Get GasPrice
URL:
https://open-api.openocean.finance/v4/:chain/gasPriceMethod: get
Params:
Example:
Request:
https://open-api.openocean.finance/v4/bsc/gasPriceResponse (eth):
{
"code": 200,
"data": {
"base": 605865956,
"standard": {
"legacyGasPrice": 605865956,
"maxPriorityFeePerGas": 500000000,
"maxFeePerGas": 1366388318,
"waitTimeEstimate": 45000
},
"fast": {
"legacyGasPrice": 605865956,
"maxPriorityFeePerGas": 2000000000,
"maxFeePerGas": 3393491699,
"waitTimeEstimate": 30000
},
"instant": {
"legacyGasPrice": 605865956,
"maxPriorityFeePerGas": 2000000000,
"maxFeePerGas": 3393491699,
"waitTimeEstimate": 30000
},
"low": {
"legacyGasPrice": 605865956,
"maxPriorityFeePerGas": 150400,
"maxFeePerGas": 606016356,
"waitTimeEstimate": 60000
}
},
"without_decimals": {
"base": 0.605865956,
"standard": {
"legacyGasPrice": 0.605865956,
"maxPriorityFeePerGas": 0.5,
"maxFeePerGas": 1.366388318,
"waitTimeEstimate": 0.000045
},
"fast": {
"legacyGasPrice": 0.605865956,
"maxPriorityFeePerGas": 2,
"maxFeePerGas": 3.393491699,
"waitTimeEstimate": 0.00003
},
"instant": {
"legacyGasPrice": 0.605865956,
"maxPriorityFeePerGas": 2,
"maxFeePerGas": 3.393491699,
"waitTimeEstimate": 0.00003
},
"low": {
"legacyGasPrice": 0.605865956,
"maxPriorityFeePerGas": 0.0001504,
"maxFeePerGas": 0.606016356,
"waitTimeEstimate": 0.00006
}
}
}Response (other evm chain):
{
"code": 200,
"data": {
"standard": 1000000000,
"fast": 1000000000,
"instant": 1000000000
},
"without_decimals": {
"standard": "1",
"fast": "1",
"instant": "1"
}
}Get Transaction
URL:
https://open-api.openocean.finance/v4/:chain/getTransactionMethod: get
Params:
hash
string
Hash from the OpenOcean contract on the blockchain
Example:
Request:
https://open-api.openocean.finance/v4/bsc/getTransaction?hash=0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782Response:
{
"code": 200,
"data": {
"id": 1194505,
"tx_id": null,
"block_number": 37495567,
"tx_index": 153,
"address": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
"tx_hash": "0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782",
"tx_hash_url": "https://bscscan.com/tx/0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782",
"sender": "0xB3cbefF0336BaA4863Cb51238bD6C35BDAaB3D84",
"receiver": "0xB3cbefF0336BaA4863Cb51238bD6C35BDAaB3D84",
"in_token_address": "0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5",
"in_token_symbol": "OOE",
"out_token_address": "0x55d398326f99059fF775485246999027B3197955",
"out_token_symbol": "USDT",
"referrer": "0x3487Ef9f9B36547e43268B8f0E2349a226c70b53",
"in_amount": "276240675000000000000",
"out_amount": "5913781972337104042",
"fee": "",
"referrer_fee": "",
"usd_valuation": 5.89409756,
"create_at": "2024-04-02T02:23:04.000Z",
"update_at": "2024-04-02T02:23:04.000Z",
"tx_fee": "0.000238858",
"tx_fee_valuation": "0.13744845",
"in_token_decimals": 18,
"out_token_decimals": 18,
"in_amount_value": "276.240675",
"out_amount_value": "5.913781972337104042",
"tx_profit": "0",
"tx_profit_valuation": "0",
"platform": null,
"status": 1
}
}DecodeInputData
URL:
https://open-api.openocean.finance/v4/:chain/decodeInputDataMethod: get
Params:
data
string
inputData
method
string
swap
function name
Example:
Request:
https://open-api.openocean.finance/v4/bsc/decodeInputData?data={000000xxxxxx}&method=swapresponse:
{
"caller": "0x55877bD7F2EE37BDe55cA4B271A3631f3A7ef121",
"desc": {
"srcToken": "0x8ea5219a16c2dbF1d6335A6aa0c6bd45c50347C5",
"dstToken": "0x55d398326f99059fF775485246999027B3197955",
"srcReceiver": "0xcE07D794FD313a1792E9bdef9912a949DfE99D75",
"dstReceiver": "0xB3cbefF0336BaA4863Cb51238bD6C35BDAaB3D84",
"amount": "276240675000000000000",
"minReturnAmount": "5854644152613733002",
"guaranteedAmount": "5913781972337104042",
"flags": "2",
"referrer": "0x3487Ef9f9B36547e43268B8f0E2349a226c70b53",
"permit": "0x"
},
"calls": [
{
"target": "0",
"gasLimit": "0",
"value": "0",
"data": "0xcac460ee00000000000000003b7c4580ce07d794fd313a1792e9bdef9912a949dfe99d750000000000000000000000008ea5219a16c2dbf1d6335a6aa0c6bd45c50347c50000000000000000000000008e50d726e2ea87a27fa94760d4e65d58c3ad8b44"
},
{
"target": "0",
"gasLimit": "0",
"value": "0",
"data": "0xcac460ee80000000000000003b8b87c08e50d726e2ea87a27fa94760d4e65d58c3ad8b44000000000000000000000000e9e7cea3dedca5984780bafc599bd69add087d5600000000000000000000000055877bd7f2ee37bde55ca4b271a3631f3a7ef121"
},
{
"target": "0",
"gasLimit": "0",
"value": "0",
"data": "0x8a6a1e8500000000000000000000000055d398326f99059ff775485246999027b3197955000000000000000000000000353c1f0bc78fbbc245b3c93ef77b1dcc5b77d2a00000000000000000000000000000000000000000000000005211f95f0c4314aa"
},
{
"target": "0",
"gasLimit": "0",
"value": "0",
"data": "0x9f86542200000000000000000000000055d398326f99059ff775485246999027b319795500000000000000000000000000000001000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000004400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f9900000000000000000000000055d398326f99059ff775485246999027b3197955000000000000000000000000b3cbeff0336baa4863cb51238bd6c35bdaab3d84000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000"
}
]
}Last updated