API V4

The latest lightning fast API V4

View Github examples for Backend and Frontend.

Quote

  • URL: https://open-api.openocean.finance/v4/:chain/quote

  • Method: get

  • Params:

Name
Type
Description

chain*

string

Chain name or Chain ID (supported chains)

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

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

Chain name or Chain ID (supported chains)

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

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

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 (supported chains)

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 (support chain)

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 (supported chains)

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 gasPrice 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 (supported chains)

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 (supported chains)

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

Last updated