The decentralized exchange (DEX) landscape continues to evolve, with users demanding faster, more efficient, and cost-effective token swaps across multiple chains. To meet this demand, developers need powerful tools that simplify cross-chain trading logic while maintaining full decentralization and security. The OKX DEX Aggregator Swap API delivers exactly that—offering a robust, scalable solution for integrating seamless token swaps into web3 applications.
This guide explores the core functionality, request and response parameters, and best practices for leveraging the Swap API effectively. Whether you're building a wallet, DeFi dashboard, or trading platform, this documentation equips you with everything needed to implement high-performance swap features.
How the DEX Aggregator Swap API Works
The OKX DEX Aggregator Swap API enables developers to retrieve optimized trade data by querying liquidity from multiple decentralized exchanges through a single endpoint. It acts as a smart routing engine that finds the most efficient path for token conversion across supported blockchains.
At its core, the API returns transaction calldata and metadata required to execute a swap on-chain via the OKX DEX Router—a fully decentralized smart contract system. This ensures users retain control over their assets while benefiting from aggregated liquidity and competitive pricing.
👉 Discover how easy it is to integrate smart swap routing into your app.
Key Features
- Multi-chain support: Includes Ethereum, Solana, BSC, Arbitrum, Base, and more.
- Exact input/output modes: Choose between fixed input (
exactIn) or desired output (exactOut). - Slippage protection: Customizable slippage thresholds to protect against volatility.
- Fee sharing: Built-in support for referral commissions in both input and output tokens.
- MEV protection: Optional Jito tips integration for Solana transactions.
- Auto-slippage calculation: Adaptive slippage based on real-time market conditions.
Core Request Parameters
To initiate a swap quote, send a GET request to:
https://web3.okx.com/api/v5/dex/aggregator/swapBelow are the essential parameters:
Required Parameters
| Parameter | Type | Description |
|---|---|---|
chainIndex | String | Unique chain identifier (e.g., 501 for Solana). See supported chains. |
amount | String | Trade amount in raw units (including decimals). Use token precision data from the token list. |
swapMode | String | Either exactIn (default) or exactOut. Note: exactOut is only available on Ethereum, Base, BSC, and Arbitrum using Uni v2/v3 protocols. |
fromTokenAddress | String | Contract address of the token being sold (e.g., 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee). |
toTokenAddress | String | Contract address of the token being bought. |
slippage | String | Maximum allowable slippage (e.g., 0.005 = 0.5%). On EVM chains: 0–1; Solana: must be less than 1. |
userWalletAddress | String | Wallet initiating the swap (e.g., 0x3f6a...fd42a). |
Optional Parameters
Additional settings allow fine-tuning of execution behavior:
swapReceiverAddress: Custom recipient for output tokens.feePercent: Referral fee percentage (up to 3% on most chains, 10% on Solana).fromTokenReferrerWalletAddress/toTokenReferrerWalletAddress: Wallet to receive referral fees (only one can be used per transaction).positiveSlippagePercent: Capture up to 10% of positive slippage gains (Solana only).positiveSlippageFeeAddress: Address to receive positive slippage rewards.gasLimit,gasLevel: Control gas costs on EVM networks.computeUnitPrice,computeUnitLimit,tips: Optimize Solana transaction priority and MEV protection.dexIds: Restrict quotes to specific DEXes (comma-separated IDs).directRoute: Force single-pool routing (Solana only).priceImpactProtectionPercentage: Reject trades exceeding a price impact threshold (default: 90%, disable with 1.0).callDataMemo: Embed custom 64-byte hex metadata in calldata.autoSlippage: Enable dynamic slippage estimation based on market depth.maxAutoSlippage: Cap auto-calculated slippage value for risk management.
Understanding the Response Data
A successful API call returns a structured JSON object containing routing details, pricing info, and transaction data.
Top-Level Fields
routerResult: Main swap quote object.chainIndex,chainId: Network identifiers.fromTokenAmount,toTokenAmount: Input and estimated output amounts in raw units.tradeFee,estimateGasFee: Estimated network cost in USD and native gas units.
Routing Breakdown
dexRouterList: Array of routing paths used.- Each includes
routerPercent, indicating portion of trade routed through that path. - Nested
subRouterListshows intermediate steps. dexProtocollists individual DEX protocols involved (e.g., Uniswap V3).
- Each includes
Token Information
Both input (fromToken) and output (toToken) include:
tokenContractAddress,tokenSymboltokenUnitPrice: Real-time USD value (may be null)decimal: Token precisionisHoneyPot: Detect scam tokens (true/false)taxRate: Sell/buy tax for fee-enabled tokens (e.g., SafeMoon)
Price Comparison & Transaction Data
quoteCompareList: Compare alternative routes by DEX, output amount, and price impact.txobject: Ready-to-sign transaction data:from,to: Sender and router contract addressdata: Calldata for executiongas,gasPrice,maxPriorityFeePerGasminReceiveAmount: Slippage-guarded minimum outputmaxSpendAmount: Max input allowed inexactOutmodesignatureData: Required if additional signatures are needed (e.g., Jito tips)
👉 See how top apps streamline swaps with real-time routing logic.
Handling Edge Cases and Best Practices
Developers should account for several important behaviors:
Partial Execution and Refunds
When using Uni V3 pools, liquidity depletion may result in partial fills. The OKX DEX Router automatically refunds any unused portion of the input token back to the user’s wallet. Ensure your smart contracts support receiving unexpected token returns.
Token Tax Awareness
Tokens like SafeMoon or SPL2022-compliant assets may charge transaction taxes. The API returns taxRate values so your frontend can display accurate net outputs.
Precision Handling
Always use correct token decimals when formatting amounts. Sending "1" USDT actually requires sending 1,000,000 units (6 decimals), while ETH uses 18 decimals.
Frequently Asked Questions
Q: What is the difference between exactIn and exactOut modes?
A: In exactIn, you specify how much you want to spend; the output is estimated. In exactOut, you define the desired output amount; the input required is calculated accordingly. ExactOut is ideal for stablecoin purchases or limit-style orders.
Q: Which chains support the exactOut mode?
A: Currently, only Ethereum, Base, BSC, and Arbitrum support exactOut—and only when routing through Uniswap V2 or V3 pools.
Q: How does autoSlippage work?
A: When enabled, the API calculates optimal slippage based on current pool depth and volatility. You can cap this with maxAutoSlippage to avoid excessive settings during high volatility.
Q: Can I earn referral fees on both input and output tokens?
A: No—only one referral type is allowed per transaction. Choose either fromTokenReferrerWalletAddress or toTokenReferrerWalletAddress.
Q: Why might tokenUnitPrice be null?
A: If the token lacks sufficient trading volume or listing data across sources, pricing may not be available. Always handle null cases gracefully in UIs.
Q: Is the Swap API completely decentralized?
A: Yes—the OKX DEX Router is a non-custodial smart contract. The API provides off-chain quoting, but all funds remain under user control during execution.
Final Thoughts
Integrating decentralized swaps into your application doesn’t have to be complex. With the OKX DEX Aggregator Swap API, developers gain access to deep liquidity, intelligent routing, and advanced trading controls—all through a simple, reliable interface.
Whether you're optimizing gas costs, enabling referral programs, or protecting users from price impact, this API provides the tools needed for professional-grade DeFi experiences.
👉 Start building smarter swaps today—explore seamless integration now.