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

# Markets, outcomes & matching

> Events, markets and outcomes, the ids you trade with, and how AGG links the same market across venues

## The data model

Every venue lists its own copy of a real-world question. AGG stores each venue's listing and links
equivalent ones together.

| Object | What it is | Id you use |
| - | - | - |
| Venue event | One venue's event, for example a game or an election | `id` from `GET /venue-events` |
| Venue market | One question inside an event, for example "Will X win?" | `id` from `GET /venue-markets` (`venueMarketId`) |
| Venue market outcome | One side of a market, usually `Yes` or `No` | `venueMarketOutcomes[].id` (`venueMarketOutcomeId`) |

**You trade an outcome.** Quotes, direct orders, and limit orders all take a
`venueMarketOutcomeId`. Orderbook and midpoint reads take the market id or the outcome id,
depending on the route. The two are not interchangeable.

Each object also carries `externalIdentifier`, the venue's own id (a Kalshi ticker, a Polymarket
token id). Use it to look up AGG ids from venue ids.

Market `status` is one of `unopened`, `paused`, `open`, `closed`, or `resolved`. Only `open`
markets can be traded. How a closed or resolved market pays out, including splits and voids, is
covered in [Market resolution & voids](/concepts/market-resolution).

## Find a market to trade

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "x-app-id: $AGG_APP_ID" \
    "https://api.agg.market/venue-markets?status=open&search=bitcoin&limit=5"
  ```

  ```ts SDK theme={null}
  const markets = await client.getVenueMarkets({ status: "open", search: "bitcoin", limit: 5 });
  const outcomeId = markets.data[0]?.venueMarketOutcomes?.[0]?.id;
  ```
</CodeGroup>

Each market in `data[]` carries `venueMarketOutcomes[]`. Take the outcome's `id`. Prices are not
on the listing; read them from `GET /midpoints` or a quote. For full filters and search modes see
[Building market views](/recipes/building-market-views) and the
[List venue markets](/api-reference/markets/list-venue-markets) reference.

## Matching across venues

AGG links listings of the same event on different venues into a **matched cluster**. Discovery
returns the cluster already assembled, so you do not match markets yourself.

* `GET /venue-events` returns one row per cluster, the **anchor** event. Use its `id` as your
  cross-venue key.
* `matchedVenueEvents[]`, `matchedVenueMarkets[]`, and `matchedVenueMarketOutcomes[]` list the
  same event, market, or outcome on the other venues.
* `venues[]` and `venueCount` summarize which venues list it.

You can quote any outcome in a cluster. The quote routes across the matched venues and returns the
split in `fills[]`. See [Quotes & smart routing](/concepts/quotes).

## aggKey

`aggKey` is a deterministic key computed from a venue's own data, on events and markets. It is a
convenient filter for fetching every venue's row for one contract. It is **not** the cross-venue
join key: it is `null` on many markets, and two members of one cluster can carry different keys.
Join on the cluster instead.

## Settlement can differ

Venues do not always settle the same question the same way, for example on timing or on a
cancelled match. `GET /venue-events/:id` returns a per-venue breakdown of those differences. Show
it before users trade across venues.

## Guides

<CardGroup cols={2}>
  <Card title="Matched clusters" href="/recipes/matched-clusters">
    Anchors, members, which id to join on, and why a cluster can look empty.
  </Card>

  <Card title="Look up by venue identifier" href="/recipes/external-identifier-lookup">
    Resolve a Kalshi ticker or Polymarket token id to the full cluster.
  </Card>

  <Card title="aggKey" href="/recipes/agg-key">
    Fetch every venue's row for one contract with one key.
  </Card>

  <Card title="Settlement key differences" href="/recipes/settlement-key-differences">
    Show how each venue settles a matched market.
  </Card>
</CardGroup>