Routing and Priority Mode

By default Treasures picks the route for you. A quote can come back with legs on more than one chain, ordered cheapest first, and on the EVM chains those legs are relayed orders that cost the wallet no gas. Priority mode (priority: "speed") changes who pays and what you sign: it asks for a single-block on-chain swap on Robinhood Chain and Base instead of a relayed order, and can serve a buy on a chain the wallet is not funded on through a cross-chain leg. On a sell, payout_chain changes them too, whatever the priority. This page lays out the difference chain by chain, and what you give up for the speed. For how the options combine, what each kind of leg asks you to sign, and recipes for common goals, see Buying and Selling.

Default routing

Send a buy or sell quote with no priority and Treasures evaluates every chain the ticker lists (or the subset you allow with chain and protocol), ranks the candidates and returns up to one leg per chain. You can nudge the order with preferred_chain, which moves that chain's leg to quote_index: 0 without adding or dropping anything.

Chain	Default route	Who pays gas	What you sign
sol	On-chain swap	The wallet, in SOL	A Solana transaction
eth	Relayed order, gasless	Nobody on your side; a settlement network broadcasts	An EIP-712 typed-data order
robinhood	Relayed order, gasless	Nobody on your side	An EIP-712 typed-data order
base	Relayed order, gasless	Nobody on your side	An EIP-712 typed-data order
arbitrum	Relayed order, gasless	Nobody on your side	An EIP-712 typed-data order

arbitrum is Reality's venue on Arbitrum One. Its listings stay hidden (and a quote there is 422 no_routes) until the venue opens, so read the listings rather than assuming it is there.

The only gas a default-route caller ever pays is Solana's, plus the one-time ERC-20 approvals, any bridge broadcasts and a sell paid out on another chain, which are always the wallet's own transactions.

Priority mode: priority: "speed"

Speed is a filter, not a preference. Under priority: "speed" the same-chain candidates are Solana (unchanged, its route is already fast) and the speed routes on Robinhood Chain and Base. Ethereum is never quoted on its own route under speed, and a Robinhood Chain or Base leg the speed route cannot serve is left out of the response with a warning rather than handed back on its relayed route. A buy can also come back as a cross-chain leg when the wallet is not funded on a listing's chain.

Chain	Under priority: "speed"	Who pays gas	What you sign
sol	Unchanged: the normal on-chain swap, still quoted	The wallet, in SOL	A Solana transaction
eth	Never on its own route. On /quote/buy and /quote/preview it can come back as a cross-chain leg, so a chain: "eth" pin yields that leg or 422 no_routes. On /quote/sell, pinning chain: "eth" (or ["eth"]) together with speed is 400 invalid_request and a wider chain set simply loses eth, unless the sell pays out on another chain	See cross-chain legs	See cross-chain legs
robinhood	Speed route: a single on-chain swap that settles in one block	The wallet, in native ETH on Robinhood Chain (4663), or your paymaster on the sponsored lane	One complete unsigned transaction (evm_signed_tx), or two when an approve is needed; one evm_calls payload on the sponsored lane
base	Speed route: a single on-chain swap that settles in one block	The wallet, in native ETH on Base (8453), or your paymaster on the sponsored lane	One complete unsigned transaction (evm_signed_tx), or two when an approve is needed; one evm_calls payload on the sponsored lane
arbitrum	Never quoted. There is no speed route; pinning chain: "arbitrum" together with speed is 400 invalid_request	n/a	n/a

Every leg carries gasless so you can tell the two apart without inspecting payload types: true for a relayed order, false for a speed-route leg. Speed-route legs also carry estimated_gas_usd, the figure the route ranking charged against them; it is null when no USD gas price was available, with a speed_route_unpriced_gas warning naming the chain, and the leg is still a speed-route leg.

What you trade away

Speed moves several things that the relayed route handles for you onto your side:

• Native gas. The wallet must hold enough native ETH on that chain to fund the broadcast. A signed transaction whose gas × fee exceeds the balance fails at submit with insufficient_native_gas; fund the wallet and re-quote.
• An unlimited allowance, signed by you. No pre-approval is needed: a wallet that has not approved the router gets an approve payload bundled before the swap. That approve grants the router an unlimited (max-uint256) allowance on the token being spent. You are signing that consent, so surface it to your user.
• Two payloads, in order. When a pair is issued, sign and return both, in the order issued, branching on each payload's role (approve, then swap, or deposit on a cross-chain leg) rather than on array position. Signing only the first is incomplete_submit; reordering them on a replay is read as a new submit, leg_already_submitted.
• Nonces. Only one speed trade per wallet per chain can be in flight. A second collides as nonce_conflict; wait for the first to go terminal, then re-quote. Never re-nonce, re-estimate or re-serialize a payload: the server compares the signed bytes with the ones it issued.
• Approve failures. On a pair, tx_hash is the swap's from the start but appears on chain only after the approve mines. approve_failed means the approve reverted or did not land within 10 minutes and the swap was never sent; tx_hash is then null. Re-quote.
• Absent legs, not downgraded ones. A chain the speed route cannot serve is missing from quotes[] with a speed_route_unavailable warning carrying chain and a reason: disabled, insufficient_balance, no_routes, provider_error, or wallet_not_delegated on the sponsored lane. The list is open; treat an unknown reason as "unavailable, reason unknown". Re-quote without priority to get the relayed route on that chain.
• A gas estimate, not a bound. estimated_gas_usd is an estimate over a live gas market. The signed transaction bounds what you can actually spend; the string does not.

Cross-chain legs

Under speed, /quote/buy and /quote/preview can serve a listing on a chain the wallet is not funded on as a cross-chain leg: your stablecoin leaves the chain it sits on and the purchase is filled on the listing's chain. origin_chain is present only on such a leg, so its presence is the marker; chain stays the destination. eth/ondo (a chain: "eth" pin included), sol/xstocks and, on an unpinned or multi-chain request, base/coinbase can be reached this way. A single-chain base or robinhood pin always routes same-chain, and robinhood, sol/ondo and eth/xstocks are never cross-chain destinations.

• Cost. cross_chain_cost_bps and cross_chain_cost_usdc disclose the hop's own cost, and cost_breakdown_bps.dex_swap_fee_bps is null on the leg. base_asset and amount_base name what left your wallet (the origin's currency), not the destination's.
• What you sign. From sol, one Solana transaction with your own wallet as fee payer, so the leg is gasless: false. From an EVM chain, a role: "deposit" transaction, preceded by an approve for the exact amount (not unlimited) when the wallet has no allowance yet; on the sponsored lane, one evm_calls payload instead. gasless and estimated_gas_usd describe the origin chain.
• Both wallets. A 422 no_routes with reason: cross_chain_wallet_missing means the buy could only be served from a chain whose wallet you did not send. Send both sol_wallet and eth_wallet.
• Warnings. cross_chain_route_unavailable (with chain, protocol and reason) means the cross-chain attempt for that listing fell back to its normal speed plan, which on eth means no leg at all. cross_chain_price_deviation flags a leg priced more than 500 bps from the reference market, and exit_gas_unfunded flags a destination wallet without the native gas to sell the position later. Both are advisory; the leg is executable.
• Leg outcomes. Besides the usual ones, a cross-chain leg can fail with refunded (the deposit came back to your origin wallet), deposit_reverted, or a per-leg quote_stale (a Solana origin's transaction expired before broadcast); re-quote after any of them. delivered_other_currency is terminal: you received a stablecoin instead of the token. cross_chain_unsettled means 6 hours passed with no outcome: do not re-quote, because it may still fill or refund.

The sponsored lane: execution: "user_operation"

If you run an ERC-4337 stack you can make a Robinhood Chain or Base speed leg gasless again. Send execution: "user_operation" together with priority: "speed" and the leg comes back as one evm_calls payload instead of a signed-transaction pair. Pack it into an ERC-4337 v0.7 UserOperation from the wallet, which must be EIP-7702-delegated to Modular Account v2 on that chain, sponsor it with your own paymaster, sign, and return it as evm_user_operation. Treasures submits it to a bundler and tracks it. The leg is then gasless: true with estimated_gas_usd: "0", and there is no nonce to collide on.

Two refusals exist only on this lane: sponsorship_rejected (your paymaster declined) and wallet_not_delegated (the wallet is not delegated on that chain; 400 when pinned, a drop reason when not). Sending execution: "user_operation" without priority: "speed" is 400 invalid_request. The lane serves Base and Robinhood Chain. A chain it cannot serve at the moment is dropped with speed_route_unavailable and reason: "disabled", or refused as 422 no_routes when pinned.

A cross-chain leg can use this lane too. Its evm_calls payload carries a deposit call in place of the swap, sender is your wallet on the origin chain, and chain_id can also be 1 (Ethereum) for an Ethereum-origin leg. It is gasless: true and its estimated_gas_usd is null, because the gas is your paymaster's.

Paying out a sell on another chain: payout_chain

POST /quote/sell takes payout_chain (sol, eth or base) to have the sale's USDC land on that chain, in your own wallet there (sol_wallet on sol, eth_wallet on eth and base). It is independent of priority and sell-only: sending it to /quote/buy or /quote/preview is 400 invalid_request. Absent or null sells every position on its own chain, as before. robinhood and arbitrum are not payout chains.

Each position you hold is planned on its own terms:

• A position already on payout_chain sells there as usual. Under speed it keeps the speed filter, so an eth position is left out when paying out on eth.
• A sol/xstocks, base/coinbase or eth/ondo position on another chain sells cross-chain as one leg, marked by payout_chain on the leg, with no separate payout step to submit. This is also why chain: ["eth"] together with speed is accepted when the payout is elsewhere.
• Any other position (sol/ondo, eth/xstocks, robinhood, arbitrum) is left out, named by a cross_chain_route_unavailable warning. It is never sold on its own chain instead.

Whatever the priority, the wallet pays the gas for a cross-chain sell leg on the position's own chain (gasless: false), and estimated_gas_usd prices it (null on sol). The one exception is the sponsored lane, where your paymaster pays and the leg is gasless: true. On eth or base the leg always carries two payloads: an exact-amount approve of the tokens sold, then a deposit that sells them and sends the USDC on. On the sponsored lane the same two calls come as one evm_calls payload sent from your eth_wallet. On sol it is one Solana transaction with your wallet as fee payer. estimated_output_usdc is what lands on payout_chain, and cross_chain_cost_bps / cross_chain_cost_usdc disclose the hop's own cost.

The refusals are specific. 400 invalid_request (message prefixed payout_chain: ) means the payout chain's wallet is missing, or nothing in your chain and protocol scope can pay out there. 422 holdings_insufficient means your holdings fall short. 422 no_routes with reason: payout_route_unavailable means you hold enough, but not enough of it can pay out on that chain; pay out elsewhere, drop payout_chain, or re-quote later.

After submit, the status leg and the GET /trades row carry payout_chain and payout_tx_hash (the payout transaction, null until completed), while tx_hash stays the sale. If the payout could not be made, the USDC may be returned on the sale's own chain, and payout_chain then equals chain.

Reading the response

• gasless on every leg says who pays. Under speed, a gasless: true leg is Solana, unless you are on the sponsored lane.
• origin_chain marks a cross-chain buy leg and payout_chain a cross-chain sell leg; both are absent on every same-chain leg.
• estimated_gas_usd appears on speed-route legs (on a cross-chain leg it prices the origin chain) and on sell legs paid out on another chain, never on a relayed leg.
• poll_after_ms on GET /quote/{quote_id}/status drops to 1250 while a speed-route leg is in flight, because it settles by receipt within a block or two, and tx_hash is the on-chain transaction to watch.
• user_op_hash appears on submit results and status legs for the sponsored lane and is null elsewhere. On a cross-chain leg on that lane tx_hash stays null until the leg is terminal, so user_op_hash is the handle to watch.

When to use it

Use the default route when you want the wallet to spend no gas and can wait for a relayed fill. Use priority mode when settlement inside one block matters more, the wallet is funded with native ETH on that chain (or you sponsor it), and your integration can handle the nonce and two-payload rules above. Buying and Selling walks through every combination with recipes. Field-level detail for every request and response key is in the quote reference.