This endpoint performs a multi-hop swap through a sequence of liquidity pools, allowing users to exchange assets that may not have direct trading pairs. Each hop in the route represents a swap through a different pool.

Route Swap Process

1. User deposits input asset via Spark transfer
2. Submit route swap request with transfer proof and hop sequence
3. System executes swaps sequentially through each pool
4. Each hop’s output becomes the next hop’s input
5. Final output is sent to the user
6. If any hop fails, the entire route is reverted

Multi-Hop Execution

The route is executed atomically:

• All hops must succeed or the entire swap fails
• Intermediate assets are handled internally
• Only initial deposit and final output involve user transfers
• Each hop maintains its own slippage protection

Route Validation

Before execution, the system validates:

• All pools in the route exist and are active
• Asset pairs match between consecutive hops
• Sufficient liquidity exists in each pool
• Total slippage remains within tolerance

Fee Structure

Fees are applied at each hop:

• LP Fees: Paid to liquidity providers of each pool
• Integrator Fees: Optional fees for route providers
• Host Fees: Platform fees for each pool’s host
• Fees compound through the route (each hop’s fee reduces next hop’s input)

Slippage Protection

Two levels of slippage protection:

• Per-hop protection: Each pool enforces its own price limits
• Route-wide protection: Overall output must meet minimum requirement
• max_route_slippage_bps: Maximum acceptable deviation for entire route

Authentication

Requires a valid JWT bearer token. The token’s public key must match the user_public_key in the request. The request must be signed with the user’s private key.

Arguments

• user_public_key - Public key of the user executing the swap
• hops - Ordered list of pools and assets for the route
• initial_spark_transfer_id - Spark transfer proof for input asset
• input_amount - Amount of initial asset to swap
• max_route_slippage_bps - Maximum slippage for entire route
• nonce - Unique value for replay protection
• signature - Request signature for verification
• integrator_fee_rate_bps - Optional default integrator fee
• integrator_public_key - Optional integrator identifier

Returns

• 200 OK with route swap details if successful
• 400 Bad Request if validation fails or route cannot be executed
• 401 Unauthorized if authentication or signature verification fails
• 500 Internal Server Error if route execution fails