Settlement Key Differences

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:

{
  "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

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
}

curl "https://api.agg.market/venue-events/evt_123" \
  -H "x-app-id: your-app-id"

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.