Skip to main content
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",
  "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. 
const { results } = await client.queryCorrelatedMarkets({
  text: "oil supply shock raises inflation risk",
  limit: 10,
});

for (const match of results) {
  console.log(match.marketQuestion, match.score, 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);

Building Market Views

Compose discovery and orderbook endpoints into event grids and trading views.

Comparing Venue Prices

Compare matched markets across venues with live midpoint data.