DEX API

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#

ParameterTypeRequiredDescription
chainIdStringYesChain ID (e.g., 1 for Ethereum. See Chain IDs)
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.
fromTokenAddressStringYesThe contract address of a token you want to send (e.g.,0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)
toTokenAddressStringYesThe contract address of a token you want to receive (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
slippageStringYesThe slippage you are willing to accept. If you set 0.5, it means 50% slippage is acceptable. min:0 max:1
userWalletAddressStringYesUser's wallet address (e.g.,0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
referrerAddressStringNoReferrer 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.
swapReceiverAddressStringNorecipient address of a purchased token if not set, userWalletAddress will receive a purchased token (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
gaslimitStringNo(Optional, The gas (in wei) for the swap transaction. If the value is too low to achieve the quote, an error will be returned
gasLevelStringNo(Optional, defaults to average) The target gas price level for the swap transaction,set to average or fast or slow
dexIdsStringNoDexId of the liquidity pool for limited quotes, multiple combinations separated by , (e.g., 1,50,180, see liquidity list for more)
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.
callDataMemoStringNoYou 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.
toTokenReferrerAddressStringNotoToken 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.
computeUnitPriceStringNoUsed 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.
computeUnitLimitStringNoUsed 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#

ParameterTypeDescription
routerResultObjectQuote path data
chainIdStringChain ID (e.g., 1 for Ethereum. See Chain IDs)
fromTokenAmountStringThe input amount of a token to be sold ( e.g.,500000000000000000000000)
toTokenAmountStringThe resulting amount of a token to be bought ( e.g.,168611907733361)
estimateGasFeeStringThe recommended gas limit for calling the contract
dexRouterListArrayQuote path data set
routerStringOne of the main paths for the token swap
routerPercentStringThe percentage of assets handled by the main path (e.g.,5)
subRouterListArrayQuote path sub data set
dexProtocolArrayLiquidity protocols used on the main path
dexNameStringThe name of the liquidity protocol (e.g.,Verse)
percentStringThe percentage of assets handled by the protocol (e.g.,100)
fromTokenObjectThe information of a token to be sold
tokenContractAddressStringToken contract address (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
tokenSymbolStringToken symbol (e.g.,USDC)
tokenUnitPriceStringThe 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'
decimalStringThe 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.
toTokenObjectThe information of a token to be bought
tokenContractAddressStringToken contract address (e.g.,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
tokenSymbolStringToken symbol (e.g.,USDC)
tokenUnitPriceStringThe 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'
decimalStringThe 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.
quoteCompareListArrayComparison of quote routes
dexNameStringDEX name of the quote route
dexLogoStringDEX logo of the quote route
tradeFeeStringEstimated network fee (USD) of the quote route
receiveAmountStringReceived amount of the quote route
txObjectcontract data model
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.
fromStringUser's wallet address (e.g.,0x3f6a3f57569358a512ccc0e513f171516b0fd42a)
gasStringestimated amount of the gas limit, increase this value by 50% (e.g.,1173250)
gasPriceStringGas price in wei (e.g.,58270000000)
maxPriorityFeePerGasStringEIP-1559: Recommended priority cost of gas per unit (e.g.,500000000)
toStringThe contract address of OKX DEX router (e.g.,0x3b3ae790Df4F312e745D270119c6052904FB6790)
valueStringThe amount of native tokens (in wei) that will be sent to the contract address (e.g.,0)
minReceiveAmountStringThe minimum amount of a token to buy when the price reaches the upper limit of slippage (e.g.,900645839798)
dataStringCall 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": ""
}