Quotes & smart routing

A quote prices a trade on one outcome across every venue that lists it, and returns the split that fills best. You then fill the quote by its quoteId. See Execution for the fill.

GET /orderbook/{venueMarketOutcomeId}/route

API reference: Get a quote (smart route).

Request

Query param	Use
`side`	`buy` (default) or `sell`.
`maxSpend`	Buy: the most to spend, in USD. Required for a buy.
`sellShares`	Sell: how many contracts to sell.
`slipCapBps`	Slippage cap in basis points.
`allowedVenues`	Only route to these venues. Repeat the param for several.
`compareVenues`	`true` adds per-venue single-venue quotes in `venueSoloQuotes[]`, each with its own `quoteId`.
`deepEstimate`	`true` adds one-time setup costs to `feeBreakdown.setupCosts`.
`mode`	`live` (default) or `paper`.
`signingAddress`, `fundingAddresses`	Self-custody only. See Self-custody trading.
`appFeeBips`, `referrer`, …	Per-trade fee overrides. Need `x-app-api-key`. See Fees.

curl -G "https://api.agg.market/orderbook/$OUTCOME_ID/route" \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "side=buy" \
  --data-urlencode "maxSpend=25"

const quote = await client.getSmartRoute({
  venueMarketOutcomeId: outcomeId,
  tradeSide: "buy",
  maxSpend: 25,
});

In the SDK the trade direction is tradeSide.

Preview vs executable

Sent	Result
`x-app-id` only	A preview quote. Use it to show a price. It cannot be filled, because it is not tied to a user.
`x-app-id` and the user’s `Authorization`	An executable quote, sized against that user’s balances. Fill it with `POST /execution/fill`.

A sell quote always needs a signed-in user. Filling a quote that belongs to someone else, or a preview quote, returns 400 with code: "quote_user_mismatch".

Can it be filled?

Check status before you fill:

`status`	Meaning
`ok`	The quote can be filled.
`insufficient_balance`	The user does not have enough funds.
`insufficient_position`	Not enough shares to sell. See `positionAvailability`.
`insufficient_depth`, `no_orderbooks`, `no_bids_above_min_price`	Not enough liquidity.
`min_order_size_violated`, `insufficient_input_amount`	The amount is too small for the venue.
`infeasible`, `checker_rejected`, `solver_error`, `invalid_input`, `engine_unavailable`	No valid route could be built.

When status is not ok, read error and message. Only fill quotes with status: "ok".

Expiry

Every quote carries two timestamps:

Field	Meaning
`refreshAt`	From this time, fetch a new quote before showing a price. The current one still fills.
`expiresAt`	After this time the quote cannot be filled.

A quote currently lasts about 45 seconds, with refreshAt about 15 seconds after it is created. Some routes expire sooner. Always read expiresAt; never hard-code the window. A fill after expiry returns 400 with code: "quote_not_found" or "quote_expired". Get a new quote and fill that. POST /execution/fill also accepts fallbackToLatest: if the quote has expired, AGG fills the user’s latest quote for the same outcome, side, amount, and venue scope instead of failing. A different amount or venue scope does not match. A quoteId fills at most once. See Errors, retries & idempotency.

What the quote contains

Field	Meaning
`quoteId`	Pass to `POST /execution/fill`.
`fills[]`	One entry per venue leg: `venue`, `venueMarketOutcomeId`, `avgPrice`, `venueQty`, `venueFee`, and the price levels used.
`totalFilled`	Total shares across legs.
`feeBreakdown`	Line-item costs. See below.
`totalCostIncFees`	Total the user pays, including app and referral fees.
`estimatedPayout`	Payout if the outcome wins, net of settlement fees.
`estimatedProfit`, `returnPct`	Payout minus cost, in USD and percent.
`slippage`	Volume-weighted price against the reference midpoint.
`allocations[]`, `bridgeSteps[]`	Which chain’s funds pay for which venue, and any cross-chain moves needed.
`warnings[]`	Venues left out or flagged, without blocking the quote.

Fees in the quote

feeBreakdown is the number to show before the user commits.

Field	Meaning (USD)
`rawExecCost`	Price times shares, before fees.
`venueFees`	Venue trading fees.
`builderFee`	Builder-code fee, when present.
`bridgeFees`	Expected cross-chain transfer fees.
`executionGas`	Estimated network gas for execution.
`totalCost`	The sum of the lines above. Excludes app and referral fees.
`appFee`	Your app fee on this buy, if it fills in full. Present only when above 0.
`referralFee`	A user-paid referral fee, when present.
`setupCosts`	One-time setup items, only with `deepEstimate=true`.

Use totalCostIncFees for the all-in number. Fees explains each kind.

Warnings

warnings[] lists venues the route skipped or flagged. Each entry has venue, venueMarketOutcomeId, and reason. The quote is still usable. Known reasons include low_liquidity, low_balance, stale_orderbook, empty_book, crossed_book, no_orderbook, app_fee_unsupported, referral_unpaid_on_solana, and referrer_not_activated_on_hypercore. Geo warnings. When a venue is not available in the user’s country, the venue is left out and the reason reads Venue not available in your region (XX) with the country code. The quote does not block. The fill checks location again and refuses a blocked user with 403. See Venue geo availability. Self-custody quotes also carry custodyWarnings[]. See Self-custody trading.

Execution

Fill a quote, or place direct and limit orders.

Comparing venue prices

Show per-venue prices next to the routed price.

Start here

Core concepts

SDK reference

Account & identity

Trading guides

Market data & discovery

Security & compliance

Real-time

Webhooks

UI Kit

Releases

Request

Preview vs executable

Can it be filled?

Expiry

What the quote contains

Fees in the quote

Warnings

Execution

Comparing venue prices

​Request

​Preview vs executable

​Can it be filled?

​Expiry

​What the quote contains

​Fees in the quote

​Warnings

​Related

Execution

Comparing venue prices

Request

Preview vs executable

Can it be filled?

Expiry

What the quote contains

Fees in the quote

Warnings

Related