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
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	ID of dexes could be access through dexList endpoint
enabledDexIds	string	ID of dexes could be access through dexList endpoint P.S. enableDexIds has higher priority compare with disabledDexIds

200: OK https://open-api.openocean.finance/v3/1/quote?inTokenAddress=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&outTokenAddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amount=1&gasPrice=25&slippage=1

{
"code": 200,
"data": {
    "inToken": {
        "symbol": "AUSD",
        "name": "Avaware USD",
        "address": "0x783C08b5F26E3daf8C4681F3bf49844e425b6393",
        "decimals": 18
    },
    "outToken": {
        "symbol": "EMBR",
        "name": "EmbrToken",
        "address": "0xD81D45E7635400dDD9c028839e9a9eF479006B28",
        "decimals": 18
    },
    "inAmount": "5000000000000000000",
    "outAmount": "126261357830302882735",
    "estimatedGas": "189669",
    "dexes": [
        {
            "dexIndex": 1,
            "dexCode": "SushiSwap",
            "swapAmount": "0"
        },
        ...
    ],
    "path": {
    }
}

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?	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	ID of dexes could be access through dexList endpoint 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.

200: OK https://open-api.openocean.finance/v3/1/swap_quote?inTokenAddress=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&outTokenAddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&account=0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50&amount=1&gasPrice=25&slippage=1

{
"code": 200,
"data": {
    "inToken": {
        "symbol": "BNB",
        "name": "Binance Coin",
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "decimals": 18
    },
    "outToken": {
        "symbol": "USDT",
        "name": "Binance-Peg USD (T)",
        "address": "0x55d398326f99059ff775485246999027b3197955",
        "decimals": 18
    },
    "inAmount": "5000000000000000000",
    "outAmount": "1854329353330546150894",
    "estimatedGas": "353007",  
    "minOutAmount": "0",
    "from": "0x929B44e589AC4dD99c0282614e9a844Ea9483C69",
    "to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
    "value": "5000000000000000000",
    "gasPrice": "5000000000",
    "data": ""
}

Get Transaction

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

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

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

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

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

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

200: OK https://open-api.openocean.finance/v3/avax/dexList

{
"code": 200,
"data": [
    {
        "index": 1,
        "code": "SushiSwap",
        "name": "SushiSwap"
    },
    {
        "index": 2,
        "code": "Pangolin",
        "name": "Pangolin"
    },
    ...
]  // Response
}

Get Transaction Hash

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

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

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

Create Wallet

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

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

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

Get gasPrice

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

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

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