Aggregator API V3

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

Price Quote

Quote the price of a specific trading pair

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

Query Parameters

Name Type Description

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`

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

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?	The wallet address used to be mark as partners and receive an extra referrerFee from user.
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.

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?

The wallet address used to be mark as partners and receive an extra referrerFee from user.

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

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

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

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

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

{
  {
    "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

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

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

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

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

PreviousAggregator API & SDK NextBest Practice

Last updated 14 days 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

Get Transaction

Query Parameters

Get Tokens Lists

Query Parameters

Get Dexes List

Query Parameters

Get Transaction Hash

Query Parameters

Get Balance from wallet

Query Parameters

Create Wallet

Query Parameters

Get gasPrice

Query Parameters

Get Allowance

Query Parameters

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

Get Transaction

Query Parameters

Get Tokens Lists

Query Parameters

Get Dexes List

Query Parameters

Get Transaction Hash

Query Parameters

Get Balance from wallet

Query Parameters

Create Wallet

Query Parameters

Get gasPrice

Query Parameters

Get Allowance

Query Parameters