User Flows and Examples

Fetching a Quote/Route

Learn how to fetch quotes from the OpenOcean API to get the best swap routes and estimated output amounts before executing a trade.

Quote Endpoint

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

Request Parameters

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. e.g. 1 USDT to 1000000 (1 * 10^6)
gasPriceDecimals*	string	GasPrice with decimals
slippage	string	Slippage percentage 0.05-50. e.g. 1% = 1. Default 1
disabledDexIds	string	Dex index from dexList to disable, comma-separated e.g. "2,6,9"
enabledDexIds	string	Dex index from dexList to enable. Has higher priority than disabledDexIds

Deprecation Notice

We are deprecating amount and gasPrice. Use amountDecimals and gasPriceDecimals respectively. All values must be passed with full decimals.

Example Request (with decimals)

Terminal

HTTP

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

Example Request (without decimals, deprecated)

Terminal

HTTP

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

Example Response

Terminal

{}

1 {
2   "code": 200,
3   "data": {
4     "inToken": { 
5       "address": "...", 
6       "decimals": 18, 
7       "symbol": "USDT", 
8       "name": "Tether USD", 
9       "usd": "0.998546", 
10       "volume": 4.99273 
11     },
12     "outToken": { 
13       "address": "...", 
14       "decimals": 18, 
15       "symbol": "USDC", 
16       "name": "USD Coin", 
17       "usd": "0.999955", 
18       "volume": 4.99 
19     },
20     "inAmount": "5000000000000000000",
21     "outAmount": "4993921938787056372",
22     "estimatedGas": "129211",
23     "dexes": [ 
24       { "dexIndex": 0, "dexCode": "Pancake", "swapAmount": "..." } 
25     ],
26     "path": { 
27       "from": "...", 
28       "to": "...", 
29       "parts": 10, 
30       "routes": [ ... ] 
31     },
32     "save": -0.0018,
33     "price_impact": "0.01%",
34     "exchange": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64"
35   }
36 }

price_impact

The price_impact field indicates estimated price deviation. OpenOcean does not enforce execution blocks by price impact. It is the integrator's responsibility to evaluate it and implement checks. We recommend setting a price impact threshold and aborting if exceeded.

Code Examples

JavaScript

Terminal

1 const axios = require('axios');
2 
3 const chain = 'bsc';
4 const url = `https://open-api.openocean.finance/v4/${chain}/quote`;
5 
6 const params = {
7   inTokenAddress: '0x55d398326f99059ff775485246999027b3197955',
8   outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
9   amount: 1,
10   gasPrice: 3
11 };
12 
13 async function main() {
14   try {
15     const { data } = await axios.get(url, { params });
16     if (data?.code === 200) {
17       console.log('Quote success:', data.data);
18     }
19   } catch (error) {
20     console.error('Error:', error);
21   }
22 }
23 
24 main();

Python

Terminal

1 import requests
2 
3 chain = 'bsc'
4 url = f'https://open-api.openocean.finance/v4/{chain}/quote'
5 
6 params = {
7   'inTokenAddress': '0x55d398326f99059ff775485246999027b3197955',
8   'outTokenAddress': '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
9   'amount': 1,
10   'gasPrice': 3
11 }
12 
13 def main():
14   response = requests.get(url, params=params)
15   if response.status_code == 200:
16     data = response.json()
17     print(data)
18   else:
19     print("Error occurred:", response.text)
20 
21 if __name__ == "__main__":
22   main()

Go

Terminal

1 package main
2 
3 import (
4   "fmt"
5   "net/http"
6   "encoding/json"
7 )
8 
9 func main() {
10   chain := "bsc"
11   url := fmt.Sprintf("https://open-api.openocean.finance/v4/%s/quote", chain)
12   params := map[string]string{
13     "inTokenAddress": "0x55d398326f99059ff775485246999027b3197955",
14     "outTokenAddress": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
15     "amount": "1", 
16     "gasPrice": "3",
17   }
18   
19   resp, _ := http.Get(url)
20   defer resp.Body.Close()
21   
22   var data map[string]interface{}
23   json.NewDecoder(resp.Body).Decode(&data)
24   
25   if code, ok := data["code"].(float64); ok && code == 200 {
26     fmt.Println("quote success")
27   }
28 }

Best Practices

1.
Refresh quotes frequently
Prices change constantly. Refresh quotes every 10-15 seconds when displaying to users.
2.
Check price impact
Warn users when price_impact is high (e.g., >1%). This indicates low liquidity or large trade size.
3.
Handle native tokens correctly
Use the special address 0xEeee...EEeE for native tokens (ETH, BNB, etc.) on most chains.
4.
Use decimals parameters
Always use amountDecimals and gasPriceDecimals for accurate values.

Quote vs Swap

The quote endpoint is for price discovery only. To execute a swap, you'll need to call the swap endpoint with a user account address.

Fetching a Quote/Route

Quote Endpoint

Request Parameters

Example Request (with decimals)

Example Request (without decimals, deprecated)

Example Response

Code Examples

JavaScript

Python

Go

Best Practices

Next Steps

Transaction Example

API Reference

1	{
2	"code": 200,
3	"data": {
4	"inToken": {
5	"address": "...",
6	"decimals": 18,
7	"symbol": "USDT",
8	"name": "Tether USD",
9	"usd": "0.998546",
10	"volume": 4.99273
11	},
12	"outToken": {
13	"address": "...",
14	"decimals": 18,
15	"symbol": "USDC",
16	"name": "USD Coin",
17	"usd": "0.999955",
18	"volume": 4.99
19	},
20	"inAmount": "5000000000000000000",
21	"outAmount": "4993921938787056372",
22	"estimatedGas": "129211",
23	"dexes": [
24	{ "dexIndex": 0, "dexCode": "Pancake", "swapAmount": "..." }
25	],
26	"path": {
27	"from": "...",
28	"to": "...",
29	"parts": 10,
30	"routes": [ ... ]
31	},
32	"save": -0.0018,
33	"price_impact": "0.01%",
34	"exchange": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64"
35	}
36	}

1	const axios = require('axios');
2
3	const chain = 'bsc';
4	const url = `https://open-api.openocean.finance/v4/${chain}/quote`;
5
6	const params = {
7	inTokenAddress: '0x55d398326f99059ff775485246999027b3197955',
8	outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
9	amount: 1,
10	gasPrice: 3
11	};
12
13	async function main() {
14	try {
15	const { data } = await axios.get(url, { params });
16	if (data?.code === 200) {
17	console.log('Quote success:', data.data);
18	}
19	} catch (error) {
20	console.error('Error:', error);
21	}
22	}
23
24	main();

1	import requests
2
3	chain = 'bsc'
4	url = f'https://open-api.openocean.finance/v4/{chain}/quote'
5
6	params = {
7	'inTokenAddress': '0x55d398326f99059ff775485246999027b3197955',
8	'outTokenAddress': '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
9	'amount': 1,
10	'gasPrice': 3
11	}
12
13	def main():
14	response = requests.get(url, params=params)
15	if response.status_code == 200:
16	data = response.json()
17	print(data)
18	else:
19	print("Error occurred:", response.text)
20
21	if __name__ == "__main__":
22	main()

1	package main
2
3	import (
4	"fmt"
5	"net/http"
6	"encoding/json"
7	)
8
9	func main() {
10	chain := "bsc"
11	url := fmt.Sprintf("https://open-api.openocean.finance/v4/%s/quote", chain)
12	params := map[string]string{
13	"inTokenAddress": "0x55d398326f99059ff775485246999027b3197955",
14	"outTokenAddress": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
15	"amount": "1",
16	"gasPrice": "3",
17	}
18
19	resp, _ := http.Get(url)
20	defer resp.Body.Close()
21
22	var data map[string]interface{}
23	json.NewDecoder(resp.Body).Decode(&data)
24
25	if code, ok := data["code"].(float64); ok && code == 200 {
26	fmt.Println("quote success")
27	}
28	}