> ## 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.
# Settlement Key Differences
> Surface how each venue settles a matched market — resolution source, timing, and edge cases — on the event detail
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 theme={null}
{
"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
"kalshi": "Official election certification",
"polymarket": "Associated Press, Fox News, and NBC",
"predict": "Associated Press and NBC"
},
"summary": "Kalshi waits for certification; others resolve on the called result."
},
{
"type": "resolution_timing",
"title": "Resolution timing",
"perVenue": { "kalshi": "2029-01-06", "polymarket": "2028-11-08", "predict": "2028-11-08" }
},
{
"type": "edge_cases",
"title": "Edge cases",
"perVenue": {
"kalshi": "Recounts may delay settlement",
"polymarket": "Resolves after source confirmation"
}
}
]
},
// Each venue's raw rules — drives the "Full rules by venue" expanders.
"fullRulesByVenue": {
"polymarket": { "description": "This market resolves to …", "rulesPrimary": null, "rulesSecondary": null },
"kalshi": { "description": null, "rulesPrimary": "If the candidate …", "rulesSecondary": "…" },
"predict": { "description": "Resolves per …", "rulesPrimary": null, "rulesSecondary": null }
}
}
```
`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
```typescript SDK theme={null}
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
}
// render the "Full rules by venue" expanders from event.fullRulesByVenue
```
```bash REST theme={null}
curl "https://api.agg.market/venue-events/evt_123" \
-H "x-app-id: your-app-id"
```
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.
## 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. **Full rules by venue** — one expander per venue in `fullRulesByVenue`. Show
`rulesPrimary ?? description` as the body (venues store their rules in different fields), and keep
`rulesSecondary` for any addendum.
3. **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
and just show the full rules.
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.