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#
| Parameter | Type | Required | Description |
|---|---|---|---|
| fromChainId | String | Yes | Source chain ID (e.g., 1 for Ethereum. See Chain IDs) |
| toChainId | String | Yes | Destination chain ID (e.g., 1 for Ethereum. See Chain IDs) |
| fromTokenAddress | String | Yes | The contract address of a token to be sold (e.g., 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE ) |
| toTokenAddress | String | Yes | The contract address of a token to be bought (e.g., TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8) |
| amount | String | Yes | The 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. |
| sort | Integer | No | Cross-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. |
| slippage | String | Yes | The 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. |
| userWalletAddress | String | Yes | User’s wallet address, AA wallet address does not support cross-chain swap (e.g., 0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9) |
| allowBridge | Array | No | Specify bridge that should be included in routes (e.g.,[211,235]) |
| denyBridge | Array | No | Specify bridge that should be excluded in routes (e.g.,[211,235]) |
| receiveAddress | String | No | Receive 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) |
| feePercent | String | No | The 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 |
| referrerAddress | String | No | Referrer 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: 1. For EVM chains: This feature doesn’t support transactions involving wrapped tokens such as those between ETH and WETH. 2. For Solana: The referral address needs to have some SOL deposited in advance to activate it. |
| priceImpactProtectionPercentage | String | No | (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. |
| onlyBridge | boolean | No | Cross-chain transactions are executed directly through the bridge, without making a source-chain swap or a destination-chain swap. |
| memo | String | No | You 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#
| Parameter | Type | Description |
|---|---|---|
| fromTokenAmount | String | The input amount of a token to be sold (Quantity needs to include accuracy. e.g., 1.00 USDT set as 1000000) |
| toTokenAmount | String | The resulting amount of a token to be bought (Quantity needs to include accuracy. e.g., 1.00 USDT set as 1000000) |
| minmumReceive | String | The minimum amount of a token to buy when the price reaches maximum slippage |
| router | Object | Bridge information |
| bridgeId | Integer | Bridge ID (e.g., 211) |
| bridgeName | String | Name of bridge (e.g.,cBridge) |
| otherNativeFee | String | Some 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. |
| crossChainFee | String | The cross-chain bridge fee is charged by the bridge, usually in stablecoin or WETH |
| crossChainFeeTokenAddress | String | The cross-chain bridge fee token information (e.g., 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE represents the native token address) |
| tx | Object | On chain transaction data |
| data | String | InputData on chian |
| from | String | User’s wallet address (e.g., 0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9) |
| to | String | The referrer's address (e.g., 0x6dc1fb08decf9f95a01222baa359aa0e02e07716) |
| value | String | The amount of native tokens (in wei) that will be sent to the contract address (e.g., 0) |
| gasLimit | String | (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) |
| gasPrice | String | Gas price in wei (e.g., 110000000) |
| maxPriorityFeePerGas | String | EIP-1559: Recommended priority cost of gas per unit (e.g., 500000000) |
| randomKeyAccount | Array | The 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) |
| signatureData | Array | If 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"
}
}
]
}