DEX API
Get route information

Get route information#

Find the best route for a cross-chain swap through OKX’s DEX cross-chain aggregator.

Request address#

GET https://www.okx.com/api/v5/dex/cross-chain/quote

Request param#

ParameterTypeRequiredDescription
fromChainIdStringYesSource chain ID (e.g., 1 for Ethereum. See Chain IDs)
toChainIdStringYesDestination chain ID (e.g., 1 for Ethereum. See Chain IDs)
fromTokenAddressStringYesThe contract address of a token to be sold (e.g., 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE )
toTokenAddressStringYesThe contract address of a token to be bought (e.g., TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8)
amountStringYesThe input amount of a token to be sold (set in minimal divisible units, e.g., 1.00 USDT set as 1000000, 1.00 DAI set as 1000000000000000000),you could get the minimal divisible units from Tokenlist.
sortIntegerNoCross-chain swap routes

0 is the default route that would get you the most tokens.

1 is the optimal route after calculating the received amount, network fees, slippage, and cross-chain bridge costs.

2 is the quickest route with the least swap time.
slippageStringYesThe slippage you are willing to accept. If you set 0.5, it means 50% slippage is acceptable. min:0.002 max:0.5
1. If you're bridging the same token Y from A chain to B chain, we suggest 0.002.
2. If you're bridging the token X from A chain to B chain and swap to token Y, we suggest 0.01 - 0.025, depending on the token trading volume.
feePercentStringNoThe percentage of fromTokenAmount will be sent to the referrer's address, the rest will be set as the input amount to be sold. min percentage:0 max percentage:3
allowBridgeArrayNoSpecify bridge that should be included in routes (e.g.,[211,235])
denyBridgeArrayNoSpecify bridge that should be excluded in routes (e.g.,[211,235])
priceImpactProtectionPercentageStringNo(Optional. The default is 90%.) The percentage (between 0 - 1.0) of the price impact allowed.

When the priceImpactProtectionPercentage is set, if the estimated price impact is above the percentage indicated, an error will be returned. For example, if PriceImpactProtectionPercentage = .25 (25%), any quote with a price impact higher than 25% will return an error.

This is an optional feature, and the default value is 0.9. When it’s set to 1.0 (100%), the feature will be disabled, which means that every transaction will be allowed to pass.

Note: If we’re unable to calculate the price impact, we’ll return null, and the price impact protection will be disabled.

Response param#

ParameterTypeRequiredDescription
fromChainIdStringYesSource chain ID (e.g., 1 for Ethereum. See Chain IDs)
toChainIdStringYesDestination chain ID (e.g., 1 for Ethereum. See Chain IDs)
fromTokenAmountStringYesThe input amount of a token to be sold (e.g.,500000000000000000000000)
fromTokenObjectYesThe information of a token to be sold
decimalsIntegerYesThe precision of tokens (e.g.,18)
tokenContractAddressStringYesToken contract address (e.g.,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2)
tokenSymbolStringYesToken symbol (e.g.,USDC)
toTokenObjectYesThe information of a token to be bought
decimalsIntegerYesThe precision of tokens (e.g.,18)
tokenContractAddressStringYesToken contract address (e.g.,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2)
tokenSymbolStringYesToken symbol (e.g.,WETH)
routerListArrayYesQuote path data set
routerObjectYesBridge information
bridgeIdIntegerYesBridge ID (e.g.,211)
bridgeNameStringYesName of bridge (e.g.,cBridge)
otherNativeFeeStringYesSome cross-chain bridges charge a certain amount of the native tokens from the source chain as a cross-chain bridge fee. Not all cross-chain bridges charge such a fee. These are the current ones that charge bridge fees: Stargate, Wanchain, Arbitrum’s official network, zkSync Era’s official network, and Linea’s official network. otherNativeFee is required to be paid using these bridges to finish the transaction.
crossChainFeeStringYesThe cross-chain bridge fee is charged by the bridge, usually in stablecoin or WETH
crossChainFeeTokenAddressStringYesThe cross-chain bridge fee token information (e.g., 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE represents the native token address)
estimateGasFeeStringYesThe recommended gas limit for calling the contract
estimatedTimeStringYes2. The estimated time to complete the cross-chain swap is displayed in seconds and dynamically calculated based on historical completion times of successful transactions.
fromDexRouterListArrayNoSource chain swap information. If there is no source chain swap, the return value will be empty.
percentStringYesThe percentage of assets handled by the protocol (e.g.,100)
routerStringYesOne of the main paths for the token swap
subRouterListArrayYesDEX Router information
dexNameStringYesThe name of the liquidity protocol (e.g.,100)
percentStringYesThe percentage of assets handled by the protocol
fromTokenObjectYesThe information of a token to be sold
decimalsIntegerYesThe precision of tokens (e.g.,18)
tokenContractAddressStringYesToken contract address (e.g.,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2)
tokenSymbolStringYesToken symbol (e.g.,WETH)
toTokenObjectYesThe information of a token to be bought
decimalsIntegerYesThe precision of tokens (e.g.,18)
tokenContractAddressStringYesToken contract address (e.g.,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2)
tokenSymbolStringYesToken symbol (e.g.,USDC)
toDexRouterListArrayNoDestination chain’s swap route information. If there is no source chain swap, the return value will be empty.
percentStringYesThe percentage of assets handled by the protocol (e.g.,100)
routerStringYesOne of the main paths for the token swap
subRouterListArrayYesDEX Router information
dexNameStringYesThe name of the liquidity protocol
percentStringYesThe percentage of assets handled by the protocol (e.g.,100)
fromTokenObjectYesThe information of a token to be sold
decimalsIntegerYesThe precision of tokens (e.g.,18)
tokenContractAddressStringYesToken contract address (e.g.,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2)
tokenSymbolStringYesToken symbol (e.g.,WETH)
toTokenObjectYesThe information of a token to be bought
decimalsIntegerYesThe precision of tokens (e.g.,6)
tokenContractAddressStringYesToken contract address (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
tokenSymbolStringYesToken symbol (e.g.,USDC)
fromChainNetworkFeeStringYesEstimated source-chain network fee for the quote route, displayed in the source token’s precision
toChainNetworkFeeStringYesEstimated destination-chain network fee for the quote route, displayed in the source token’s precision
minimumReceivedStringYesThe minimum amount of a token to buy when the price reaches maximum slippage
needApproveIntegerYesIf approval is needed
toTokenAmountStringYesThe resulting amount of a token to be bought

Request example#

shell
curl --location --request GET 'https://www.okx.com/api/v5/dex/cross-chain/quote?amount=15&fromChainId=324&toChainId=42161&fromTokenAddress=0x3355df6d4c9c3035724fd0e3914de96a5a83aaf4&toTokenAddress=0xff970a61a04b1ca14834a43f5de4533ebddb5cc8&slippage=0.07' \
--header 'OK-ACCESS-PROJECT: 86af********d1bc' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z'

Response example#

200
{
  "code":"0",
  "data":[
{
  "fromChainId":"56",
  "fromToken":{
  "decimals":18,
  "tokenContractAddress":"0x55d398326f99059ff775485246999027b3197955",
  "tokenSymbol":"USDT"
},
  "fromTokenAmount":"30000000000000000000",
  "routerList":[
{
  "estimateTime":"290",
  "fromDexRouterList":[
{
  "router":"0x55d398326f99059ff775485246999027b3197955--0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c--0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
  "routerPercent":"100",
  "subRouterList":[
{
  "dexProtocol":[
{
  "dexName":"Uniswap V3",
  "percent":"100"
}
  ],
  "fromToken":{
  "decimals":18,
  "tokenContractAddress":"0x55d398326f99059ff775485246999027b3197955",
  "tokenSymbol":"USDT"
},
  "toToken":{
  "decimals":18,
  "tokenContractAddress":"0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
  "tokenSymbol":"WBNB"
}
},
{
  "dexProtocol":[
{
  "dexName":"Uniswap V3",
  "percent":"100"
}
  ],
  "fromToken":{
  "decimals":18,
  "tokenContractAddress":"0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
  "tokenSymbol":"WBNB"
},
  "toToken":{
  "decimals":18,
  "tokenContractAddress":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
  "tokenSymbol":"USDC"
}
}
  ]
}
  ],
  "minimumReceived":"28635611",
  "needApprove":1,
  "router":{
  "bridgeId":235,
  "bridgeName":"swft",
  "crossChainFee":"1.090044714717251827012",
  "crossChainFeeTokenAddress":"0x7ceb23fd6bc0add59e62ac25578270cff1b9f619",
  "otherNativeFee":"0"
},
  "toDexRouterList":[
{
  "router":"0x7ceb23fd6bc0add59e62ac25578270cff1b9f619--0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "routerPercent":"100",
  "subRouterList":[
{
  "dexProtocol":[
{
  "dexName":"Uniswap V3",
  "percent":"100"
}
  ],
  "fromToken":{
  "decimals":18,
  "tokenContractAddress":"0x7ceb23fd6bc0add59e62ac25578270cff1b9f619",
  "tokenSymbol":"WETH"
},
  "toToken":{
  "decimals":18,
  "tokenContractAddress":"0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270",
  "tokenSymbol":"WMATIC"
}
}
  ]
}
  ],
  "toTokenAmount":"28924860"
}
  ],
  "toChainId":"42161",
  "toToken":{
  "decimals":6,
  "tokenContractAddress":"0xff970a61a04b1ca14834a43f5de4533ebddb5cc8",
  "tokenSymbol":"USDC.e"
}
}
  ],
  "msg":""
}