API V4

The latest lightning fast API V4

Quote

URL: https://open-api.openocean.finance/v4/:chain/quote
Method: get
Params:

Name

Type

Description

chain*

string

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

enabledDexIds

string

‼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

with decimals

https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000

without decimals

https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1

Response:

{
    "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/reverseQuote
Method: 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 = USDC
outToken = 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=1

response:

{
    "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
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

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

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)

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)

Note: enableDexIds has higher priority compare with disabledDexIds

disabledDexIds

string (Optional)

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

Example:

request:

with decimals

https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB

without decimals

https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB

response:

{
    "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/tokenList
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Example:

Request:

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

Response:

{
"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
Method: get
Params:

Parameter

type

example

description

chain

string

bsc or 56

Example:

Request:

https://open-api.openocean.finance/v3/avax/dexList

Response:

{
"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
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Example:

Request:

https://open-api.openocean.finance/v4/bsc/gasPrice

Response (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"
 }
}

e.g. 14 GWEI set as 14

Get Transaction

URL: https://open-api.openocean.finance/v4/:chain/getTransaction
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

hash

string

Hash from the OpenOcean contract on the blockchain

Example:

Request:

https://open-api.openocean.finance/v4/bsc/getTransaction?hash=0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782

Response:

{
  "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/decodeInputData
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

data

string

inputData

method

string

swap

function name

Example:

Request:

https://open-api.openocean.finance/v4/bsc/decodeInputData?data={000000xxxxxx}&method=swap

response:

  {
  "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"
}
  ]
}

PreviousGuide NextAPI V3

Last updated 4 days ago

API V4

The latest lightning fast API V4

Quote

URL: https://open-api.openocean.finance/v4/:chain/quote
Method: get
Params:

Name

Type

Description

chain*

string

Chain name or Chain ID ()

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 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 . P.S. enableDexIds has higher priority compared with disabledDexIds

‼Note:

Example:

Request

with decimals

https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000

without decimals

https://open-api.openocean.finance/v4/bsc/quote?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1

Response:

{
    "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)

*Read above before use this endpoint.

URL: https://open-api.openocean.finance/v4/:chain/reverseQuote
Method: 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 = USDC
outToken = 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=1

response:

{
    "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
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Chain name or Chain ID ()

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

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

referrerFee

number (Optional)

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)

Enter the 'index' number of dexs through endpoint to enable the dexs to access.

Note: enableDexIds has higher priority compare with disabledDexIds

disabledDexIds

string (Optional)

Enter the 'index' number of dexs through 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

Example:

request:

with decimals

https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amountDecimals=5000000000000000000&gasPriceDecimals=1000000000&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB

without decimals

https://open-api.openocean.finance/v4/bsc/swap?inTokenAddress=0x55d398326f99059ff775485246999027b3197955&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d&amount=5&gasPrice=1&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&referrer=0xD4eb4cbB1ECbf96a1F0C67D958Ff6fBbB7B037BB

response:

{
    "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%"
    }
}

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
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Chain name or Chain ID ()

Example:

Request:

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

Response:

{
"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
Method: get
Params:

Parameter

type

example

description

chain

string

bsc or 56

chain name or chain ID ()

Example:

Request:

https://open-api.openocean.finance/v3/avax/dexList

Response:

{
"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
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

chain name or chain ID ()

Example:

Request:

https://open-api.openocean.finance/v4/bsc/gasPrice

Response (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"
 }
}

Please be aware that when using/quote and/swapin our API, the should set in GWEI without decimals.

e.g. 14 GWEI set as 14

Get Transaction

URL: https://open-api.openocean.finance/v4/:chain/getTransaction
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Chain name or Chain ID ()

hash

string

Hash from the OpenOcean contract on the blockchain

Example:

Request:

https://open-api.openocean.finance/v4/bsc/getTransaction?hash=0x756b98a89714be5c640ea9922aba12e0c94bc30e5a17e111d1aa40373cc24782

Response:

{
  "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/decodeInputData
Method: get
Params:

parameter

type

example

description

chain

string

bsc or 56

Chain name or Chain ID ()

data

string

inputData

method

string

swap

function name

Example:

Request:

https://open-api.openocean.finance/v4/bsc/decodeInputData?data={000000xxxxxx}&method=swap

response:

  {
  "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"
}
  ]
}

PreviousGuide NextAPI V3

Last updated 4 days ago