Correlated Markets SDK recipe

This recipe shows how to wire the Correlated Markets endpoints together using @agg-build/sdk. For the REST endpoint map, query/path shapes, and curl examples see the Correlated Markets overview.

Correlated Markets starts from one prediction market and returns a paginated list of related events:

1. Expand - Yes-side events that become more attractive if your thesis is right.
2. Hedge - Yes-side events that become more attractive if your thesis is wrong.

Use it when you want to build portfolio ideas, thematic discovery, or a "related markets" surface that goes beyond title matching. The endpoint can resolve a market from the IDs partners already store, queue missing correlated market signal generation in the background, and return cached results after generation finishes.

1. Create the client

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

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

2. Resolve a market and fetch candidates

Use resolveCorrelatedMarkets when you have an external venue identifier, event slug, Polymarket condition ID, or a text query. If AGG has not generated signals for the market yet, the response is status: "processing" and a market-intel job has been queued. Poll the same request again to read results after the job completes.

const result = await client.resolveCorrelatedMarkets({
  venue: "polymarket",
  externalId: "123456",
  side: "yes",
  mode: "expand",
  limit: 6,
});

console.log(result.market);

if ("status" in result && result.status === "processing") {
  return;
}

console.table(result.data);
console.log(result.nextCursor);

Each result has the event ID, event title, similarity score, suggested action, and the signal that created the match.

{
  "venueEventId": "ve_oil_supply",
  "eventTitle": "OPEC production cut",
  "eventStatus": "open",
  "eventStartDate": "2026-06-18T00:00:00.000Z",
  "eventEndDate": "2026-07-01T00:00:00.000Z",
  "score": 0.72,
  "action": "BUY YES",
  "reason": "Energy markets tighten as supply risk rises",
  "reasonDomain": "energy"
}

3. Use an internal venueMarketId when you already have one

If your UI already has a venueMarket.id from GET /venue-events or GET /venue-markets, call the cascade endpoint directly. This path does not resolve identifiers.

const cascade = await client.getCorrelatedMarketCascade({
  venueMarketId: "vm_abc123",
  side: "yes",
  mode: "hedge",
  limit: 10,
});

Pass cursor: cascade.nextCursor for the next page. limit is capped at 100. Resolved and closed markets are excluded by default; add includeResolved: true when you want historical results.

4. Inspect generated signals

Signals explain why a market connects to another event. They are generated for both Yes and No outcomes and grouped by domain.

const batch = await client.getMarketCorrelatedSignals("vm_abc123");

for (const signal of batch.signals) {
  console.log(signal.side, signal.direction, signal.domain, signal.text);
}

5. Search by a theme

Use queryCorrelatedMarkets for free-text discovery across generated signals. Set balanced: true when a single page should include both expand and hedge-style directions; set direction when you want only more_likely or less_likely matches.

const { results } = await client.queryCorrelatedMarkets({
  text: "oil supply shock raises inflation risk",
  limit: 10,
  balanced: true,
});

for (const match of results) {
  console.log(match.marketQuestion, match.marketStatus, match.eventEndDate, match.score);
  console.log(match.matchSource, match.matchedSignal.direction, match.matchedSignal.text);
}

Operational status

Use getCorrelatedMarketsStatus for coverage dashboards or operator checks.

const status = await client.getCorrelatedMarketsStatus();

console.log(status.markets.coverage);
console.log(status.signals.missingEmbeddings);
console.log(status.config.jobsEnabled);
console.log(status.config.backfillInterval);

Related