OpenOcean
Launch AppGitHubReferral programMedia
Search
⌃K
Links

OpenOcean API 2.0

OpenOcean API 2.0 stoped updating, so it will be better for developer to use OpenOcean API 3.0​
​

1. Quote price

Parameter name
Type
Example
Description
exChange
string
1inch
platform(openoceanv1,openoceanv2,1inch,matcha,paraswap)
chainId
number
56
chain id (1/56/100/137/250/42161/43114) In particular, we have defined Terra as 400
inTokenSymbol
string
USDT
sell token name
inTokenAddress
string
0x55d398326f99059ff775485246999027b3197955
sell token address
outTokenSymbol
string
BNB
buy token name
outTokenAddress
string
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
buy token address
amount
number
1
sell amount
gasPrice
number
5
you can set it yourself or get it through GetGasPrice
slippage
number
1
1 equals 1%,
ranges 0.01% to100%
in_token_decimals
number?
18
you can define it according to the market
out_token_decimals
number?
18
you can define it according to the market
withRoute
string?
routes
default null
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/quote?inTokenSymbol=USDT
&inTokenAddress=0x55d398326f99059ff775485246999027b3197955
&outTokenSymbol=BNB&outTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
&amount=1
&gasPrice=5
&slippage=100
&exChange=openoceanv2
&chainId=56
Response:
{
code: 200,
error: "",
data: {
"inToken": {
"symbol": "USDT",
"chainId": "56",
"address": "0x55d398326f99059ff775485246999027b3197955",
"inUsd": 0.694055 // inAmount to usd
},
"outToken": {
"symbol": "BNB",
"chainId": "56",
"address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
"outUsd": "0.6984" // outAmount to usd
},
"inAmount": "1",
"outAmount": "0.0014",
"exChange": "1inch",
"transCost": "0.000946225",
"transUsd": "0.4561", // transCost to usd
"save": "" // only openoceanv2 has this key
}
}

2. Get token list

Parameter
Type
Example
Description
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/tokenList?chainId=56
Response:
{
code: 200,
error: "",
data: [
{
"symbol": "0xBTC",
"name": "0xBitcoin Token",
"address": "0xb6ed7644c69416d67b522e20bc294a9a9b405b31",
"decimals": 8
},
{
"symbol": "1INCH",
"name": "1INCH Token",
"address": "0x111111111117dc0aa78b770fa6a738034120c302",
"decimals": 18
},
{
"symbol": "1UP",
"name": "Uptrennd",
"address": "0x07597255910a51509ca469568b048f2597e72504",
"decimals": 18
},
{
"symbol": "2KEY",
"name": "TwoKeyEconomy",
"address": "0xe48972fcd82a274411c01834e2f031d4377fa2c0",
"decimals": 18
},
...
]
}
​

3. Create wallet

Parameter
Type
Example
Description
chainId
number
56
chain id (1/56/137/43114)
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/createWallet?chainId=56
Response:
{
code: 200,
error: "",
data: {
address: string，
privateKey: string,
}
}

4. Get balance

Parameter
Type
Example
Description
account
string
optional
wallet address
chainId
number
56
chain id (1/56/137/43114)
inTokenAddress
string
0x55d398326f99059ff775485246999027b3197955,0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
token address
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/getBalance?chainId=56
&account=0xe7d92d0B213bfdfCb1A7fb8fc5C53348EE5f6cFa
&inTokenAddress=0x55d398326f99059ff775485246999027b3197955,
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE

Response:

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

5. Swap

Parameter
Type
Parameter
Description
exChange
string
openoceanv2
platform
chainId
number
56
chainId 56
inTokenSymbol
string
USDT
sell token name
inTokenAddress
string
sell token address
0x55d398326f99059ff775485246999027b3197955
outTokenSymbol
string
USDC
buy token name
outTokenAddress
string
0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
buy token address
amount
number
50
sell token amount
gasPrice
number
5
you can set it yourself or get it through GetGasPrice
slippage
number
1
1 equals 1%,
ranges 0.01% to100%
account
string
wallet address
It can be read from the configuration file
referrer
string？
0x0000000000000000000000000000000000000000
Please contact us for a unique referrer parameter
in_token_decimals
number?
18
you can define it according to the market
out_token_decimals
number?
18
you can define it according to the market
withoutCheckBalance
boolean?
true
default null
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/swap?chainId=56
&exChange=openoceanv2&inTokenSymbol=USDT
&inTokenAddress=0x55d398326f99059ff775485246999027b3197955
&outTokenSymbol=USDC&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
&amount=5
&gasPrice=5&slippage=100
Response:
{
code: 200,
error: "",
data: {
hash: "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
}
}

6. Get transaction

Parameter
Type
Example
Description
chainId
number
56
chain id (1/56/137/43114)
hash
string
0xa4733659e9a9496b30228f98b8d862062e93e58d7e9b8f208c5215228fc5b858
hash value
exChange
string
openoceanv2
openoceanv1/openoceanv2
type
string
transfer
transfer/swap
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/getTransaction?chainId=56
&hash=0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71
&exChange=openoceanv2
Response:
{
code: 200,
error: "",
data: {
"hash": "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
"blockNumber": 12123764,
"transactionIndex": 527,
"from": "0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a",
"to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
"inTokenAddress": "0x55d398326f99059ff775485246999027b3197955",
"inTokenSymbol": "USDT",
"outTokenAddress": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"outTokenSymbol": "USDC",
"inAmount": 5,
"outAmount": "3.3951",
"gasFee": "0.59" // usd
}
}

7. Get transaction receipt

Parameter
Type
Example
Description
chainId
number
56
chain id (1/56/137/43114)
hash
string
0xa4733659e9a9496b30228f98b8d862062e93e58d7e9b8f208c5215228fc5b858
hash value
exChange
string
openoceanv2
platform(openoceanv1/openoceanv2)
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/getTransactionReceipt?chainId=56
&hash=0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71
&exChange=openoceanv2
Response:
{
code: 200,
error: "",
data: {
"to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
"from": "0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a",
"contractAddress": null,
"transactionIndex": 527,
"transactionHash": "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
"blockNumber": 12123764,
"confirmations": 190,
"status": 1 // -2-not on the chain -1-pendding 0-fail 1-success
}
}

8. Transfer

Parameter
Type
Example
Description
chainId
number
56
chain id
inTokenAddress
string
0x55d398326f99059ff775485246999027b3197955
transfer token address
inTokenSymbol
string
USDT
transfer token name
decimals
number
18
unit conversion
amount
number
5
transfer number
gasPrice
number
5
you can set it yourself or get it through GetGasPrice
targetAddress
string
0x929B44e589AC4dD99c0282614e9a844Ea9483C69
wallet address
  • Example:
Request:
https://open-api.openocean.finance/v1/cross/transfer?chainId=56
&inTokenAddress=0x55d398326f99059ff775485246999027b3197955
&inTokenSymbol=USDT&decimals=18&amount=2
&gasPrice=5
&targetAddress=0x929B44e589AC4dD99c0282614e9a844Ea9483C69
Response:
{
code: 200,
error: "",
data: {
hash: "0xcec6125eebcfb6a5e32341d9bc2571946dbf2a1db018e333abd644f505840529"
}
}

9. GetGasPrice

​
  • Method: get
  • Url: https://open-api.openocean.finance/v1/:chainId/getGasPrice
  • Parameters:
parameter
type
example
description
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
  • Example:
request:
https://open-api.openocean.finance/v1/56/getGasPrice
response:
{
code: 200,
data: {
price: 5 // default 5
}
}

10. Swap quote

​
Parameter
Type
Parameter
Description
exChange
string
1inch
platform
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
In particular, we have defined Terra as 400
inTokenSymbol
string
USDT
sell token name
inTokenAddress
string
sell token address
0x55d398326f99059ff775485246999027b3197955
outTokenSymbol
string
USDC
buy token name
outTokenAddress
string
0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
buy token address
amount
number
50
sell token amount
gasPrice
number
5
you can set it yourself or get it through GetGasPrice
slippage
number
1
1 equals 1%,
ranges 0.01% to100%
account
string
wallet address
It can be read from the configuration file
referrer
string?
0x0000000000000000000000000000000000000000
Please contact us for a unique referrer parameter
in_token_decimals
number?
18
you can define it according to the market
out_token_decimals
number?
18
you can define it according to the market
withoutCheckBalance
boolean?
true
default null
  • Example:
    request:
    https://open-api.openocean.finance/v1/cross/swap_quote?
    inTokenSymbol=USDT
    &inTokenAddress=0x55d398326f99059ff775485246999027b3197955
    &outTokenSymbol=BNB
    &outTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
    &amount=1
    &gasPrice=40
    &slippage=100
    &exChange=openoceanv2
    &chainId=56
    &in_token_decimals=18
    &out_token_decimals=9
    &account=0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a
    response:
    {
    "code": 200,
    "error":""
    "data": {
    "inToken": {
    "symbol": "",
    "name": "",
    "address": "",
    "decimals":
    },
    "outToken": {
    "symbol": "",
    "name": "",
    "address": "",
    "decimals":
    },
    "inAmount": "",
    "outAmount": "",
    "estimatedGas": "",
    "minOutAmount": "",
    "from": "",
    "to": "",
    "value": "0",
    "gasPrice": "",
    "data": "" // important parameter for transaction
    }
    }

11. GetAllowance

​
  • Method: Get
  • URL: https://open-api.openocean.finance/v1/cross/getAllowance
  • Parameters:
Parameter
Type
Parameter
Description
account
string
0xf8953d8671644348303cfa8Ae408F5d9fb884761
wallet address
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
In particular, we have defined Terra as 400
inTokenAddress
string
0x9029FdFAe9A03135846381c7cE16595C3554e10A,0x08ba0619b1e7a582e0bce5bbe9843322c954c340
token address
contractAddress
string
0x6352a56caadC4F1E25CD6c75970Fa768A3304e64
contract address
Example:
request:
https://open-api.openocean.finance/v1/cross/getAllowance?chainId=56&account=0xf8953d8671644348303cfa8Ae408F5d9fb884761&inTokenAddress=0x55d398326f99059ff775485246999027b3197955,0x08ba0619b1e7a582e0bce5bbe9843322c954c340&contractAddress=0x6352a56caadC4F1E25CD6c75970Fa768A3304e64
response:
{
"code": 200,
"data": [
{
"symbol": "USDT",
"allowance": "0",
"raw": "0"
},
{
"symbol": "BMON",
"allowance": "0",
"raw": "0"
}
]
}

Common error codes

Codes
Error description
201
Invalid request format
202
Set token decimals
204
Insufficient balance
205
Suspend trading
206
Fail to approve token
500
Internal server error
​
​
Developer - Previous
Legacy
Next
OpenOcean CEX API
Last modified 1yr ago