> ## 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.

# Choose your integration

> Managed quote and fill, direct orders, limit orders, self-custody, and hosted venue accounts compared

Every option trades the same markets. They differ in who holds the funds, who signs, and what you
build.

## At a glance

| Option | Funds held in | Who signs | You implement | Pick it when |
| - | - | - | - | - |
| **Managed quote + fill** | The user's managed balance | AGG | Quote, show price, fill, poll status | You want the best price across venues and a simple flow. The default. |
| **Direct order** | The user's managed balance | AGG | One call with your `externalId`, then poll | Your backend already knows the venue and amount, and you want idempotent server calls. |
| **Limit order** | The user's managed balance (reserved while open) | AGG | Place, poll until open, cancel | You want price control on one venue and can wait for a fill. |
| **Self-custody** | The user's own EVM wallet | The user's wallet | Quote and fill with `signingAddress`, then a loop that signs each request | Users must keep their own keys. Needs a client that can sign. |
| **Hosted venue account** | An account AGG hosts for the user on one venue (BetDEX) | AGG | Provision the account, then deposit and withdraw per venue | You need that venue's native account. |

Only managed quote + fill has a [paper mode](/recipes/paper-trading) for testing without real
funds. The other options are live only.

## Managed quote + fill

`GET /orderbook/{venueMarketOutcomeId}/route` with the user's token returns a `quoteId` that may
split across venues. `POST /execution/fill` executes it. You show the quote's price and fees before
the user confirms. Quotes last about 45 seconds.

Start with [Quickstart: REST](/quickstart/rest). Concepts: [Quotes & smart routing](/concepts/quotes),
[Execution](/concepts/execution).

## Direct order

`POST /execution/orders` places a market order on one venue you name. There is no quote step, and it
never splits. `externalId` is required, so a timed-out request can be retried without trading twice.
`maxSpend` caps the all-in cost. Live only.

Guide: [Direct order execution](/recipes/direct-order-execution).

## Limit order

`POST /execution/limit-orders` rests an order at your price on one venue, with a time in force
(`GTC`, `GTD`, `FOK`, `FAK`, `IOC`, `ALO`; venues support subsets). Funds or shares are reserved
while it is open. Track it with `GET /execution/orders?orderId=`; `open` is not final.

Guide: [Limit orders](/recipes/limit-orders).

## Self-custody

The user links an EVM wallet to their account. Quotes and fills name it as `signingAddress`. AGG
prices against that wallet's balances and then asks the wallet to sign each step: venue orders,
funding moves, and approvals. AGG never holds the key. The user must be present to sign, and each
request expires.

Supported on Polymarket, Hyperliquid, and Kalshi (with the user's own Kalshi API key). Other venues
are refused at fill time.

Guides: [Self-custody trading](/recipes/self-custody) and
[Self-custody signing reference](/recipes/self-custody-signing).

## Hosted venue account

For BetDEX, AGG can host a venue account for the user. You provision it, read its balance, get a
Solana USDC deposit address for it, and withdraw from it. See the **Hosted Venue Accounts** group in
the API Reference, starting with
[Provision hosted venue account](/api-reference/hosted-venue-accounts/provision-hosted-venue-account).

## Where your code runs

| Setup | How it works |
| - | - |
| Browser only | Your app signs users in and calls AGG with `x-app-id` and the user's token. Add [allowed origins](/environments#allowed-origins). |
| Browser plus backend | Users sign in on the client. Your backend calls trading routes with `x-app-id`, `x-app-api-key`, and that user's access token. |
| UI kit | Drop in `@agg-build/ui` components; they call the same API. See [Quickstart: React](/quickstart/react). |

Server-only features, such as per-trade `appFeeBips`, referral fees, and `skipQuote` on direct
orders, need `x-app-api-key`.