Guide

Cross-Chain API Documentation

API

OpenOcean Cross-chain API Integration Guide

OpenOcean provides an API interface for cross-chain trading, enabling developers to implement cross-chain asset transfers. This guide will introduce how to use this feature's API.

Cross-chain Overview

The Cross-chain feature allows users to directly transfer crypto assets between different blockchain networks on the OpenOcean platform.

Cross-chain Transfer in 3 Steps

  1. Get Quote for Cross-chain Transfer

  2. Execute Cross-chain Transaction

  3. Monitor Transaction Status

1. Get Quote for Cross-chain Transfer

You can call the Quote API to get all available routes and fees for your cross-chain transfer.

Example request:

// Transfer 30 USDT from BSC to USDC on Polygon
import axios from 'axios';
const response = await axios({
    url: 'https://open-api.openocean.finance/cross_chain/v1/cross/quoteByOO?' +
         'fromSymbol=USDT' +
         '&fromChainId=56' +  
         '&toSymbol=USDC' +
         '&toChainId=137' +
         '&amount=30000000000000000000' +
         '&sort=cheapestRoute',
    method: 'GET'
});
​
const quote = response.data;

Example response:

{
  "code": 200,
  "data": {
    "fromAsset": {
      "ids": "tether",
      "name": "Binance-Peg USD (T)",
      "address": "0x55d398326f99059ff775485246999027b3197955",
      "decimals": 18,
      "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
      "symbol": "USDT",
      "chain": "bsc",
      "chainId": "56"
    },
    "toAsset": {
      "ids": "usd-coin",
      "name": "USDC",
      "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "decimals": 6,
      "icon": "https://s3.openocean.finance/token_logos/logos/1710141465519_2940486690496251.png",
      "symbol": "USDC",
      "chain": "polygon",
      "chainId": "137"
    },
    "fromChainId": "56",
    "toChainId": "137",
    "routes": [
      null,
      {
        "isApprovalRequired": true,
        "allowanceTarget": "0x3D84A60fdDeb9FAdb4072b0ba27fd1C99Aa14365",
        "middlewareRoute": [],
        "bridgeRoute": {
          "bridgeId": 24,
          "tokenReceiver": "0x798Ca148e60a210AaE9EF274f8B6395524C7302c",
          "bridgeInfo": {
            "serviceTime": 200,
            "displayName": "Symbiosis Bridge",
            "icon": "https://s3.openocean.finance/static/symbiosis.svg",
            "code": "symbiosis"
          },
          "fromAsset": {
            "ids": "tether",
            "name": "Binance-Peg USD (T)",
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
            "symbol": "USDT",
            "chain": "bsc",
            "chainId": "56"
          },
          "fromChainId": "56",
          "toAsset": {
            "ids": "usd-coin",
            "name": "USDC",
            "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
            "decimals": 6,
            "icon": "https://s3.openocean.finance/token_logos/logos/1710141465519_2940486690496251.png",
            "symbol": "USDC",
            "chain": "polygon",
            "chainId": "137"
          },
          "toChainId": "137",
          "value": 0,
          "inputAmount": "30000000000000000000",
          "outputAmount": "29393817"
        },
        "fees": {
          "gasLimit": [],
          "middlewareFee": {},
          "bridgeFee": {
            "symbol": "USDC",
            "icon": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png",
            "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
            "amount": "600000",
            "chainId": 137,
            "decimals": 6,
            "value": "0.6"
          }
        },
        "type": 1
      },
      {
        "isApprovalRequired": true,
        "allowanceTarget": "0x9Fe54152D08087061916a7D18cC164d6ea8cB62C",
        "middlewareRoute": [],
        "bridgeRoute": {
          "bridgeId": 20,
          "tokenReceiver": "0xd373888dcaDDCB270a407E4B963E655922bE2E73",
          "bridgeInfo": {
            "serviceTime": 200,
            "displayName": "Squid",
            "icon": "https://s3.openocean.finance/static/squid.svg",
            "code": "squid"
          },
          "fromAsset": {
            "ids": "tether",
            "name": "Binance-Peg USD (T)",
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
            "symbol": "USDT",
            "chain": "bsc",
            "chainId": "56"
          },
          "fromChainId": "56",
          "toAsset": {
            "ids": "usd-coin",
            "name": "USDC",
            "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
            "decimals": 6,
            "icon": "https://s3.openocean.finance/token_logos/logos/1710141465519_2940486690496251.png",
            "symbol": "USDC",
            "chain": "polygon",
            "chainId": "137"
          },
          "toChainId": "137",
          "value": 0,
          "inputAmount": "30000000000000000000",
          "outputAmount": "29997010"
        },
        "fees": {
          "gasLimit": [
            {
              "chainId": 56,
              "name": "BNB",
              "symbol": "BNB",
              "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
              "decimals": 18,
              "logoURI": "https://raw.githubusercontent.com/0xsquid/assets/main/images/master/tokens/bnb.svg",
              "coingeckoId": "binancecoin",
              "commonKey": "wbnb-wei",
              "amount": "1467500000000000",
              "value": "0.8805"
            }
          ],
          "middlewareFee": {},
          "bridgeFee": {
            "chainId": 56,
            "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "name": "Binance Chain Native Token",
            "symbol": "BNB",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png",
            "ids": "binancecoin",
            "amount": "365184046172157",
            "value": 1
          }
        },
        "type": 1
      },
      {
        "isApprovalRequired": true,
        "allowanceTarget": "0x018fEADD83a8f2ad4d2508469a3a3215483C4377",
        "middlewareRoute": [
          {
            "137": {
              "middlewareId": 7,
              "middlewareName": "OpenOcean",
              "middlewareInfo": {
                "displayName": "OpenOcean",
                "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x9029fdfae9a03135846381c7ce16595c3554e10a.png"
              },
              "fromAsset": {
                "ids": "usd-coin",
                "name": "USD Coin (PoS)",
                "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
                "decimals": 6,
                "symbol": "USDC",
                "chain": "polygon",
                "chainId": 137,
                "icon": "https://s3.openocean.finance/token_logos/logos/polygon/0x2791bca1f2de4661ed88a30c99a7a9449aa84174.png"
              },
              "toAsset": {
                "ids": "usd-coin",
                "name": "USDC",
                "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
                "decimals": 6,
                "icon": "https://s3.openocean.finance/token_logos/logos/1710141465519_2940486690496251.png",
                "symbol": "USDC",
                "chain": "polygon",
                "chainId": "137"
              },
              "inputAmount": "29670300",
              "outputAmount": "29673215",
              "value": 0
            }
          }
        ],
        "bridgeRoute": {
          "bridgeId": 23,
          "messageBus": "0x4a364f8c717cAAD9A442737Eb7b8A55cc6cf18D8",
          "tokenReceiver": "0x04954F93D189c9aFB6E09c47a55d9A124537aB08",
          "bridgeInfo": {
            "serviceTime": 200,
            "displayName": "Stargate Bridge",
            "icon": "https://s3.openocean.finance/static/stargate.svg",
            "code": "stargate"
          },
          "fromAsset": {
            "chainId": 56,
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "name": "Binance-Peg USD (T)",
            "symbol": "USDT",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
            "ids": "tether",
            "chain": "bsc",
            "cross": "0xedf0c420bc3b92b961c6ec411cc810ca81f5f21a"
          },
          "fromChainId": 56,
          "toAsset": {
            "ids": "usd-coin",
            "name": "USD Coin (PoS)",
            "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
            "decimals": 6,
            "symbol": "USDC",
            "chain": "polygon",
            "chainId": 137,
            "icon": "https://s3.openocean.finance/token_logos/logos/polygon/0x2791bca1f2de4661ed88a30c99a7a9449aa84174.png",
            "cross": "0xedf0c420bc3b92b961c6ec411cc810ca81f5f21a"
          },
          "toChainId": 137,
          "value": 0,
          "inputAmount": "30000000000000000000",
          "outputAmount": "29670300"
        },
        "fees": {
          "gasLimit": [
            {
              "chainId": 137,
              "address": "0x0000000000000000000000000000000000001010",
              "icon": "https://s3.openocean.finance/images/1637561049975_1903381661429342.png",
              "name": "Matic",
              "symbol": "MATIC",
              "decimals": 18,
              "ids": "matic-network",
              "assetAddress": "0x0000000000000000000000000000000000001010",
              "amount": 522458,
              "value": 0.006073727194522211
            }
          ],
          "middlewareFee": {
            "chainId": 56,
            "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "name": "Binance Chain Native Token",
            "symbol": "BNB",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png",
            "ids": "binancecoin",
            "assetAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "amount": 0
          },
          "bridgeFee": {
            "chainId": 56,
            "address": "0x55d398326f99059ff775485246999027b3197955",
            "name": "Binance-Peg USD (T)",
            "symbol": "USDT",
            "decimals": 18,
            "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
            "ids": "tether",
            "chain": "bsc",
            "amount": "329699999999999000",
            "assetAddress": "0x55d398326f99059ff775485246999027b3197955"
          }
        },
        "type": 1,
        "src_poolId": 2,
        "dst_poolId": 1,
        "src_chainId": 102,
        "dst_chainId": 109
      },
      null
    ]
  }
}

2. Execute Cross-chain Transaction

After getting the quote, you can execute the cross-chain transfer by calling the swap API.

Example request:

import axios from 'axios';
const response = await axios({
    url: 'https://open-api.openocean.finance/cross_chain/v1/cross/stargate/swap',
    method: 'POST',
    data: {
        account: "0x2132b141D19D7563e686Bb6f4764C7cE9097D514",
        route: {
                "isApprovalRequired": true,
                "allowanceTarget": "0x018fEADD83a8f2ad4d2508469a3a3215483C4377",
                "middlewareRoute": [
                    {
                        "137": {
                            "middlewareId": 7,
                            "middlewareName": "OpenOcean",
                            "middlewareInfo": {
                                "displayName": "OpenOcean",
                                "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x9029fdfae9a03135846381c7ce16595c3554e10a.png"
                            },
                            "fromAsset": {
                                "ids": "tether",
                                "name": "Tether USD",
                                "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
                                "decimals": 6,
                                "symbol": "USDT",
                                "chain": "polygon",
                                "chainId": "137",
                                "icon": "https://s3.openocean.finance/images/1640831384587_011475796734160326.png"
                            },
                            "toAsset": {
                                "ids": "usd-coin",
                                "name": "USD Coin",
                                "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
                                "decimals": 6,
                                "symbol": "USDC",
                                "chain": "polygon",
                                "chainId": "137",
                                "icon": "https://ethapi.openocean.finance/logos/polygon/0x2791bca1f2de4661ed88a30c99a7a9449aa84174.png"
                            },
                            "inputAmount": "29670300",
                            "outputAmount": "29757056",
                            "value": 0
                        }
                    }
                ],
                "bridgeRoute": {
                    "bridgeId": 23,
                    "messageBus": "0x4a364f8c717cAAD9A442737Eb7b8A55cc6cf18D8",
                    "tokenReceiver": "0x04954F93D189c9aFB6E09c47a55d9A124537aB08",
                    "bridgeInfo": {
                        "serviceTime": 600000,
                        "displayName": "Stargate Bridge",
                        "icon": "https://s3.openocean.finance/static/stargate.svg",
                        "code": "stargate"
                    },
                    "fromAsset": {
                        "ids": "tether",
                        "name": "Binance-Peg USD (T)",
                        "address": "0x55d398326f99059ff775485246999027b3197955",
                        "decimals": 18,
                        "symbol": "USDT",
                        "chain": "bsc",
                        "chainId": "56",
                        "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
                        "cross": "0xedf0c420bc3b92b961c6ec411cc810ca81f5f21a"
                    },
                    "fromChainId": "56",
                    "toAsset": {
                        "ids": "tether",
                        "name": "Tether USD",
                        "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
                        "decimals": 6,
                        "symbol": "USDT",
                        "chain": "polygon",
                        "chainId": "137",
                        "icon": "https://s3.openocean.finance/images/1640831384587_011475796734160326.png",
                        "cross": "0xedf0c420bc3b92b961c6ec411cc810ca81f5f21a"
                    },
                    "toChainId": "137",
                    "value": 0,
                    "inputAmount": "30000000000000000000",
                    "outputAmount": "29670300"
                },
                "fees": {
                    "gasLimit": [
                        {
                            "chainId": 137,
                            "address": "0x0000000000000000000000000000000000001010",
                            "icon": "https://s3.openocean.finance/images/1637561049975_1903381661429342.png",
                            "name": "Matic",
                            "symbol": "MATIC",
                            "decimals": 18,
                            "ids": "matic-network",
                            "assetAddress": "0x0000000000000000000000000000000000001010",
                            "amount": 465385,
                            "value": 0.05403689156807064
                        }
                    ],
                    "middlewareFee": {
                        "chainId": 56,
                        "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                        "name": "Binance Chain Native Token",
                        "symbol": "BNB",
                        "decimals": 18,
                        "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png",
                        "ids": "binancecoin",
                        "assetAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                        "amount": 0
                    },
                    "bridgeFee": {
                        "ids": "tether",
                        "name": "Binance-Peg USD (T)",
                        "address": "0x55d398326f99059ff775485246999027b3197955",
                        "decimals": 18,
                        "symbol": "USDT",
                        "chain": "bsc",
                        "chainId": "56",
                        "icon": "https://s3.openocean.finance/token_logos/logos/bsc/0x55d398326f99059ff775485246999027b3197955.png",
                        "amount": "329699999999999000",
                        "assetAddress": "0x55d398326f99059ff775485246999027b3197955"
                    }
                },
                "type": 1,
                "src_poolId": 2,
                "dst_poolId": 1,
                "src_chainId": 102,
                "dst_chainId": 109
            }
    }
});

Example response:

{
    "code": 200,
    "data": {
        "from": "0x2132b141D19D7563e686Bb6f4764C7cE9097D514",
        "to": "0x43c47B76D24Ad1F73f5Ab12442A016397A5ae9F6",
        "data": "0xa44bbb150000000000000000...", // input data
        "value": "3041816680838351"
    }
}

3. Monitor Transaction Status

Track your transaction status until completion.

Example request:

import axios from 'axios';
const response = await axios({
    url: 'https://open-api.openocean.finance/cross_chain/v1/cross/getCrossStatus?' +
         'chainId=56' +
         '&hash=0xa4208f52f834771a5f96e87f6cadcd4691274289bd99e1a508e38cbc986e56e3'
});

Example response:

{
  "code": 0,
  "data": {
    "status": 5, // 2-fail, 3-pending, 5-success
    "outAmount": "20993692", // dest amount with decimals
    "destHash": "0x68a71370b6ddc85fc77f8ddf8d0529e4f4320406f9803b6cd561a1b1d37d745c", // dest chain hash
    "swapHash": "0x27221b9003d3997f40d1d1a7360720b9031dff67beb3ba7a0815a31417d1bc74", // swap hash, if dest chain need to swap
    "swapStatus": 5 // swap status
  }
}

Important Notes

  1. All amounts must include token decimals

  2. Always check minimum transfer amounts

  3. Monitor transactions until complete

  4. Some routes may require additional swaps on destination chain

PreviousCross-Chain APINextAPI