aggKey

aggKey is an optional fetch filter. sufwan-local-test computes it at discovery from that venue's own data, and you pass the string back unchanged to fetch the rows that share it. Which id to store is Ids.

It appears on both objects: VenueEvent.aggKey (the event, e.g. a game) and VenueMarket.aggKey (a market within it, e.g. a spread line).

Using itCopy Anchor Link

Read aggKey off a market or event, then pass it back as a filter. The parameter accepts one key or several, and combines with the other filters (venue, status, …). Your app's venue and category visibility still applies.

import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.t.sufwankhalid.com",
  appId: "YOUR_APP_ID",
});

const { data } = await client.getVenueEvents({
  aggKey: "agg_nba_nyk_sas_260610",
});

List venue events. A market key uses the same aggKey parameter on List venue markets.

Use the event key for every venue's version of the same event, the market key for the exact same contract including line, period and window.

What it convergesCopy Anchor Link

The key is computed from each venue's own data, so how far it converges depends on the family.

It is guaranteed identical across venues where every venue exposes the same normalizable inputs: sports head-to-head (canonical league and team codes plus the game date), crypto up/down, and central-bank rate decisions (institution code plus meeting day). Two rows from different venues sharing a non-null key in those families are the same contract — same line, same period, same window.

Dated outcomes — elections, "by when" questions, token launches — are derived from whatever the venue publishes: a human-readable slug where there is one, a ticker where there is not, and a date segment from that venue's own resolution timestamp. Two venues listing the same question routinely produce different keys, so use the matched cluster for that family.

A key carried by only one venue is usually not a convergence failure — most of the time only one venue lists that game or window. The guarantee is conditional: if two venues list the same contract, their keys agree.

When it's nullCopy Anchor Link

null means "no canonical key". It is not an error and does not mean the market is unmatched — those rows still carry their counterparts on matchedVenueMarkets[].

A market is keyed only when the key fully identifies the contract; see Sports market suffixes for exactly which do. Player props, individual strikes of a multi-strike ladder, and long-tail venue-specific propositions return null even when their parent event has a key. Expect null far more often on markets than on events, and design for it rather than treating it as a gap.

Do you need to parse it?Copy Anchor Link

Almost never. Every fact you might read out of the string is already a typed field, and those fields are the supported contract — the segment grammar is not.

Building a sports detail page takes exactly one parse: the ladder family key in Grouping a line ladder. If you are reaching into the key for anything else, the field you want already exists.

FormatCopy Anchor Link

A key is the agg_ prefix followed by _-joined segments. Dates are YYMMDD (sports local date; daily markets) or a compact UTC instant (sub-daily intraday markets). Decimals use p (2p5 = 2.5). A future format revision will use a new prefix (e.g. aggk2_), so agg_ is your version guard.

Sports market suffixesCopy Anchor Link

The market key is the event key plus a suffix. A full-game two-way moneyline carries no suffix — its market key is the event key. This is the complete set.

{method} is a closed set: kotko, sub, dec, draw.

Full-game and full-match scopes carry no period token. Every other scope is the period value with non-alphanumeric characters removed (set_1 → set1, first_5_innings → first5innings), trailing for spread/total/BTTS and prefixed for moneyline.

Marker tokens are not uniqueCopy Anchor Link

A team code can be spelled exactly like a suffix marker. Tottenham is tot, Sporting is sp, Malmö is ml, and all three are live:

Never split on the first _sp_, _tot_ or _ml_. Splitting agg_atc_sp_wol_260906_sp_sp_m1p5 on its first _sp_ yields agg_atc_sp — no opponent, no date — which collides with every other Sporting fixture. Anchor on the _YYMMDD token: it ends every event key, and markers only ever appear after it.

const DATE = /_\d{6}(?=_|$)/;

// Everything up to and including the date token — the event base.
const eventBase = (aggKey) => {
  const m = DATE.exec(aggKey);
  return m ? aggKey.slice(0, m.index + m[0].length) : aggKey;
};

Grouping a line ladderCopy Anchor Link

One card with a line selector, unioned across venues — the only supported structural read of the key. Uses the eventBase helper above, and gates on sportsMarketType: neither rule is safe applied to the other type.

const familyKey = (market) => {
  const base = eventBase(market.aggKey);

  // Both legs of one symmetric spread → one family. They name DIFFERENT teams
  // (…_sp_arg_m1p5 and …_sp_che_p1p5 are the same line).
  if (market.sportsMarketType === "spread") return `${base}_sp`;

  // Drop the trailing line and optional period token. What remains keeps
  // subjects apart: …_tot, …_tot_team_arg, …_tot_corners.
  if (market.sportsMarketType === "total")
    return base + market.aggKey.slice(base.length).replace(/_\d+(p\d+)?(_[a-z0-9]+)?$/, "");

  return market.aggKey;
};

Both rules drop the period, so take it from the period field and put it in your group key alongside the family. Order totals by lineValue. Order spreads by |lineValue|, taking the side of the axis from the m/p token — polymarket stores spreads negative while kalshi, novig and predict store them positive, so sorting on the signed value interleaves the two halves of one ladder.

RelatedCopy Anchor Link