API V3

GitHub - openocean-finance/openocean-api at feature/v3GitHub

Recommend read the below docs along using OpenOcean API

65KB

Best Practices of Using OpenOcean API.pdf

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	Please refer to "supported chains" for the corresponding chain codes/chain ID
inTokenAddress*	string	in token address
outTokenAddress*	string	out 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
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=0x929B44e589AC4dD99c0282614e9a844Ea9483aaa

• 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	Please refer to "supported chains" for the corresponding chain codes/chain ID
inTokenAddress*	string	in token address
outTokenAddress*	string	out 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
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	seller's address, please ensure that it has been approved to spend the necessary amount of inTokenAddress
referrer	string?	Set a wallet address used to identify partners and collect fees from users. If the referrerFee is not provided, no extra fee will be generated, and the wallet address will only be used to differentiate the data flow on your end.
referrerFee	number?	Specify the percentage of in-token you wish to receive from the transaction, within the range of 0% to 3%, with 1% represented as '1', in the range of 0.01 to 3. e.g. 1.2% fee set as 1.2 By default, OpenOcean shares 15% 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.

Example:

• Request

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

• 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.

Get Transaction

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

Query Parameters

Name	Type	Description
chain*	string	Please refer to "supported chains" for the corresponding chain codes/chain ID
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	Please refer to "supported chains" for the corresponding chain codes/chain ID

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	Please refer to "supported chains" for the corresponding chain codes/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 Transaction Hash

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

Query Parameters

Name	Type	Description
chain*	string	Please refer to "supported chains" for the corresponding chain codes/chain ID
account*	string	user's wallet address
pageSize*	number	The amount of tx hash you wish to receive

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

{
  {
    "code": 200,
    "data": [
        {
            "account": "0x929B44e589AC4dD99c0282614e9a844Ea9483C69",
            "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

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	Please refer to "supported chains" for the corresponding chain codes/chain ID

Example:

• Request

 https://open-api.openocean.finance/v1/cross/getBalance?chainId=56&account=0x929B44e589AC4dD99c0282614e9a844Ea9483C69&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	Please refer to "supported chains" for the corresponding chain codes/chain ID

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	Please refer to "supported chains" for the corresponding chain codes/chain ID

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	Please refer to "supported chains" for the corresponding chain codes/chain ID
account*	string	user's wallet address
inTokenAddress*	string	token address

Example:

• Request

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

• Response:

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