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

# Find Markets

> Discover, search, and browse prediction markets via the Metadata API

<Info>
  During development, you can use the [developer endpoints](/get-started/endpoints) without an API key. For production use, [request an API key](/get-started/api-key) for higher rate limits.
</Info>

<Note>
  Every block below is an independent example. Each one redeclares the env consts and the `headers` object so you can copy and run any one of them on its own.
</Note>

A **market** is a single YES/NO question. **Events** group related markets (for example, an NBA game is an event containing a market for each team winning). The Metadata API lets you query either.

## List markets

Query events with `withNestedMarkets=true` to include each event's markets inline. Read outcome mints from each market's `accounts` field (pass these as `outputMint` to `/order` when trading). See [Event fields](/prediction-markets/prediction-market-data-model#event-singleeventresponse) for the data model.

<AccordionGroup>
  <Accordion title="Get events with nested markets">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const { events = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/events?withNestedMarkets=true&limit=200`,
      { headers }
    ).then((r) => r.json());

    events.forEach((event: any) => {
      console.log("Event:", {
        ticker: event.ticker,
        title: event.title,
        subtitle: event.subtitle,
        seriesTicker: event.seriesTicker,
      });

      event.markets?.forEach((market: any) => {
        const accountValues = Object.values(market.accounts);

        console.log("  Market:", {
          ticker: market.ticker,
          title: market.title,
          status: market.status,
          accounts: accountValues.map((account: any) => ({
            yesMint: account.yesMint,
            noMint: account.noMint,
          })),
        });
      });
    });
    ```
  </Accordion>
</AccordionGroup>

## Filter by market status

Filter events to focus on markets that match a given **status** (e.g. active vs. initialized). See [Prediction Market Lifecycle](/prediction-markets/market-lifecycle) for the full status flow.

<AccordionGroup>
  <Accordion title="Get active markets">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const { events = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/events?withNestedMarkets=true&status=active&limit=200`,
      { headers }
    ).then((r) => r.json());

    events.forEach((event: any) => {
      event.markets?.forEach((market: any) => {
        const accountValues = Object.values(market.accounts);

        console.log("Market:", {
          ticker: market.ticker,
          title: market.title,
          status: market.status,
          accounts: accountValues.map((account: any) => ({
            yesMint: account.yesMint,
            noMint: account.noMint,
          })),
        });
      });
    });
    ```
  </Accordion>

  <Accordion title="Get initialized markets">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const { events = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/events?withNestedMarkets=true&status=initialized&limit=200`,
      { headers }
    ).then((r) => r.json());

    events.forEach((event: any) => {
      event.markets?.forEach((market: any) => {
        const accountValues = Object.values(market.accounts);

        console.log("Market:", {
          ticker: market.ticker,
          title: market.title,
          status: market.status,
          accounts: accountValues.map((account: any) => ({
            yesMint: account.yesMint,
            noMint: account.noMint,
          })),
        });
      });
    });
    ```
  </Accordion>
</AccordionGroup>

## Full-text search

`GET /api/v1/search?q=...` returns events matching title, ticker, or nested market titles. Response shape mirrors `/events`.

<AccordionGroup>
  <Accordion title="Search events by title or ticker">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const params = new URLSearchParams({
      q: "bitcoin",
      withNestedMarkets: "true",
      status: "active",
      limit: "20",
    });

    const { events = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/search?${params}`,
      { headers }
    ).then((r) => r.json());

    for (const event of events) {
      console.log(`${event.ticker}  ${event.title}  (${event.markets?.length ?? 0} markets)`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Markets by series

A **series** groups related events. For example, a single NBA series contains an event for each game; a Bitcoin price series contains an event for each price interval. Series cover every category Kalshi supports (crypto, sports, politics, weather, entertainment, and more).

The events endpoint accepts a `seriesTickers` parameter that returns every event and market in that series.

### Query with a known series ticker

<AccordionGroup>
  <Accordion title="Get all active markets in a series">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    // Pick a series ticker for your topic. Examples:
    //   KXBTC  - Bitcoin price markets
    //   KXSOL  - Solana price markets
    //   KXNBA  - NBA game outcomes
    const seriesTicker = "KXBTC";

    const { events = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/events?withNestedMarkets=true&seriesTickers=${seriesTicker}&status=active`,
      { headers }
    ).then((r) => r.json());

    events.forEach((event: any) => {
      console.log("Event:", {
        ticker: event.ticker,
        title: event.title,
      });

      event.markets?.forEach((market: any) => {
        const accountValues = Object.values(market.accounts);

        console.log("  Market:", {
          ticker: market.ticker,
          title: market.title,
          status: market.status,
          accounts: accountValues.map((account: any) => ({
            yesMint: account.yesMint,
            noMint: account.noMint,
          })),
        });
      });
    });
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  Pass a comma-separated list to query multiple series at once: `seriesTickers=KXBTC,KXSOL,KXNBA`.
</Tip>

### Find a series ticker by category and tag

Pass any of the resulting tickers into the events query above.

<AccordionGroup>
  <Accordion title="Get tags by category">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const { tagsByCategories = {} } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/tags_by_categories`,
      { headers }
    ).then((r) => r.json()) as { tagsByCategories: Record<string, any[]> };

    Object.entries(tagsByCategories).forEach(([category, tags]) => {
      const tagList = Array.isArray(tags) ? tags.join(", ") : String(tags ?? "");
      console.log(`Tags for ${category}: ${tagList}`);
    });
    ```
  </Accordion>

  <Accordion title="Filter series by category and tags">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const selectedCategory = "Sports";
    const selectedTag = "Football";

    const byCategory = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/series?category=${selectedCategory}`,
      { headers }
    ).then((r) => r.json());
    const categorizedSeriesTickers = (byCategory.series ?? []).map((s: any) => s.ticker);
    console.log(`${selectedCategory}: ${categorizedSeriesTickers.length} series`, categorizedSeriesTickers.slice(0, 10));

    const byTag = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/series?tags=${selectedTag}`,
      { headers }
    ).then((r) => r.json());
    const taggedSeriesTickers = (byTag.series ?? []).map((s: any) => s.ticker);
    console.log(`tag=${selectedTag}: ${taggedSeriesTickers.length} series`, taggedSeriesTickers.slice(0, 10));

    const selectedTags = "Football,Soccer";
    const withBoth = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/series?category=${selectedCategory}&tags=${selectedTags}`,
      { headers }
    ).then((r) => r.json());
    const seriesTickers = (withBoth.series ?? []).map((s: any) => s.ticker);
    console.log(`${selectedCategory} + tags=${selectedTags}: ${seriesTickers.length} series`, seriesTickers.slice(0, 10));
    ```
  </Accordion>
</AccordionGroup>

## Calendar view

Two endpoints for date-based UIs:

* `GET /api/v1/calendar?date=YYYY-MM-DD`: events for one day, with pricing and score data
* `GET /api/v1/calendar/month?month=YYYY-MM`: per-date summary for month-grid views

<AccordionGroup>
  <Accordion title="Fetch events for a date">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const today = new Date().toISOString().slice(0, 10); // "YYYY-MM-DD"

    const day = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/calendar?date=${today}&category=Sports`,
      { headers }
    ).then((r) => r.json());

    const buckets = Object.entries(day.events ?? {});
    if (buckets.length === 0) {
      console.log(`No Sports events on ${today}.`);
    }
    for (const [startTime, events] of buckets) {
      console.log(`-- ${startTime} UTC --`);
      for (const event of events as any[]) {
        console.log(`  ${event.ticker}  ${event.title}`);
      }
    }
    ```
  </Accordion>

  <Accordion title="Fetch a month at a glance">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const month = "2026-04";

    const summary = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/calendar/month?month=${month}&months=1&category=Sports`,
      { headers }
    ).then((r) => r.json());

    for (const [date, milestones] of Object.entries(summary.dates ?? {})) {
      const leagues = new Set((milestones as any[]).map((m) => m.league).filter(Boolean));
      console.log(`${date}: ${(milestones as any[]).length} milestones, leagues: ${[...leagues].join(", ")}`);
    }
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  `months=12` max for year-at-a-glance views.
</Tip>

## Live events feed

`GET /api/v1/live_events` returns currently live sports events with score data. Live first, then upcoming and final.

<AccordionGroup>
  <Accordion title="&#x22;What is playing now&#x22;">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const params = new URLSearchParams({
      category: "Sports",
      status: "live",
      limit: "20",
    });

    const { liveEvents = [] } = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/live_events?${params}`,
      { headers }
    ).then((r) => r.json());

    for (const card of liveEvents) {
      console.log(`${card.ticker}  ${card.title}  status=${card.status}`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Sport filters

If your UI surfaces a sport-heavy filter sidebar (NBA, NFL, MLB, etc.), `GET /api/v1/filters_by_sports` returns the per-sport scopes and competitions you need to render those controls.

<AccordionGroup>
  <Accordion title="Get per-sport filter options">
    ```typescript theme={null}
    import "dotenv/config";

    const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
    const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

    const headers: HeadersInit = {};
    if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

    const filtersRes = await fetch(
      `${DFLOW_METADATA_API_URL}/api/v1/filters_by_sports`,
      { headers }
    ).then((r) => r.json());

    console.log("Sport ordering:", filtersRes.sportOrdering);
    ```
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Prediction Market Quickstart" href="/prediction-markets/recipes/quickstart" icon="rocket">
    Build a Kalshi prediction market integration end-to-end.
  </Card>

  <Card title="Identify a Market From a Mint" href="/prediction-markets/recipes/identify-market-by-mint" icon="bullseye">
    Reverse-lookup a market and side from any ledger or outcome mint.
  </Card>

  <Card title="Bulk Fetch Markets" href="/prediction-markets/recipes/bulk-fetch-markets" icon="layer-group">
    Hydrate multiple markets and outcome mints in one call.
  </Card>

  <Card title="Prediction Market Data Model" href="/prediction-markets/prediction-market-data-model" icon="diagram-project">
    Events, markets, outcomes, mints, and how they relate.
  </Card>
</CardGroup>

## API Routes

* [`GET /api/v1/events`](/resources/metadata-api/events/events)
* [`GET /api/v1/search`](/resources/metadata-api/search/search)
* [`GET /api/v1/series`](/resources/metadata-api/series/series)
* [`GET /api/v1/tags_by_categories`](/resources/metadata-api/tags/tags-by-categories)
* [`GET /api/v1/filters_by_sports`](/resources/metadata-api/sports/filters-by-sports)
* `GET /api/v1/calendar`
* `GET /api/v1/calendar/month`
* `GET /api/v1/live_events`