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 | Integer | Yes | Source chain ID (e.g., 1 for Ethereum. See Chain IDs) |
| toChainId | Integer | 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 | Integer[] | No | Specify bridge that should be included in routes (e.g.,[211,235]) |
| denyBridge | Integer[] | 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: This doesn’t support transactions involving wrapped tokens such as those between ETH and WETH. |
| 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 | BigInteger | 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) |
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"
}
}
]
}