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:

string

required

Your AGG app identifier.

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

Endpoint	Use when
`POST /correlated-markets/resolve`	You have a venue id, external id, slug, condition id, or fuzzy text and want candidates in one call.
`GET /correlated-markets/cascade/{venueMarketId}`	You already have an AGG `venueMarketId` and want expand or hedge candidates.
`GET /correlated-markets/connections/{venueMarketId}`	You want a side- and mode-agnostic list of related events for a market.
`GET /correlated-markets/{venueMarketId}`	You want to inspect the generated Yes/No signals for a market.
`POST /correlated-markets/query`	You want free-text semantic search across generated signals.
`GET /correlated-markets/status`	You want coverage and worker-status information.

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);

API Reference

View schemas and try the Correlated Markets endpoints.

Building Market Views

Compose Discovery endpoints into event grids and trading views.

Getting Started

Components

REST API

WebSocket Protocol

Authentication

Account

Funding & Execution

Webhooks

Discovery

Real-Time Data

Releases

Public API access

Endpoint map

Resolve a market

Expand vs hedge

Use an AGG market id directly

Result shape

Inspect generated signals

Side- and mode-agnostic connections

Search by theme

Coverage and worker status

API Reference

Building Market Views

​Public API access

​Endpoint map

​Resolve a market

​Expand vs hedge

​Use an AGG market id directly

​Result shape

​Inspect generated signals

​Side- and mode-agnostic connections

​Search by theme

​Coverage and worker status

​Related

API Reference

Building Market Views

Public API access

Endpoint map

Resolve a market

Expand vs hedge

Use an AGG market id directly

Result shape

Inspect generated signals

Side- and mode-agnostic connections

Search by theme

Coverage and worker status

Related