> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Correlated Markets

> Public Discovery API for finding markets connected by generated real-world outcome signals

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:

<ParamField header="x-app-id" type="string" required>
  Your AGG app identifier.
</ParamField>

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`](/api-reference/discovery/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}`](/api-reference/discovery/getcascade)         | You already have an AGG `venueMarketId` and want expand or hedge candidates.                         |
| [`GET /correlated-markets/connections/{venueMarketId}`](/api-reference/discovery/getconnections) | You want a side- and mode-agnostic list of related events for a market.                              |
| [`GET /correlated-markets/{venueMarketId}`](/api-reference/discovery/getmarketcorrelatedsignals) | You want to inspect the generated Yes/No signals for a market.                                       |
| [`POST /correlated-markets/query`](/api-reference/discovery/querycorrelatedmarkets)              | You want free-text semantic search across generated signals.                                         |
| [`GET /correlated-markets/status`](/api-reference/discovery/getcorrelatedmarketsstatus)          | 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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```json theme={null}
{
  "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.

```typescript theme={null}
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.

```bash theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
const status = await client.getCorrelatedMarketsStatus();

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

## Related

<CardGroup cols={2}>
  <Card title="API Reference" icon="book-open" href="/api-reference/discovery">
    View schemas and try the Correlated Markets endpoints.
  </Card>

  <Card title="Building Market Views" icon="layer-group" href="/recipes/building-market-views">
    Compose Discovery endpoints into event grids and trading views.
  </Card>
</CardGroup>