API V3

https://github.com/openocean-finance/openocean-api/tree/feature/v3github.com

Note: If you are using our API for arbitrage, please reach out us directly to Telegram or Discord for tailored services.

65KB

Best Practices of Using OpenOcean API.pdf

PDF

Open

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

Please set token amount without decimals. e.g. 1.00 ETH set as 1

1.23 USDC set as 1.23

gasPrice*

string

Please set the gas price in GWEI without decimals e.g. 14 GWEI set as 14

*Note: Please set 1 as the default gasPrice on Sui & Solana.

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

https://open-api.openocean.finance/v3/bsc/quote?gasPrice=3&inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x55d398326f99059ff775485246999027b3197955&amount=5&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801

Response:

{
    "code": 200,
    "data": {
        "inToken": {
            "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "decimals": 18,
            "symbol": "BNB",
            "name": "Binance Coin",
            "usd": "620.35",
            "volume": 3101.75
        },
        "outToken": {
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "decimals": 18,
            "symbol": "USDT",
            "name": "Tether USD",
            "usd": "1",
            "volume": 3117.1058057156174
        },
        "inAmount": "5000000000000000000",
        "outAmount": "3117105805715617378120",
        "estimatedGas": "480938",
        "dexes": [
            {
                "dexIndex": 0,
                "dexCode": "Pancake",
                "swapAmount": "3000604244229350523854"
            },
            {
                "dexIndex": 1,
                "dexCode": "PancakeV2",
                "swapAmount": "3099231525136725819510"
            },
           .......
            
        ],
        "path": {
            "from": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "to": "0x55d398326f99059fF775485246999027B3197955",
            "parts": 10,
            "routes": [
                {
                    "parts": 5,
                    "percentage": 50,
                    "subRoutes": [
                        {
                            "from": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
                            "to": "0x55d398326f99059fF775485246999027B3197955",
                            "parts": 25,
                            "dexes": [
                                {
                                    "dex": "UniswapV3",
                                    "id": "0x47a90A2d92A8367A91EfA1906bFc8c1E05bf10c4",
                                    "parts": 25,
                                    "percentage": 100
                                }
                            ]
                        }
                    ]
                },
                {
                    "parts": 5,
                    "percentage": 50,
                    "subRoutes": [
                        {
                            "from": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
                            "to": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
                            "parts": 25,
                            "dexes": [
                                {
                                    "dex": "PancakeV3",
                                    "id": "0xf2688Fb5B81049DFB7703aDa5e770543770612C4",
                                    "parts": 25,
                                    "percentage": 100
                                }
                            ]
                        },
                        {
                            "from": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
                            "to": "0x55d398326f99059fF775485246999027B3197955",
                            "parts": 25,
                            "dexes": [
                                {
                                    "dex": "ThenaFusion",
                                    "id": "0x1b9a1120a17617D8eC4dC80B921A9A1C50Caef7d",
                                    "parts": 25,
                                    "percentage": 100
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "save": 0.6038,
        "price_impact": "0.49%"
    }
}

Building Transaction

To obtain a more accurate gas limit, we suggest calling the ‘’est_gas‘’ function from a reliable RPC before submitting the transaction on chain.
Also, try to call 'eth.estamiteGas()' before sendTransaction and renew the estimatedGas to ensure the transaction can be done successfully.

Note that, 'estimatedGas' is only a reference provided, please adjust by your need.

Building Transaction

GET https://open-api.openocean.finance/v3/:chain/swap_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

disabledDexIds

string?

ID of dexes could be access through dexList endpoint

slippage*

number

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

gasPrice*

string

Please set the gas price in GWEI without decimals e.g. 14 GWEI set as 14

*Note: Please set 1 as the default gasPrice on Sui & Solana.

amount*

string

Please set token amount without decimals. e.g. 1.00 ETH set as 1

1.23 USDC set as 1.23

account*

string

User's address, please ensure that it has been approved to spend the necessary amount of inTokenAddress. *If this param is not included in the request url, the response will only return quotes, without the calldata/transaction body.

referrer

string?

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?

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

Enter the 'index' number of dexs through dexList endpoint to enable the dexs to access. P.S. enableDexIds has higher priority compare with disabledDexIds

sender

string

The caller address.

Token Delivery Logic

If a sender address is specified, the sender address will be set as sender(caller), and account address will be set as receiver.

If no sender address is specified, the account address will automatically be set as the sender(caller) and receiver.

minOutput

number?

The minimum amount of target tokens the user expects to receive.

minOutput without decimals.

For example, if USDT is 9.8(minOutput=9.8).

Support chain:Base/BNB/ETH

Example:

Request

https://open-api.openocean.finance/v3/bsc/swap_quote?gasPrice=3&inTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&outTokenAddress=0x55d398326f99059ff775485246999027b3197955&amount=5&slippage=1&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801

Response:

{
    "code": 200,
    "data": {
        "inToken": {
            "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "decimals": 18,
            "symbol": "BNB",
            "name": "Binance Coin",
            "usd": "624.01",
            "volume": 3120.05
        },
        "outToken": {
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "decimals": 18,
            "symbol": "USDT",
            "name": "Tether USD",
            "usd": "1",
            "volume": 3118.8616323466294
        },
        "inAmount": "5000000000000000000",
        "outAmount": "3118861632346629673681",
        "estimatedGas": 699604,
        "minOutAmount": "3087673016023163376944",
        "from": "0x929b44E589Ac4dD99c0282614E9a844EA9483AAA",
        "to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
        "value": "5000000000000000000",
        "gasPrice": "3000000000",
        "data": "0x90411a3200000000000000000000000055877bd7f2ee37bde55ca4b271a3631f3a7ef121000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee00000000000000000000000055d398326f99059ff775485246999027b319795500000000000000000000000055877bd7f2ee37bde55ca4b271a3631f3a7ef121000000000000000000000000929b44e589ac4dd99c0282614e9a844ea9483aaa0000000000000000000000000000000000000000000000004563918244f400000000000000000000000000000000000000000000000000a7621228e15ba895300000000000000000000000000000000000000000000000a912e6622e9fd112d1000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000420000000000000000000000000bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004563918244f4000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004d0e30db00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000104e5b07cdb00000000000000000000000047a90a2d92a8367a91efa1906bfc8c1e05bf10c400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004563918244f4000000000000000000000000000055877bd7f2ee37bde55ca4b271a3631f3a7ef12100000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000002ebb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c00006455d398326f99059ff775485246999027b319795500000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000648a6a1e8500000000000000000000000055d398326f99059ff775485246999027b3197955000000000000000000000000353c1f0bc78fbbc245b3c93ef77b1dcc5b77d2a00000000000000000000000000000000000000000000000a912e6622e9fd112d100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001a49f86542200000000000000000000000055d398326f99059ff775485246999027b319795500000000000000000000000000000001000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000004400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000064d1660f9900000000000000000000000055d398326f99059ff775485246999027b3197955000000000000000000000000929b44e589ac4dd99c0282614e9a844ea9483aaa00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "chainId": 56,
        "rfqDeadline": 0,
        "price_impact": "-0.04%"
    }
}

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.

Example(Params "minOutput")

Request

without decimals

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

response:

{
    "code": 200,
    "data": {
        "inToken": {
            "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
            "decimals": 6,
            "symbol": "USDT",
            "name": "Tether USD",
            "usd": "1",
            "volume": 1
        },
        "outToken": {
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "decimals": 6,
            "symbol": "USDC",
            "name": "USD Coin",
            "usd": "0.999802",
            "volume": 0.98987396614
        },
        "inAmount": "1000000",
        "outAmount": "990070",
        "estimatedGas": 219290,
        "minOutAmount": "980000",
        "from": "0xceCfC852f8cE51D92A5A291f6999DEE147bc2169",
        "to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
        "value": "0",
        "gasPrice": "1900000000",
        "data": "0x...................."
        "chainId": 1,
        "rfqDeadline": 0,
        "gmxFee": 0,
        "blockNumber": 23375193,
        "price_impact": "-1.02%"
    }
}

minOutput=0.98 = the minimum acceptable swap result for the user. If the output is less than 0.98 USDC, the trade will not execute.

Building Transaction

To obtain a more accurate gas limit, we suggest calling the ‘’est_gas‘’ function from a reliable RPC before submitting the transaction on chain.
Also, try to call 'eth.estamiteGas()' before sendTransaction and renew the estimatedGas to ensure the transaction can be done successfully.

Note that, 'estimatedGas' is only a reference provided, please adjust by your need.

Get Transaction

GET https://open-api.openocean.finance/v3/:chain/getTransaction

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

hash*

string

transaction hash

Example:

Request

https://open-api.openocean.finance/v3/avax/getTransaction?hash=0x57e752d311c347008a5d66286096b62d6a0687834a3df8b0dd06265ff16ee575

Response:

{
"code": 200,
"data": {
    "id": 25144,
    "tx_id": null,
    "block_number": 12091885,
    "tx_index": 8,
    "address": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
    "tx_hash": "0x57e752d311c347008a5d66286096b62d6a0687834a3df8b0dd06265ff16ee575",
    "sender": "0x7fFadA80929a732f93D648D92cc4E052e2b9C4Aa",
    "in_token_address": "0x0000000000000000000000000000000000000000",
    "in_token_symbol": "AVAX",
    "out_token_address": "0xA7D7079b0FEaD91F3e65f86E8915Cb59c1a4C664",
    "out_token_symbol": "USDC.e",
    "referrer": "0x40603469C577B1Db3D401155901A276F604436f4",
    "in_amount": "1400000000000000000",
    "out_amount": "97659580",
    "fee": "",
    "referrer_fee": "",
    "usd_valuation": 97.38,
    "create_at": "2022-03-14T08:39:18.000Z",
    "update_at": "2022-03-14T08:39:18.000Z",
    "tx_fee": "0.010181825",
    "tx_fee_valuation": "0.72993503",
    "in_token_decimals": 18,
    "out_token_decimals": 6,
    "in_amount_value": "1.4",
    "out_amount_value": "97.65958"
   }
}

Get Tokens Lists

GET https://open-api.openocean.finance/v3/:chain/tokenList

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

Example:

Request

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

Response:

{
"code": 200,
"data": [
    {
        "id": 1619,
        "code": "avaware-usd",
        "name": "Avaware USD",
        "address": "0x783C08b5F26E3daf8C4681F3bf49844e425b6393",
        "decimals": 18,
        "symbol": "AUSD",
        "icon": "https://cloudstorage.openocean.finance/images/1646208600388_8016544631355003.png",
        "chain": "avax",
        "createtime": "2022-03-02T08:10:07.000Z",
        "hot": null,
        "sort": "2022-03-02T08:10:07.000Z",
        "chainId": null
    },
    ...
]
}

Get Dexes List

GET https://open-api.openocean.finance/v3/:chain/dexList

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

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 Transaction Hash from wallet

Below is the api to get the transaction hashes based on specific account.

GET https://open-api.openocean.finance/v3/:chain/getTxs

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

account*

string

user's wallet address

pageSize*

number

The amount of tx hash you wish to receive

Example:

Request:

https://open-api.openocean.finance/v3/bsc/getTxs?account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&pageSize=10

Response:

{
  {
    "code": 200,
    "data": [
        {
            "account": "0x9116780aEf4B376499358fa7dEeC00cCF64fA801",
            "block": 16017430,
            "inAmount": "1",
            "inToken": "USDT",
            "outAmount": "0.098904137685202557",
            "outToken": "USDT",
            "txFee": "0.00070697",
            "txFeeValuation": "0.26521273",
            "txHash": "0x9302b5d877b82ab27cfad776311294bb55f539f676385ce0470891063a3ee398",
            "inTokenAddress": "0x55d398326f99059ff775485246999027b3197955",
            "outTokenAddress": "0x55d398326f99059fF775485246999027B3197955",
            "tradeTime": "2022-03-13T07:42:19.000Z"
        },
        ...
    ]
    }

Get Balance from wallet

GET https://open-api.openocean.finance/v3/:chain/getBalance

Query Parameters

Name

Type

Description

inTokenAddress*

string

Please enter the token addresses, separating each address with a comma. You may enter up to five tokens.

account*

string

user's wallet address

chain*

string

Chain name or Chain ID (supported chains)

Example:

Request

https://open-api.openocean.finance/v1/cross/getBalance?chainId=56&account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&inTokenAddress=0x55d398326f99059ff775485246999027b3197955,0x55d398326f99059fF775485246999027B3197955

Response:

{
    code: 200, 
    data: [
        {
            "symbol": "USDT",
            "tokenAddress": "0x55d398326f99059ff775485246999027b3197955",
            "balance": 0,
            "raw": 0
        },
        {
            "symbol": "USDT",
            "tokenAddress": "0x55d398326f99059fF775485246999027B3197955",
            "balance": 0,
            "raw": 0
        }
    ]
}

Create Wallet

GET https://open-api.openocean.finance/v3/:chain/createWallet

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

Example:

Request

https://open-api.openocean.finance/v3/bsc/createWallet

Response:

{
      code: 200,
      data: {
        address: string，
        privateKey: string,
      }    
  }

Get gasPrice

GET https://open-api.openocean.finance/v3/:chain/gasPrice

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

Example:

Request

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

Response:

{
 "code": 200,
 "data": {
  "standard": 3000000000,
  "fast": 3000000000,
  "instant": 3000000000
 },
 "without_decimals": {
  "standard": "3",
  "fast": "3",
  "instant": "3"
 }
}

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

e.g. 14 GWEI set as 14

Get Allowance

GET https://open-api.openocean.finance/v3/:chain/allowance

Query Parameters

Name

Type

Description

chain*

string

Chain name or Chain ID (supported chains)

account*

string

user's wallet address

inTokenAddress*

string

token address

Example:

Request

https://open-api.openocean.finance/v3/polygon/allowance?account=0x9116780aEf4B376499358fa7dEeC00cCF64fA801&inTokenAddress=0x831753DD7087CaC61aB5644b308642cc1c33Dc13

Response:

{
    code: 200,
    data: [
         {
            "symbol": "QUICK", // token symbol
            "allowance": "79228162514.26434", // without decimals
            "raw": "79228162514264340000000000000" // with decimals
        }
    ]
}

PreviousAPI V4 NextPermit2

Last updated 2 months ago

Recommend read the below docs along using OpenOcean API

Price Quote

Quote the price of a specific trading pair

Query Parameters

Building Transaction

Building Transaction

Query Parameters

Building Transaction

Get Transaction

Query Parameters

Get Tokens Lists

Query Parameters

Get Dexes List

Query Parameters

Get Transaction Hash from wallet

Query Parameters

Get Balance from wallet

Query Parameters

Create Wallet

Query Parameters

Get gasPrice

Query Parameters

Get Allowance

Query Parameters