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

# API Overview

> AGG REST API — authentication, users, markets, orderbooks, charts, and execution

# API Overview

The AGG API gives partner apps access to authentication, user profile endpoints, venue events and
markets, categories, live orderbooks, charts, and execution workflows.

## Base URL

```
https://api.agg.market
```

(Use your deployment URL in development.)

## Authentication

Authentication is **tiered**. Each documented endpoint uses one of these partner-facing tiers:

| Tier     | Headers                                    | Typical use                                                                                          |
| -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **app**  | `x-app-id`                                 | Public partner reads: venue events, venue markets, orderbooks, charts, and auth start/exchange flows |
| **user** | `x-app-id` + `Authorization: Bearer <jwt>` | User profile, avatar upload, KYC, balances, positions, orders, deposit addresses, withdrawals        |

## API Reference

For request/response schemas, try-it-out, and full endpoint details, use the **API Reference** tab (OpenAPI).

## Current orderbook reads

`GET /orderbooks` is the only supported public REST endpoint for live current-book reads.

Pass one or more `venueMarketIds` query parameters for the exact markets you want:

```bash theme={null}
curl \
  -H "x-app-id: YOUR_APP_ID" \
  "https://api.agg.market/orderbooks?venueMarketIds=market-1&venueMarketIds=market-2"
```

The response returns one item per requested `venueMarketId` in request order. Inspect each item’s
`status` and `error` fields to distinguish:

* `ok`
* `market_not_found`
* `market_resolved`
* `market_closed`
* `market_paused`
* `market_unopened`
* `book_not_loaded`

Legacy public REST current-book endpoints return `410 Gone` and should be migrated to `/orderbooks`.

## Example (app-tier)

```bash theme={null}
curl \
  -H "x-app-id: YOUR_APP_ID" \
  "https://api.agg.market/venue-events?limit=10"
```

## Example (user-tier, after sign-in)

```bash theme={null}
curl \
  -H "x-app-id: YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_JWT" \
  "https://api.agg.market/execution/balances"
```

## Route families

* **Authentication**: start a provider flow, verify wallet signatures, exchange redirect codes, refresh access tokens, sign out.
* **Users**: fetch the current user, update profile data, upload avatars, disconnect linked providers, initiate KYC, and access balances, positions, orders, and deposit addresses.
* **Venue Events / Venue Markets / Categories**: browse normalized market data for lists and detail views.
* **News Feed / Correlated Markets**: show market-aware articles, resolve related markets, inspect generated signals, and find expand or hedge candidates through the public Discovery API.
* **Orderbook / Charts**: fetch live per-venue books through `/orderbooks`, route previews, historical candles, and chart-ready data.
* **Execution**: execute quotes and withdrawals.

## Next steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="gear" href="/api/setup">
    Wire up `createAggClient`, providers, auth, and WebSocket connections.
  </Card>

  <Card title="Authentication" icon="key" href="/recipes/authentication">
    SIWE, SIWS, OAuth, and email magic-link flows.
  </Card>

  <Card title="WebSocket Protocol" icon="brackets-curly" href="/api/websocket">
    Real-time orderbooks, trades, heartbeats, and authenticated user events.
  </Card>

  <Card title="News Feed" icon="newspaper" href="/api/discovery/news-feed">
    Add market-aware articles to discovery pages and market detail views.
  </Card>

  <Card title="Funding & Withdrawals" icon="cube" href="/recipes/deposits">
    Balances, deposit addresses, and withdrawal flows.
  </Card>
</CardGroup>