> ## 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 SDK recipe

> End-to-end SDK walkthrough for resolving markets and rendering related events with @agg-build/sdk

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](/api/discovery/correlated-markets).

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

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

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

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

## 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.

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

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

## 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.

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

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

## Related

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

  <Card title="Comparing Venue Prices" icon="scale-balanced" href="/recipes/comparing-venue-prices">
    Compare matched markets across venues with live midpoint data.
  </Card>
</CardGroup>