---
title: "Settlement Key Differences"
description: "Surface how each venue settles a matched market — resolution source, timing, and edge cases — on the event detail"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

The same prediction lives on more than one venue, but the venues don't always settle it the
same way. One resolves "US presidential election" on the **AP call**; another waits for
**official certification** weeks later. One voids a cancelled match; another resolves it 50‑50.
Those differences are real settlement risk — and historically a trader had to read three sets of
rules to find them.

**Settlement Key Differences** does that reading for you. For any matched cross‑venue event, AGG
returns a structured, per‑venue breakdown of *how the settlements differ*, plus each venue's full
rules — so you can render a "Settlement" panel that tells a user exactly what they're trading
before they trade it.

It's returned **automatically on the single event‑detail endpoint** — no extra parameter, no
extra call.

## What you get

`GET /venue-events/:id` (or `client.getVenueEventById(id)`) now includes two fields:

```jsonc
{
  "id": "evt_…",
  "title": "Who will win the 2028 US presidential election?",

  // The structured differences — drives the "Key differences" cards.
  // null until AGG has computed a diff for the cluster (or when venues settle identically).
  "settlementDiff": {
    "sharedSummary": "All venues track the winner of the 2028 U.S. presidential election.",
    "differences": [
      {
        "type": "resolution_source",            // open enum → pick an icon
        "title": "Resolution source",            // display label
        "perVenue": {                            // a venue is omitted if its rules don't ground a value
          "limitless": "Official election certification",
          "polymarket": "Associated Press, Fox News, and NBC",
          "predict": "Associated Press and NBC"
        },
        "summary": "Limitless waits for certification; others resolve on the called result."
      },
      {
        "type": "resolution_timing",
        "title": "Resolution timing",
        "perVenue": { "limitless": "2029-01-06", "polymarket": "2028-11-08", "predict": "2028-11-08" }
      },
      {
        "type": "edge_cases",
        "title": "Edge cases",
        "perVenue": {
          "limitless": "Recounts may delay settlement",
          "polymarket": "Resolves after source confirmation"
        }
      }
    ]
  }
}
```

`type` is an open enum — known values today are `resolution_source`, `resolution_timing`,
`scope`, `threshold`, `start_date`, `end_date`, `edge_cases`, and `wording`, with `other` as the
catch‑all. Map known types to an icon and fall back to a generic icon for anything else, so a new
type is never dropped.

## Fetch it

<CodeGroup>
```typescript SDK
import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({ baseUrl: "https://api.agg.market", appId: "your-app-id" });

const event = await client.getVenueEventById("evt_123");

if (event.settlementDiff) {
  // render the "Key differences" cards from event.settlementDiff.differences
}
```

```bash REST
curl "https://api.agg.market/venue-events/evt_123" \
  -H "x-app-id: your-app-id"
```
</CodeGroup>

<Note>
Settlement data is returned on the **single event‑detail** endpoint only — it is intentionally
**not** included in the `/venue-events` listing, where running a per‑event settlement lookup for
every row would be wasteful. Fetch it when a user opens an event.
</Note>

## Render it

The fields map one‑to‑one to a settlement panel:

1. **Key differences** — one card per `settlementDiff.differences[]` entry: the `title` as the
   heading, an icon chosen from `type`, and one row per venue from `perVenue` (key = venue, value =
   the short per‑venue value). The card count is `differences.length`.
2. **Empty / not‑yet‑computed** — when `settlementDiff` is `null` or `differences` is `[]`, the
   venues settle identically (or AGG hasn't computed a diff yet); hide the "Key differences" block.

A drop‑in `@agg-build/ui` component for this panel is on the roadmap; until then, render from the
typed fields above.

## How it's built

The differences are produced by a small **hybrid engine**, computed **once per matched
cross‑venue cluster** and persisted — it runs in the background, completely off the trade/quote
path, so reading them never adds latency to execution.

- **Deterministic core (no model):** the structured facts AGG already ingests — resolution dates,
  resolution sources, thresholds, market scope — are compared directly across venues. This is exact
  and grounds the timing/source/threshold/scope differences with zero ambiguity.
- **Language model gap‑fill:** for the nuances that only live in prose (edge cases like recounts,
  walkovers, void conditions, or a resolution source named only in the rules text), a cost‑efficient
  model reads each venue's rules and fills the remaining differences — and is **only** invoked when a
  venue's settlement genuinely isn't captured structurally.

Both paths emit the same structure, and a difference is surfaced only when venues actually diverge
and the value can be grounded in a venue's own rules — AGG omits a venue rather than guess. The
result is cached per cluster and refreshed as venues update their rules.