API V3
Recommend reading the below docs along with using OpenOcean API. GitHub: openocean-api (feature/v3).
Best Practices: Best Practices of Using OpenOcean API (PDF)
Price Quote
Quote the price of a specific trading pair.
GET https://open-api.openocean.finance/v3/:chain/quote
Query Parameters:
| Name | Type | Description |
|---|---|---|
| chain* | string | Chain name or Chain ID (supported chains) |
| inTokenAddress* | string | Input token address |
| outTokenAddress* | string | Output token address |
| amount* | string | Token amount without decimals. e.g. 1.00 ETH → 1, 1.23 USDC → 1.23 |
| gasPrice* | string | Gas price in GWEI without decimals. e.g. 14 GWEI → 14. Use 1 for Sui & Solana. |
| slippage | string | 0.05–50, default 1 |
| disabledDexIds / enabledDexIds | string | Dex index from dexList (enabledDexIds has higher priority) |
Example Request
1 https://open-api.openocean.finance/v3/bsc/quote?gasPrice=3&inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x55d398326f99059ff775485246999027b3197955&amount=5&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801
Response
1 { "code": 200, "data": { "inToken": { ... }, "outToken": { ... }, "inAmount": "5000000000000000000", "outAmount": "3117105805715617378120", "estimatedGas": "480938", "dexes": [ ... ], "path": { ... }, "save": 0.6038, "price_impact": "0.49%" } }
Building Transaction
To obtain a more accurate gas limit, call est_gas from a reliable RPC before submitting. Also try eth.estimateGas() before sendTransaction and renew estimatedGas. Note: estimatedGas is only a reference.
GET https://open-api.openocean.finance/v3/:chain/swap_quote
Query Parameters:
| Name | Type | Description |
|---|---|---|
| chain* | string | Chain name or Chain ID |
| inTokenAddress* | string | Input token address |
| outTokenAddress* | string | Output token address |
| amount* | string | Token amount without decimals |
| gasPrice* | string | Gas price in GWEI without decimals (1 for Sui & Solana) |
| slippage* | number | 0.05–50, e.g. 1 = 1% |
| account* | string | User address (must be approved). If omitted, response has no calldata/transaction body |
| referrer / referrerFee | string / number | Partner EOA; fee 0.01–5 |
| enabledDexIds / disabledDexIds | string | From dexList |
| sender | string | Caller; if set, account = receiver |
| minOutput | number? | Min target tokens without decimals. Base/BNB/ETH |
Example Request
1 https://open-api.openocean.finance/v3/bsc/swap_quote?gasPrice=3&inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x55d398326f99059ff775485246999027b3197955&amount=5&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801
estimatedGas
Use eth_estimateGas * 1.25–1.5 when sending. Update gasPrice to avoid failures. If estimateGas fails, do not submit the tx.
Example with minOutput
1 https://open-api.openocean.finance/v3/1/swap_quote?amount=1&gasPrice=1.9&slippage=1&referrer=0x39041f1b366fe33f9a5a79de5120f2aee2577ebc&account=0xceCfC852f8cE51D92A5A291f6999DEE147bc2169&disableRfq=true&referrerFee=1&inTokenAddress=0xdac17f958d2ee523a2206206994597c13d831ec7&outTokenAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&minOutput=0.98
minOutput
minOutput=0.98 means minimum acceptable swap result 0.98 USDC. If output is less, the trade will not execute.
Get Transaction
GET https://open-api.openocean.finance/v3/:chain/getTransaction
Params: chain*, hash* (transaction hash)
1 https://open-api.openocean.finance/v3/avax/getTransaction?hash=0x57e752d311c347008a5d66286096b62d6a0687834a3df8b0dd06265ff16ee575
Get Tokens Lists
GET https://open-api.openocean.finance/v3/:chain/tokenList
Params: chain*
1 https://open-api.openocean.finance/v3/avax/tokenList
Get Dexes List
GET https://open-api.openocean.finance/v3/:chain/dexList
Params: chain*
1 https://open-api.openocean.finance/v3/avax/dexList
1 { "code": 200, "data": [ { "index": 1, "code": "SushiSwap", "name": "SushiSwap" }, ... ] }
Get Transaction Hash from wallet
GET https://open-api.openocean.finance/v3/:chain/getTxs
Params: chain*, account*, pageSize*
1 https://open-api.openocean.finance/v3/bsc/getTxs?account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&pageSize=10
Get Balance from wallet
GET https://open-api.openocean.finance/v3/:chain/getBalance
Params: chain*, account*, inTokenAddress* (comma-separated token addresses, up to 5)
1 https://open-api.openocean.finance/v1/cross/getBalance?chainId=56&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&inTokenAddress=0x55d398326f99059ff775485246999027b3197955,0x55d398326f99059fF775485246999027B3197955
Create Wallet
GET https://open-api.openocean.finance/v3/:chain/createWallet
Params: chain*
1 https://open-api.openocean.finance/v3/bsc/createWallet
1 { "code": 200, "data": { "address": "string", "privateKey": "string" } }
Get gasPrice
GET https://open-api.openocean.finance/v3/:chain/gasPrice
Params: chain*
1 https://open-api.openocean.finance/v3/bsc/gasPrice
1 { "code": 200, "data": { "standard": 3000000000, "fast": 3000000000, "instant": 3000000000 }, "without_decimals": { "standard": "3", "fast": "3", "instant": "3" } }
For /quote and /swap_quote, gasPrice should be set in GWEI without decimals (e.g. 14 GWEI → 14).
Get Allowance
GET https://open-api.openocean.finance/v3/:chain/allowance
Params: chain*, account*, inTokenAddress*
1 https://open-api.openocean.finance/v3/polygon/allowance?account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&inTokenAddress=0x831753DD7087CaC61aB5644b308642cc1c33Dc13
1 { "code": 200, "data": [ { "symbol": "QUICK", "allowance": "79228162514.26434", "raw": "79228162514264340000000000000" } ] }
GetTxsByReferrer
Retrieves transaction records made through a referrer. Contact us to activate permissions.
GET https://open-api.openocean.finance/v3/getTxsByReferrer
Params: referrer* (string), chain (optional), startId (pagination), pageSize (default 10)
1 https://open-api.openocean.finance/v3/getTxsByReferrer?referrer={Referrer's address}&pageSize=10