Correlated Markets

Correlated Markets is an app-tier Discovery API. It starts from a prediction market and returns events that may become more relevant if that market resolves a certain way.

Use it for related-market modules, portfolio idea generation, hedge discovery, and thematic search that goes beyond event title matching.

Public API access

All Correlated Markets endpoints are public partner API endpoints under the Discovery tag in the API Reference. They require only your app header:

No user JWT is required. App exclusions still apply, so responses are filtered by the app's venue and category settings. Closed and resolved markets are excluded by default unless you pass includeResolved: true.

Endpoint map

Resolve a market

Use resolve when your app stores venue-native identifiers. The endpoint resolves the market, checks whether signals already exist, and then returns a paginated cascade.

curl \
  -H "x-app-id: YOUR_APP_ID" \
  -H "content-type: application/json" \
  -X POST "https://api.agg.market/correlated-markets/resolve" \
  --data '{
    "venue": "polymarket",
    "externalId": "123456",
    "side": "yes",
    "mode": "expand",
    "limit": 10
  }'

If signals are not generated yet, AGG queues the background job and returns:

{
  "market": {
    "id": "vm_abc123",
    "question": "Will oil close above $100 this year?"
  },
  "status": "processing",
  "message": "Correlated market generation queued"
}

Retry the same request after processing completes.

Expand vs hedge

mode: "expand" returns Yes-side events that become more attractive if your thesis is right.

mode: "hedge" returns Yes-side events that become more attractive if your thesis is wrong. Hedge results exclude the expand results for the same market and side.

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

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

Use an AGG market id directly

If your UI already has a venueMarket.id from GET /venue-events or GET /venue-markets, call the cascade endpoint directly.

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

if (cascade.nextCursor) {
  const nextPage = await client.getCorrelatedMarketCascade({
    venueMarketId: "vm_abc123",
    side: "yes",
    mode: "expand",
    limit: 20,
    cursor: cascade.nextCursor,
  });
}

limit is capped at 100. Pagination uses the returned nextCursor.

Result shape

Each result is an event-level candidate. Use venueEventId to fetch full event details or navigate to the event in your UI.

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

Inspect generated signals

Each market is summarised by a set of generated Yes/No signals — short statements that explain which real-world states become more or less likely if the market resolves a given way. These signals power the cascade and connection endpoints; fetch them directly when you want to render "why this market is related" copy.

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

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

Side- and mode-agnostic connections

connections returns related events for a market without requiring a side or mode. It is the right call when you just want "what else is connected to this market" — for example, on an event detail page where you want a single Related Markets rail.

curl \
  -H "x-app-id: YOUR_APP_ID" \
  "https://api.agg.market/correlated-markets/connections/vm_abc123?limit=10"

Pagination uses the returned nextCursor. Resolved and closed markets are excluded by default; pass includeResolved=true to include them.

Search by theme

Use semantic query search when the user starts from a theme instead of a specific market. Query results include market and event status/date fields, so clients can keep resolved markets out of tradeable recommendation UIs without extra lookups. Use direction to request only more_likely or less_likely signals, or balanced: true to mix both directions in one page.

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

Coverage and worker status

status exposes signal coverage, embedding coverage, and the background worker configuration so operators can spot stalled generation or low coverage from a dashboard.

const status = await client.getCorrelatedMarketsStatus();

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

Related