> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle).
> Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors).
> The API reference is generated from https://docs.agg.market/openapi/openapi.json.

# Quotes & smart routing

> What a quote contains, when it can be filled, how long it lasts, and where fees and warnings show up

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](/concepts/execution) for the fill.

```
GET /orderbook/{venueMarketOutcomeId}/route
```

API reference: [Get a quote (smart route)](/api-reference/trading/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](/recipes/self-custody). |
| `appFeeBips`, `referrer`, ... | Per-trade fee overrides. Need `x-app-api-key`. See [Fees](/concepts/fees). |

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```ts SDK theme={null}
  const quote = await client.getSmartRoute({
    venueMarketOutcomeId: outcomeId,
    tradeSide: "buy",
    maxSpend: 25,
  });
  ```
</CodeGroup>

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](/concepts/errors).

## 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](/concepts/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](/recipes/venue-geo-availability).

Self-custody quotes also carry `custodyWarnings[]`. See
[Self-custody trading](/recipes/self-custody).

## Related

<CardGroup cols={2}>
  <Card title="Execution" href="/concepts/execution">
    Fill a quote, or place direct and limit orders.
  </Card>

  <Card title="Comparing venue prices" href="/recipes/comparing-venue-prices">
    Show per-venue prices next to the routed price.
  </Card>
</CardGroup>