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)
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.
fromTokenReferrerWalletAddress	String	Optional	The wallet address to receive the commission fee from the `fromToken`. This new field no longer requires a token account parameter for SPL-Token; specifying the Sol wallet address is sufficient. When using the API, the commission rate needs to be set with `feePercent`. For a single transaction, only the `fromToken` or `toToken` commission can be chosen. This does not support transactions involving wrapped token pairs, such as transactions between SOL and WSOL, or ETH and WETH.
toTokenReferrerWalletAddress	String	Optional	The wallet address to receive the commission fee from the `toToken`. This new field no longer requires a token account parameter for SPL-Token. When using the API, the commission rate needs to be set with `feePercent`. For a single transaction, only the `fromToken` or `toToken` commission can be chosen. This does not support transactions involving wrapped token pairs, such as transactions between SOL and WSOL, or ETH and WETH.

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`)
estimateGasFee	String	The recommended gas limit for calling the contract
dexRouterList	Array	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	Array	Quote path sub data set
dexProtocol	Array	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
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.
quoteCompareList	Array	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
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.
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",
                        "from": "0x6f9ffea7370310cd0f890dfde5e0e061059dcfd9",
                        "gas": "202500",
                        "gasPrice": "18522500000",
                        "maxPriorityFeePerGas": "500000000",
                        "minReceiveAmount": "3",
                        "to": "0xf3de3c0d654fda23dad170f0f320a92172509127",
                        "value": "1000000000"
                  }
            }
      ],
      "msg": ""
}