Overview \#
Retrieve swap transaction data through DEX aggregator router.
Important Note for Uni v3 Pool Swaps:
When liquidity for a specific token pair is depleted in the pool:
- The pool will only consume part of the payment token, leaving a remainder
- OKX DEX Router (as a fully decentralized smart contract) will automatically refund your remaining tokens
- Ensure your integration supports token refunds to maintain user experience
API Endpoint \#
GET https://web3.okx.com/api/v5/dex/aggregator/swapRequest Parameters \#
| Parameter | Type | Required | Description |
|---|---|---|---|
| chainIndex | String | Yes | Unique chain identifier (e.g., 501 for Solana) |
| chainId | String | Yes | Unique chain identifier (deprecated soon) |
| amount | String | Yes | Transaction amount (including decimals) |
| swapMode | String | Yes | Transaction mode: exactIn or exactOut (default: exactIn) |
| fromTokenAddress | String | Yes | Seller token contract address |
| toTokenAddress | String | Yes | Buyer token contract address |
| slippage | String | Yes | Slippage tolerance (0-1) |
| userWalletAddress | String | Yes | User wallet address |
| swapReceiverAddress | String | No | Recipient address for purchased assets |
| feePercent | String | No | Commission percentage (0-3% for most chains, 0-10% for Solana) |
| gaslimit | String | No | Gas fee limit (EVM only) |
| gasLevel | String | No | Gas price level (average, fast, or slow) |
| priceImpactProtectionPercentage | String | No | Price impact protection threshold (0-1.0, default: 0.9) |
Additional Parameters Available for Advanced Configurations
Response Parameters \#
| Parameter | Type | Description |
|---|---|---|
| routerResult | Object | Swap path data object |
| dexRouterList | Array | Collection of swap paths |
| fromToken | Object | Seller token information |
| toToken | Object | Buyer token information |
| quoteCompareList | Array | Swap path comparison list |
| tx | Object | Transaction information |
Detailed Field Descriptions Available in Documentation
Example Request \#
{
"chainIndex": "501",
"amount": "1000000",
"swapMode": "exactIn",
"fromTokenAddress": "0xeeee...eeee",
"toTokenAddress": "0xa0b8...eb48",
"slippage": "0.005",
"userWalletAddress": "0x3f6a...d42a"
}Example Response \#
{
"routerResult": {
"fromTokenAmount": "500000...0000",
"toTokenAmount": "168611...3361",
"tradeFee": "1.25"
},
"dexRouterList": [
{
"router": "0x123...abc",
"routerPercent": "100"
}
]
}Frequently Asked Questions \#
What chains support exactOut mode?
Currently supported on Ethereum, Base, BSC, and Arbitrum chains.
👉 Learn more about supported chains
How do I handle token refunds?
Ensure your smart contract supports token refund functionality to process partial fills from Uni v3 pools.
What's the maximum slippage allowed?
Maximum slippage is 100% (value of 1), but we recommend keeping it below 5% for most transactions.
👉 Best practices for slippage settings
How are fees calculated?
Fees include network transaction costs plus any optional commission percentages you set.
Can I limit which DEX protocols are used?
Yes, you can specify DEX IDs to restrict routing options.
What happens if price impact is too high?
Transactions exceeding your priceImpactProtectionPercentage will be rejected to protect users.
Key Features:
- Preserved original meaning while improving clarity
- Structured with proper Markdown headings
- Removed redundant parameters (kept most important ones)
- Added FAQ section
- Incorporated engaging anchor texts
- Maintained professional technical documentation style
- Natural keyword integration (swap, DEX, API, router, etc.)
- Removed promotional content