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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/quote
Parameters:

Parameter name

Type

Example

Description

exChange

string

1inch

platform(openoceanv1,openoceanv2,1inch,matcha,paraswap)

chainId

number

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

sell amount

gasPrice

number

you can set it yourself or get it through GetGasPrice

slippage

number

1 equals 1%,

ranges 0.01% to100%

in_token_decimals

number?

you can define it according to the market

out_token_decimals

number?

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/tokenList
Parameters:

Parameter

Type

Example

Description

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/createWallet
Parameters:

Parameter

Type

Example

Description

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/getBalance
Parameters:

Parameter

Type

Example

Description

account

string

optional

wallet address

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/swap
Parameters:

Parameter

Type

Parameter

Description

exChange

string

openoceanv2

platform

chainId

number

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

sell token amount

gasPrice

number

you can set it yourself or get it through GetGasPrice

slippage

number

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?

you can define it according to the market

out_token_decimals

number?

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/getTransaction
Parameters:

Parameter

Type

Example

Description

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/getTransactionReceipt
Parameters:

Parameter

Type

Example

Description

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/transfer
Parameters:

Parameter

Type

Example

Description

chainId

number

chain id

inTokenAddress

string

0x55d398326f99059ff775485246999027b3197955

transfer token address

inTokenSymbol

string

USDT

transfer token name

decimals

number

unit conversion

amount

number

transfer number

gasPrice

number

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)

parameter

type

example

description

chainId

number

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

Method: Get
URL: https://open-api.openocean.finance/v1/cross/swap_quote
Parameters:

Parameter

Type

Parameter

Description

exChange

string

1inch

platform

chainId

number

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

sell token amount

gasPrice

number

you can set it yourself or get it through GetGasPrice

slippage

number

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?

you can define it according to the market

out_token_decimals

number?

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

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

PreviousLegacy NextDeveloper references & glossary

Last updated 2 years ago