DEX API
Cross-chain swap

Cross-chain swap#

Generate the data to execute a cross-chain swap.

Request address#

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

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.
userWalletAddressStringYesUser’s wallet address, AA wallet address does not support cross-chain swap (e.g., 0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9)
allowBridgeArrayNoSpecify bridge that should be included in routes (e.g.,[211,235])
denyBridgeArrayNoSpecify bridge that should be excluded in routes (e.g.,[211,235])
receiveAddressStringNoReceive address of a bought token if not set, the userWalletAddress will receive a bought token. TRON, SUI and other non-EVM chains need to set a receiving address (e.g., 0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
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
referrerAddressStringNoReferrer address (e.g. 0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9)
The fromToken address that receives the referrer fee. When using the API, the fee rate can be adjusted by adding feePercent.
Note: This doesn’t support transactions involving wrapped tokens such as those between ETH and WETH.
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.
onlyBridgebooleanNoCross-chain transactions are executed directly through the bridge, without making a source-chain swap or a destination-chain swap.
memoStringNoYou can customize the parameters carried in /build-tx by encoding the data into a 128-character 64-byte hexadecimal string. This can be queried through the /status API.

Response param#

ParameterTypeDescription
fromTokenAmountStringThe input amount of a token to be sold
(Quantity needs to include accuracy. e.g., 1.00 USDT set as 1000000)
toTokenAmountStringThe resulting amount of a token to be bought
(Quantity needs to include accuracy. e.g., 1.00 USDT set as 1000000)
minmumReceiveStringThe minimum amount of a token to buy when the price reaches maximum slippage
routerObjectBridge information
bridgeIdIntegerBridge ID (e.g., 211)
bridgeNameStringName of bridge (e.g.,cBridge)
otherNativeFeeStringSome 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.
crossChainFeeStringThe cross-chain bridge fee is charged by the bridge, usually in stablecoin or WETH
crossChainFeeTokenAddressStringThe cross-chain bridge fee token information (e.g., 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE represents the native token address)
txObjectOn chain transaction data
dataStringInputData on chian
fromStringUser’s wallet address (e.g., 0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9)
toStringThe referrer's address (e.g., 0x6dc1fb08decf9f95a01222baa359aa0e02e07716)
valueStringThe amount of native tokens (in wei) that will be sent to the contract address (e.g., 0)
gasLimitString(Optional, The gas (in wei) for the swap transaction. If the value is too low to achieve the quote, an error will be returned (e.g., 50000)
gasPriceStringGas price in wei (e.g., 110000000)
maxPriorityFeePerGasStringEIP-1559: Recommended priority cost of gas per unit (e.g., 500000000)
randomKeyAccountArrayThe randomKeyAccount parameter is not required for every transaction. It is only generated and returned during certain special transactions, such as when using the CCTP bridge for cross-chain token transfers. When this parameter is provided, you must use it along with the user’s wallet private key for multi-signature operations to ensure the transaction is secure and successfully completed. Click here to view a multi-signature example)
signatureDataArrayIf this parameter is returned, it indicates that the transaction requires additional signing data. Developers should use this parameter as one of the inputs for the transaction signature and ensure it is correctly applied during the signing process.

Request example#

shell
curl --location --request GET 'https://www.okx.com/api/v5/dex/cross-chain/build-tx?amount=15&fromChainId=324&toChainId=42161&fromTokenAddress=0x3355df6d4c9c3035724fd0e3914de96a5a83aaf4&toTokenAddress=0xff970a61a04b1ca14834a43f5de4533ebddb5cc8&slippage=0.07&userWalletAddress=0x22497668Fb12BA21E6A132de7168D0Ecc69cDF7d&feePercent=1&referrerAddress=0x3f6a3f57569358a512ccc0e513f171516b0fd42a' \
--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,
  "msg":"",
  "data":
    [
      {
        "fromTokenAmount": "1000000000000",
        "router": {
            "bridgeId": 235,
            "bridgeName": "swft",
            "crossChainFee": "4.67131461",
            "otherNativeFee": "1.50000000",
            "crossChainFeeTokenAddress":"0x7ceb23fd6bc0add59e62ac25578270cff1b9f619",

       },
        "toTokenAmount": "1000000000000",
        "minmumReceive": "1000000000000",
        "tx":{
            "data":"0xc748673057861a797275cd8a068abb95a902e8de",
            "from":"xxxxxxxxxxx",
            "to":"0x6dc1fb08decf9f95a01222baa359aa0e02e07716",
            "value":0,
            "gasLimit":"442621",
            "gasPrice":"3192374970",
            "maxPriorityFeePerGas":"3579"
          }
       }
    ]
}