Simulate Route Swap
This endpoint allows users to preview the results of a multi-hop swap through a sequence of liquidity pools without executing the transaction. It calculates expected outputs, fees, and price impacts across the entire route.
Simulation Process
- Load all pools in the route into memory
- Validate asset pairs match between consecutive hops
- Simulate each swap sequentially using current reserves
- Calculate cumulative fees and price impacts
- Apply slippage protection to determine viability
- Return detailed breakdown without modifying state
Multi-Hop Calculation
The simulation executes virtually through each pool:
- Each hop’s output becomes the next hop’s input
- Fees are deducted at each step, compounding through route
- Price impact accumulates across all hops
- Final output reflects all fees and slippage
Route Validation
Before simulation, the system validates:
- Minimum 2 hops required (use regular swap for single hop)
- Maximum 4 hops allowed (to prevent excessive complexity)
- All pools exist and have sufficient liquidity
- Asset pairs are correctly chained (hop[n].output = hop[n+1].input)
- Maximum slippage tolerance is reasonable (0-100%)
Price Impact Analysis
The simulation provides detailed impact metrics:
- Per-hop impact: Price movement in each individual pool
- Cumulative impact: Total price degradation across route
- Warning threshold: Alerts when impact exceeds 5%
- Impact increases with trade size relative to pool liquidity
Fee Breakdown
Simulation calculates all fees separately:
- LP fees: Fees paid to liquidity providers at each pool
- Host fees: Platform fees for each pool’s host
- Total fees: Sum of all fees across the route
- Fees compound (each reduces next hop’s input amount)
Execution Price
The execution price represents:
- Effective exchange rate:
output_amount/input_amount - Includes all fees and price impacts
- Comparable to direct pair pricing for arbitrage detection
Use Cases
Route simulation is useful for:
- Finding optimal paths between assets without direct pairs
- Comparing routes for best execution
- Estimating costs before committing funds
- Detecting arbitrage opportunities
- Understanding fee impact on large trades
No Authentication Required
Simulations are read-only operations that don’t modify pool state or require authentication. Anyone can simulate routes.
Arguments
hops- Ordered sequence of pools and assets defining the routeamount_in- Initial amount to swap through the routemax_route_slippage_bps- Maximum acceptable slippage in basis points
Returns
200 OKwith detailed simulation results and per-hop breakdown400 Bad Requestif route validation fails or pools don’t exist500 Internal Server Errorif simulation calculation fails
Body
Route simulation details including hop sequence and input amount
Defines the request for simulating a swap across a defined route of liquidity pools.
An ordered sequence of pools and assets that defines the swap route. Must contain at least 2 hops and no more than 4 hops.
[
{
"assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
"assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
"poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
},
{
"assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
"assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
"poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
}
]The total amount of the input asset to be swapped, in its smallest unit.
x >= 0100000000
The maximum acceptable slippage for the entire route, in basis points (0-10000).
x >= 0100
Response
Route simulation successful
Represents the complete simulation result for the requested route swap.
The estimated final amount of the output asset to be received, in its smallest unit.
x >= 0The estimated effective price of the swap, calculated as output_amount / input_amount.
The total estimated fees paid to liquidity providers across all hops.
x >= 0The total estimated fees paid to pool hosts across all hops.
x >= 0The total estimated price impact for the entire route as a percentage string.
A detailed breakdown of the simulation results for each hop in the route.
An optional warning message, e.g., if the calculated slippage exceeds the user's maximum setting.