Swap#
Generate the data to call the OKX DEX router to execute a swap.
Request address#
GET https://www.okx.com/api/v5/dex/aggregator/swap
Request param#
| Parameter | Type | Required | Description |
|---|---|---|---|
| chainId | String | Yes | Chain ID (e.g., 1 for Ethereum. See Chain IDs) |
| 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. |
| fromTokenAddress | String | Yes | The contract address of a token you want to send (e.g.,0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee) |
| toTokenAddress | String | Yes | The contract address of a token you want to receive (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) |
| slippage | String | Yes | The slippage you are willing to accept. If you set 0.5, it means 50% slippage is acceptable. min:0 max:1 |
| userWalletAddress | String | Yes | User's wallet address (e.g.,0x3f6a3f57569358a512ccc0e513f171516b0fd42a) |
| referrerAddress | String | No | Referrer address (Supports SOL or SPL-Token commissions. SOL commissions use wallet address, and SPL-Token commissions use token account.) The fromToken address that receives the commission. 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 SOL and WSOL. In a single transaction, either a fromToken commission or a toToken commission can be selected. |
| swapReceiverAddress | String | No | recipient address of a purchased token if not set, userWalletAddress will receive a purchased token (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 |
| gaslimit | String | No | (Optional, The gas (in wei) for the swap transaction. If the value is too low to achieve the quote, an error will be returned |
| gasLevel | String | No | (Optional, defaults to average) The target gas price level for the swap transaction,set to average or fast or slow |
| dexIds | String | No | DexId of the liquidity pool for limited quotes, multiple combinations separated by , (e.g., 1,50,180, see liquidity list for more) |
| solTokenAccountAddress | String | No | Account address for toToken in solana transactions, Get method reference |
| 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. |
| callDataMemo | String | No | You can customize the parameters to be sent on the blockchain in callData by encoding the data into a 128-character 64-bytes hexadecimal string. For example, the string “0x111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111” needs to keep the “0x” at its start. |
| toTokenReferrerAddress | String | No | toToken referrer address (Only supports SPL-Token commissions which use token account.) The toToken address that receives the commission. 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 SOL and WSOL. In a single transaction, either a fromToken commission or a toToken commission can be selected. |
| computeUnitPrice | String | No | Used for transactions on the Solana network and similar to gasPrice on Ethereum. This price determines the priority level of the transaction. The higher the price, the more likely that the transaction can be processed faster. |
| computeUnitLimit | String | No | Used for transactions on the Solana network and analogous to gasLimit on Ethereum, which ensures that the transaction won’t take too much computing resource. |
Response param#
| Parameter | Type | Description |
|---|---|---|
| routerResult | Object | Quote path data |
| chainId | String | Chain ID (e.g., 1 for Ethereum. See Chain IDs) |
| fromTokenAmount | String | The input amount of a token to be sold ( e.g.,500000000000000000000000) |
| toTokenAmount | String | The resulting amount of a token to be bought ( e.g.,168611907733361) |
| dexRouterList | Object[] | Quote path data set |
| router | String | One of the main paths for the token swap |
| routerPercent | String | The percentage of assets handled by the main path (e.g.,5) |
| subRouterList | Object[] | Quote path sub data set |
| dexProtocol | Object[] | Liquidity protocols used on the main path |
| dexName | String | The name of the liquidity protocol (e.g.,Verse) |
| percent | String | The percentage of assets handled by the protocol (e.g.,100) |
| fromToken | Object | The information of a token to be sold |
| tokenContractAddress | String | Token contract address (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) |
| tokenSymbol | String | Token symbol (e.g.,USDC) |
| tokenUnitPrice | String | The token unit price returned by this interface is a general USD price based on data from on-chain, exchange, and other third-party sources. Note: This price is only a recommended price. For some special cases, the token unit price may be 'null' |
| decimal | String | The decimal number defines the smallest unit into which a single currency token can be divided. For example, if the decimal number of a token is 8, it means that a single such token can be divided into 100,000,000 of its smallest units. Note: This parameter is for reference only. It may change due to reasons such as settings adjustments by the contract owner. |
| toToken | Object | The information of a token to be bought |
| quoteCompareList | Object[] | Comparison of quote routes |
| dexName | String | DEX name of the quote route |
| dexLogo | String | DEX logo of the quote route |
| tradeFee | String | Estimated network fee (USD) of the quote route |
| receiveAmount | String | Received amount of the quote route |
| tx | Object | contract data model |
| from | String | User's wallet address (e.g.,0x3f6a3f57569358a512ccc0e513f171516b0fd42a) |
| gas | String | estimated amount of the gas limit, increase this value by 50% (e.g.,1173250) |
| gasPrice | String | Gas price in wei (e.g.,58270000000) |
| maxPriorityFeePerGas | String | EIP-1559: Recommended priority cost of gas per unit (e.g.,500000000) |
| to | String | The contract address of OKX DEX router (e.g.,0x3b3ae790Df4F312e745D270119c6052904FB6790) |
| value | String | The amount of native tokens (in wei) that will be sent to the contract address (e.g.,0) |
| minReceiveAmount | String | The minimum amount of a token to buy when the price reaches the upper limit of slippage (e.g.,900645839798) |
| data | String | Call data |
Request example#
shell
curl --location --request GET 'https://www.okx.com/api/v5/dex/aggregator/swap?chainId=1&amount=1000000000&toTokenAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&fromTokenAddress=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&slippage=0.05&userWalletAddress=0x6f9ffea7370310cd0f890dfde5e0e061059dcfb8' \
--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": [
{
"routerResult": {
"chainId": "1",
"dexRouterList": [
{
"router": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee--0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"routerPercent": "100",
"subRouterList": [
{
"dexProtocol": [
{
"dexName": "Uniswap V3",
"percent": "100"
}
],
"fromToken": {
"decimal": "18",
"tokenContractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"tokenSymbol": "WETH",
"tokenUnitPrice": "3091.9471418658263"
},
"toToken": {
"decimal": "6",
"tokenContractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"tokenSymbol": "USDC",
"tokenUnitPrice": "0.9969978613218498"
}
}
]
}
],
"estimateGasFee": "135000",
"fromToken": {
"decimal": "18",
"tokenContractAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
"tokenSymbol": "ETH",
"tokenUnitPrice": "3083.81"
},
"fromTokenAmount": "1000000000",
"quoteCompareList": [
{
"amountOut": "0.000003",
"dexLogo": "https://static.okx.com/cdn/wallet/logo/balancer.png",
"dexName": "Balancer V1",
"tradeFee": "23.169955019"
},
{
"amountOut": "0.000000",
"dexLogo": "https://static.okx.com/cdn/wallet/logo/DODO.png",
"dexName": "DODO",
"tradeFee": "19.322545514"
},
{
"amountOut": "0.000003",
"dexLogo": "https://static.okx.com/cdn/wallet/logo/Curve.png",
"dexName": "Curve TNG",
"tradeFee": "12.055216449"
},
{
"amountOut": "0.000003",
"dexLogo": "https://static.okx.com/cdn/wallet/logo/dex_Maverick.png",
"dexName": "Maverick V1",
"tradeFee": "10.772746614"
},
{
"amountOut": "0.000003",
"dexLogo": "https://static.okx.com/cdn/wallet/logo/balancer.png",
"dexName": "Balancer V2",
"tradeFee": "10.345256669"
}
],
"toToken": {
"decimal": "6",
"tokenContractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"tokenSymbol": "USDC",
"tokenUnitPrice": "0.9969978613218498"
},
"toTokenAmount": "3"
},
"tx": {
"data": "0x0d5f0e3b0000000000000000000187036f9ffea7370310cd0f890dfde5e0e061059dcfd9000000000000000000000000000000000000000000000000000000003b9aca0000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000180000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"estimateErrorMsg": "",
"from": "0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9",
"gas": "202500",
"gasPrice": "18522500000",
"isEstimateError": false,
"maxPriorityFeePerGas": "500000000",
"minReceiveAmount": "3",
"to": "0xf3de3c0d654fda23dad170f0f320a92172509127",
"value": "1000000000"
}
}
],
"msg": ""
}