Legacy API V2

OpenOcean API 2 has stopped updating, please refer to Aggregator API V3 or V4 for integration.

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

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

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

Last updated