OpenOcean DEX API 2.0
Instruction of OpenOcean DEX API 2.0
We strongly recommend that users deploy it themselves, rather than simply call it!

1. Quote price

Parameter name
Type
Example
Description
exChange
string
openoceanv2
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
OOE
sell token name
inTokenAddress
string
0x9029FdFAe9A03135846381c7cE16595C3554e10A
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:
1
https://open-api.openocean.finance/v1/cross/quote?inTokenSymbol=OOE
2
&inTokenAddress=0x9029FdFAe9A03135846381c7cE16595C3554e10A
3
&outTokenSymbol=BNB&outTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
4
&amount=1
5
&gasPrice=5
6
&slippage=100
7
&exChange=openoceanv2
8
&chainId=56
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: {
5
"inToken": {
6
"symbol": "OOE",
7
"chainId": "56",
8
"address": "0x9029FdFAe9A03135846381c7cE16595C3554e10A",
9
"inUsd": 0.694055 // inAmount to usd
10
},
11
"outToken": {
12
"symbol": "BNB",
13
"chainId": "56",
14
"address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
15
"outUsd": "0.6984" // outAmount to usd
16
},
17
"inAmount": "1",
18
"outAmount": "0.0014",
19
"exChange": "openoceanv2",
20
"transCost": "0.000946225",
21
"transUsd": "0.4561", // transCost to usd
22
"save": "" // only openoceanv2 has this key
23
}
24
}
Copied!

2. Get token list

Parameter
Type
Example
Description
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
  • Example:
Request:
1
https://open-api.openocean.finance/v1/cross/tokenList?chainId=56
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: [
5
{
6
"symbol": "0xBTC",
7
"name": "0xBitcoin Token",
8
"address": "0xb6ed7644c69416d67b522e20bc294a9a9b405b31",
9
"decimals": 8
10
},
11
{
12
"symbol": "1INCH",
13
"name": "1INCH Token",
14
"address": "0x111111111117dc0aa78b770fa6a738034120c302",
15
"decimals": 18
16
},
17
{
18
"symbol": "1UP",
19
"name": "Uptrennd",
20
"address": "0x07597255910a51509ca469568b048f2597e72504",
21
"decimals": 18
22
},
23
{
24
"symbol": "2KEY",
25
"name": "TwoKeyEconomy",
26
"address": "0xe48972fcd82a274411c01834e2f031d4377fa2c0",
27
"decimals": 18
28
},
29
...
30
]
31
}
32
Copied!

3. Create wallet

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

4. Get balance

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

Response:

1
{
2
code: 200,
3
error: "",
4
data: [
5
{
6
"symbol": "OOE",
7
"tokenAddress": "0x9029FdFAe9A03135846381c7cE16595C3554e10A",
8
"balance": 0,
9
"raw": 0
10
},
11
{
12
"symbol": "BNB",
13
"tokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
14
"balance": 0,
15
"raw": 0
16
}
17
]
18
}
Copied!

5. Swap

Parameter
Type
Parameter
Description
exChange
string
openoceanv2
platform
chainId
number
56
chainId 56
inTokenSymbol
string
OOE
sell token name
inTokenAddress
string
sell token address
0x9029FdFAe9A03135846381c7cE16595C3554e10A
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:
1
https://open-api.openocean.finance/v1/cross/swap?chainId=56
2
&exChange=openoceanv2&inTokenSymbol=OOE
3
&inTokenAddress=0x9029FdFAe9A03135846381c7cE16595C3554e10A
4
&outTokenSymbol=USDC&outTokenAddress=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d
5
&amount=5
6
&gasPrice=5&slippage=100
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: {
5
hash: "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
6
}
7
}
Copied!

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:
1
https://open-api.openocean.finance/v1/cross/getTransaction?chainId=56
2
&hash=0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71
3
&exChange=openoceanv2
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: {
5
"hash": "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
6
"blockNumber": 12123764,
7
"transactionIndex": 527,
8
"from": "0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a",
9
"to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
10
"inTokenAddress": "0x9029FdFAe9A03135846381c7cE16595C3554e10A",
11
"inTokenSymbol": "OOE",
12
"outTokenAddress": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
13
"outTokenSymbol": "USDC",
14
"inAmount": 5,
15
"outAmount": "3.3951",
16
"gasFee": "0.59" // usd
17
}
18
}
Copied!

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:
1
https://open-api.openocean.finance/v1/cross/getTransactionReceipt?chainId=56
2
&hash=0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71
3
&exChange=openoceanv2
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: {
5
"to": "0x6352a56caadC4F1E25CD6c75970Fa768A3304e64",
6
"from": "0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a",
7
"contractAddress": null,
8
"transactionIndex": 527,
9
"transactionHash": "0x591ba7950e039f21de04831c7231584958a5255c4e2af7a08ec651ed8599de71",
10
"blockNumber": 12123764,
11
"confirmations": 190,
12
"status": 1 // -2-not on the chain -1-pendding 0-fail 1-success
13
}
14
}
Copied!

8. Transfer

Parameter
Type
Example
Description
chainId
number
56
chain id
inTokenAddress
string
0x9029FdFAe9A03135846381c7cE16595C3554e10A
transfer token address
inTokenSymbol
string
OOE
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:
1
https://open-api.openocean.finance/v1/cross/transfer?chainId=56
2
&inTokenAddress=0x9029FdFAe9A03135846381c7cE16595C3554e10A
3
&inTokenSymbol=OOE&decimals=18&amount=2
4
&gasPrice=5
5
&targetAddress=0x929B44e589AC4dD99c0282614e9a844Ea9483C69
Copied!
Response:
1
{
2
code: 200,
3
error: "",
4
data: {
5
hash: "0xcec6125eebcfb6a5e32341d9bc2571946dbf2a1db018e333abd644f505840529"
6
}
7
}
Copied!

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:
1
https://open-api.openocean.finance/v1/56/getGasPrice
Copied!
response:
1
{
2
code: 200,
3
data: {
4
price: 5 // default 5
5
}
6
}
Copied!

10. Swap quote

Parameter
Type
Parameter
Description
exChange
string
openoceanv2
platform
chainId
number
56
chain id (1/56/100/137/250/42161/43114)
In particular, we have defined Terra as 400
inTokenSymbol
string
OOE
sell token name
inTokenAddress
string
sell token address
0x9029FdFAe9A03135846381c7cE16595C3554e10A
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:
    1
    https://open-api.openocean.finance/v1/cross/swap_quote?
    2
    inTokenSymbol=OOE
    3
    &inTokenAddress=0x9029FdFAe9A03135846381c7cE16595C3554e10A
    4
    &outTokenSymbol=BNB
    5
    &outTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
    6
    &amount=1
    7
    &gasPrice=40
    8
    &slippage=100
    9
    &exChange=openoceanv2
    10
    &chainId=56
    11
    &in_token_decimals=18
    12
    &out_token_decimals=9
    13
    &account=0x6ce8Ea05AFDF026BA6e9998936598EE8F0163F3a
    Copied!
    response:
    1
    {
    2
    "code": 200,
    3
    "error":""
    4
    "data": {
    5
    "inToken": {
    6
    "symbol": "",
    7
    "name": "",
    8
    "address": "",
    9
    "decimals":
    10
    },
    11
    "outToken": {
    12
    "symbol": "",
    13
    "name": "",
    14
    "address": "",
    15
    "decimals":
    16
    },
    17
    "inAmount": "",
    18
    "outAmount": "",
    19
    "estimatedGas": "",
    20
    "minOutAmount": "",
    21
    "from": "",
    22
    "to": "",
    23
    "value": "0",
    24
    "gasPrice": "",
    25
    "data": "" // important parameter for transaction
    26
    }
    27
    }
    Copied!

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:
1
https://open-api.openocean.finance/v1/cross/getAllowance?chainId=56&account=0xf8953d8671644348303cfa8Ae408F5d9fb884761&inTokenAddress=0x9029FdFAe9A03135846381c7cE16595C3554e10A,0x08ba0619b1e7a582e0bce5bbe9843322c954c340&contractAddress=0x6352a56caadC4F1E25CD6c75970Fa768A3304e64
Copied!
response:
1
{
2
"code": 200,
3
"data": [
4
{
5
"symbol": "OOE",
6
"allowance": "0",
7
"raw": "0"
8
},
9
{
10
"symbol": "BMON",
11
"allowance": "0",
12
"raw": "0"
13
}
14
]
15
}
Copied!

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