Quote
URL: https://open-api.openocean.finance/v4/:chain/quote
Token amount with decimals. For example, if 1 USDT is input, use 1000000 (1 USDT * 10^6).
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
âŧNote:
We are deprecating the use of amount
and gasPrice
parameters.
They will be replaced by amountDecimal
and gasPriceDecimal
, respectively.
The previous parameters did not include token decimal, and going forward, all values must be passed with full decimals.
Example:
Copy https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000
Copy https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1
Copy {
"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
Copy 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
Copy 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
Copy 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
Copy 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/reverseQuote
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:
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.
Copy https://open-api.openocean.finance/v4/bsc/reverseQuote?inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=1&gasPrice=1
Copy {
"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/swap
parameter
type
example
description
0x783C08b5F26E3daf8C4681F3bf49844e425b6393
0xD81D45E7635400dDD9c028839e9a9eF479006B28
Token amount with decimals. For example, if 1 USDT is input, use 1000000 (1 USDT * 10^6).
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
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.
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.
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.
Note: enableDexIds
has higher priority compare with disabledDexIds
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 amountDecimal
and gasPriceDecimal
, respectively.
The previous parameters did not include token decimal, and going forward, all values must be passed with full decimals.
Example:
Copy https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000&slippage=1&account=0x2FF855378Cd29f120CDF9d675E959cb5422ec5f2&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB
Copy https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1&slippage=1&account=0x2FF855378Cd29f120CDF9d675E959cb5422ec5f2&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB
Copy {
"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": "0x2FF855378Cd29f120CDF9d675E959cb5422ec5f2",
"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/tokenList
parameter
type
example
description
Example:
Copy https://open-api.openocean.finance/v4/bsc/tokenList
Copy {
"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/dexList
Parameter
type
example
description
Example:
Copy https://open-api.openocean.finance/v3/avax/dexList
Response:
Copy {
"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/gasPrice
parameter
type
example
description
Example:
Copy https://open-api.openocean.finance/v4/bsc/gasPrice
Copy {
"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):
Copy {
"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/getTransaction
parameter
type
example
description
Hash from the OpenOcean contract on the blockchain
Example:
Copy https://open-api.openocean.finance/v4/bsc/getTransaction?hash=0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782
Copy {
"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
}
}
URL: https://open-api.openocean.finance/v4/:chain/decodeInputData
parameter
type
example
description
Example:
Copy https://open-api.openocean.finance/v4/bsc/decodeInputData?data={000000xxxxxx}&method=swap
Copy {
"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"
}
]
}