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:

Expand - Yes-side events that become more attractive if your thesis is right.
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);

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.

Getting Started

Components

REST API

WebSocket Protocol

Authentication

Account

Funding & Execution

Webhooks

Discovery

Real-Time Data

Releases

1. Create the client

2. Resolve a market and fetch candidates

3. Use an internal venueMarketId when you already have one

4. Inspect generated signals

5. Search by a theme

Operational status

Building Market Views

Comparing Venue Prices

​1. Create the client

​2. Resolve a market and fetch candidates

​3. Use an internal venueMarketId when you already have one

​4. Inspect generated signals

​5. Search by a theme

​Operational status

​Related

Building Market Views

Comparing Venue Prices

1. Create the client

2. Resolve a market and fetch candidates

3. Use an internal venueMarketId when you already have one

4. Inspect generated signals

5. Search by a theme

Operational status

Related