Jupiterswap routing: multi-hop and split swaps
Jupiterswap routing selects paths through Jupiter's available Solana liquidity to exchange the chosen tokens. A multi-hop path passes through an intermediate token; a split swap distributes the trade across paths. Available engines, pool liquidity, trade size, and request settings determine which combinations a quote can use.
The short version: Restricting a routing engine can remove useful liquidity even when the selected tokens and input amount stay unchanged.
Tracing a quoted route to received tokens
Start with the selected token mints, the input amount, and an executable transaction for the quoted route. A mint address identifies the token that each leg exchanges. Following those connections shows whether the proposed paths end in the requested output token. Repeat the quote review whenever the amount or routing settings change.
- Confirm the starting and destination mints, and interpret the input amount using that token's decimals.
- Read the selected engine and the available route plan; distinguish intermediate hops from branches that split the input.
- Check the minimum output, quote validity, and signing wallet's support for the returned transaction version before authorization.
- Keep submission within the chosen interface: an order transaction uses managed execution; a signed custom build can use your own Solana RPC or Jupiter's submission service with SOL tips.
- Require successful confirmation and reconcile the actual input debit and output credit with the completed swap.
A transaction signature identifies a transaction without proving that its swap succeeded. For Swap API V2 managed execution, totalOutputAmount reports output after any fee collected in that token. outputAmountResult describes the route's output before that fee. Compare matching mints and units when reconciling those amounts with token balance changes.
Hops and splits describe different route shapes
A hop counts a sequential token exchange, while a split allocates part of the trade to another path. These choices can appear together in the same route.
Direct paths
A direct path exchanges the input token for the output token without an intermediate mint. Its simplicity does not establish a better price. Available liquidity and the trade amount determine whether it competes with paths that use intermediate tokens.
Intermediate hops
In a multi-hop path, an earlier exchange supplies the token that a later exchange consumes. The intermediate token connects markets that can offer useful liquidity for the requested pair. The quoted destination remains the selected output token, even when the route passes through other mints.
Split allocations
A split distributes the trade across liquidity paths that contribute to the same final output. Metis can split and merge portions at different points, including paths that reuse a DEX. When the legs execute in one atomic Solana transaction, a failed instruction reverses the transaction's swap state changes. Network fees can still apply.
When do extra pools improve the quote?
Extra pools can improve quoted output when their additional liquidity outweighs the costs of reaching and using them. An automated market maker, or AMM, quotes against its available liquidity. A trade can move the pool's price as it consumes that liquidity. Splitting reduces reliance on one pool, while an intermediate hop can reach a more favorable market.
The benefit changes with trade size because pool pricing responds to the amount that each leg exchanges. A route that wins for one amount may lose for another. Additional legs can introduce venue fees and account requirements, so hop count alone cannot rank quotes. Compare the same input amount and destination mint with consistent fee and routing settings. The final output estimate describes the combined path; an attractive rate on an intermediate leg does not establish the value of the whole swap.
Routing engines set the available choices
Engine selection chooses the routing system; the route plan describes the liquidity that it uses. A DEX label and a routing engine therefore identify different parts of a quote.
Meta-Aggregator quotes
Swap API V2's Meta-Aggregator lets Metis, JupiterZ, DFlow, and OKX compete, subject to request compatibility. Metis searches on-chain liquidity, while standalone JupiterZ uses request for quote, or RFQ, offers from market makers. The router response field identifies the engine that won the quote.
Custom Metis transactions
The Router path returns raw swap instructions through /build and exposes Metis routing. It suits integrations that need custom instructions or cross-program invocation, where one Solana program calls another. These custom builds cannot use /execute, which handles assembled order transactions and validates their contents.
RFQ liquidity within Metis
JupiterZ V1 supplies standalone RFQ quotes, while JupiterZ V2 streams market-maker orderbooks into Metis. V2 fills settle as part of a Metis route. Market-maker liquidity can therefore supply a hop, even though the selected engine is Metis. The maker still validates and co-signs the fill through a last-look check, which can reject execution.
Routing filters have engine-specific boundaries
On Swap API V2's Meta-Aggregator path, excludeDexes filters only Metis routing.
Other eligible engines remain unaffected by that DEX filter. excludeRouters removes whole engines from competition. On the Router path, dexes restricts Metis to selected exchanges, while excludeDexes removes selected exchanges. Those inclusion and exclusion parameters are mutually exclusive on /build. Labels are case sensitive. An unrecognized inclusion label can return a no-route error that resembles missing liquidity, so a restrictive request needs accurate labels.
Filtering narrows the available search space and can reduce output or eliminate a usable path. A venue exclusion on one engine does not establish a global exclusion across the Meta-Aggregator. If an integration requires a strict venue boundary, the chosen endpoint and filter scope must support that boundary.
Account budgets and transaction space constrain complexity
Lowering maxAccounts on /build limits the accounts that the swap route can use. This can leave room for custom instructions, but it also removes routing choices. A route that requires more accounts may disappear, produce worse pricing, or stop fitting the request. The account budget concerns route construction; the complete transaction still needs validation.
Solana v0 transactions have a 1,232-byte size limit; v1 raises that limit to 4,096 bytes. Address lookup tables compress account references in v0, while v1 includes accounts directly. On /build, transactionVersion=1 requests v1. On /order, maxSupportedTransactionVersion=1 permits v1 only when Metis wins and the order is not gasless. Otherwise, the order returns v0. Wallet and client support must match the returned version.
Compute units measure the work that programs perform during execution. Integrations using /build need to simulate the complete transaction when estimating its compute budget. Adding instructions changes that workload. Space-saving edits also need context: an account-creation instruction is dispensable only when its required account already exists.
Can execution use different pools from the quote?
Yes, a Metis route using JIT Swap can change candidate pool selection or split allocations during execution. JIT means just in time: the program evaluates candidate liquidity against the pool states that exist when the swap executes.
JIT Swap can rebalance allocations among its candidate pools during on-chain execution. The off-chain route supplies those candidates and the initial allocation. This mechanism refines that selection within its supported scope; it does not search every possible pool at execution time.
Quote latency creates a separate trade-off. The beta mode=fast setting on /build reduces routing computation by disabling splitting and exploring fewer combinations. It also performs the priority-fee lookup in parallel. Faster quoting can sacrifice output from more complex paths. The parallel lookup estimates global priority fees because the route's writable accounts are not yet known.
Output thresholds bound the acceptable execution
The minimum-output threshold defines the lowest output that an exact-input swap accepts under its slippage setting. Slippage describes the difference between quoted and executed output. It remains distinct from the price impact that the trade causes within liquidity pools. A complex route can improve its initial quote and still fail when later market movement breaches its threshold.
Jupiter's Real-Time Slippage Estimator, or RTSE, estimates tolerance when creating an order, rather than changing it during execution. The Meta-Aggregator applies it automatically unless a fixed value overrides it; /build requires slippageBps=rtse to opt in. Transaction validity adds another boundary. Aggregator orders carry a last valid block height, while standalone RFQ quotes carry an expiry timestamp. An unexpired quote can still fail because market prices have moved.
Market availability can change without a new token
Metis periodically reviews market liquidity and removes markets that fail its routing criteria. Eligible new markets can receive instant routing during a grace period based on token age. Creating another pool for an older token does not restart that period. A bonding-curve market that fails to graduate before the period ends leaves routing; its graduated market can enter after migration. These rules apply to Metis, rather than every engine. The Meta-Aggregator may still quote through another eligible engine after a Metis market disappears. A failed Metis-only quote therefore does not prove that every Jupiter routing path is unavailable.
Jupiterswap routing: reader questions
Will a separate fee payer preserve every routing engine?
Setting a payer different from the taker on Swap API V2's Meta-Aggregator restricts routing to Metis. That setting activates integrator-sponsored gas and excludes the standalone JupiterZ routing option. Setting payer equal to taker has no effect. Automatic Jupiter sponsorship and market-maker-paid fees are separate mechanisms, so a gasless response alone does not identify this restriction.
Does manual mode mean JupiterZ cannot win the quote?
Manual mode indicates that optional request parameters were supplied and may affect routing or swap behavior; it does not identify the winning engine. The router field supplies that information. Restrictions depend on the specific parameters. A fixed slippage setting alone does not force Metis-only routing, and supported referral settings can retain JupiterZ eligibility.
How do routing basis points translate into a trade share?
Divide a route allocation in basis points by 100 to express it as a percentage: 10,000 basis points represent 100%. Swap API V2 treats bps as the canonical allocation field, while retaining percent for compatibility. Routing allocations and slippage tolerance use the same unit to describe different quantities.
Where can an integration identify the DEX program behind a failed route leg?
Jupiter's program-ID-to-label mapping associates on-chain program addresses with readable DEX labels. Matching a faulting program identifier from transaction logs to that mapping can identify the affected venue. The logs and the particular error still determine whether the problem concerns pricing, token accounts, or another execution requirement.
Are intermediate Solana hops cross-chain transfers?
Intermediate hops in Jupiter's Solana swap routing exchange different tokens within Solana. A longer token path does not by itself introduce another blockchain or a bridge. The intermediate mint identifies the token that connects neighboring exchanges, while the selected destination mint identifies the token that the complete route aims to produce.
Can I request a fixed output amount through Swap API V2?
Swap API V2's order and build paths support only exact-input swaps, which route a specified amount of the starting token. A quoted output amount is an estimate for that input, and the minimum-output threshold limits acceptable execution. This endpoint scope does not establish the modes available through other Jupiter APIs.
Last updated -