GET /api/v1/quote. The API tab is the authoritative reference for arguments, defaults, aliases, bounds, and response schemas. This page explains the decisions behind the result.
1. Resolve the request
Select canonical contract IDs from/api/v1/tokens. Send exactly one atomic integer-string amount: amount_in for a forward quote or amount_out for a reverse quote. Read token decimals instead of assuming them.
Query names are snake_case (amount_in, max_hops, include_paths, referral_id). The server also accepts the camelCase aliases amountIn, amountOut, maxHops, maxSplits, includePaths, and referralId, which is what the TypeScript SDK sends. Unknown parameters are ignored, so a misspelled name is silently dropped rather than rejected.
A pricing request can omit slippage. An executable payload or envelope requires explicit slippage; a value such as 0.01 means 1%. Set fresh=true when the additional live-ledger check is appropriate for confirmation or automated execution.
2. Read the liquidity snapshot
Routing reads indexed pool state. Pool adapters apply the corresponding venue’s pricing rules to candidate swaps. The snapshot makes route comparison possible without requesting every candidate from an external quote API.snapshot.ledger and snapshot.ageSeconds describe the snapshot used. When the live check runs, snapshot.checkedLiveLedger records the comparison ledger. A freshness check limits ledger drift at request time. It cannot stop reserves changing between quoting and execution.
3. Search and allocate
The engine searches token paths within hop and candidate limits. Forward and reverse swaps can split across several paths to reduce the cost of consuming individual pools. Split allocation is bounded search, not exhaustive optimization. When the locally derived USD value of the requestedamount_in (forward) or amount_out (reverse) is strictly below 10 or above, or when no usable local price is available, the requested/default limits apply. This uses the captured pool snapshot and cached USD prices without another network request; fees and slippage do not change which requested amount is valued.
Routes involving an LP token use liquidity mint or burn logic as well as any required swaps. Read the liquidity breakdown instead of treating every hop as an ordinary swap.
Atomic LP routes from another asset
The input to an LP deposit, or output from a withdrawal, can be a token outside the pool’s reserves. Use the same quote endpoint with the LP share-token contract ID asto for buys or from for sells.
For a constant-product deposit, the planner routes the input into one reserve token, balances inside the LP pool, then deposits. A withdrawal burns shares, swaps the other reserve into a common reserve token, then routes that combined balance to the destination. These steps execute in one transaction. External routes exclude the LP pool so their pricing cannot independently change the reserves used by the liquidity operation.
Stable-pool deposits can route into one reserve and deposit it directly; the share estimate includes the pool’s imbalance fee. Constant-product balancing accounts for the Aquarius admin fee removed from tradable reserves.
Request includePaths=true to inspect external paths and lp.preSwap for the balancing swap. maxHops and maxSplits bound the external search; mint/burn and balancing add operations. A path count can include sequential conversion stages, so it does not always mean alternative splits of the original input.
Provide sender, explicit slippage, and simulate=true to request a prepared standalone transaction. Atomic non-reserve routes return one transaction and one routeXdr. Check transaction.simulated; quote-only output is an estimate. Simulate the complete outer transaction again when embedding the payload in a lending strategy.
The hub-route search permits up to eight distinct pool contracts, including the LP pool. This is a planning bound, not a guarantee that every route fits network resources. Failed simulations never relax the original minimum output or the contract’s residual protection.
maxHops and maxSplits trade search and execution complexity against output. Read their current defaults and bounds in the generated API reference. includePaths=true returns the detailed split breakdown for rendering or analysis.
4. Apply fees and output protection
amountOut is the expected output after swap fees. Fee disclosure identifies the amount and whether it is charged on input or output. Static and referral fee buckets round separately; their combined configured rate cannot exceed 1,000 basis points. Do not deduct the displayed fee from amountOut again. Soroban network fees remain a separate cost.
For a forward executable quote, slippage sets the minimum acceptable net output. A reverse quote’s requested amount is a net output target; execution must preserve that target. Do not infer an amountInMax field from the reverse request.
Oracle USD values and human-readable numeric fields are display aids. Use atomic integer strings for accounting and transaction checks; missing oracle prices are not zero prices.
5. Encode and simulate
Explicit slippage allows the router payload to be encoded. Addingsender requests a wallet envelope, with server simulation enabled by default. Check transaction.simulated, not a top-level field.
If a route exceeds simulation budget, the service may reduce route complexity and return degraded metadata. A fallback must preserve the original minimum output. If no acceptable executable route fits, the request fails; it must not silently relax protection.
Reading the response
The
*Short and *Usd fields are display values. Use the atomic strings for accounting.
6. Consume the result
Requote after changes to the amount, tokens, sender, slippage, or referral. Execution models explains payload handling; errors explains recovery.