Skip to main content
Prediction markets are organized in a three-level hierarchy: Series, Events, and Markets. Understanding this structure is essential for discovering and trading prediction market outcome tokens.

​
Hierarchy Overview

The prediction market structure follows this hierarchy:
  1. Series - Collections of related events organized around a common theme
  2. Events - Real-world occurrences or questions that contain one or more markets
  3. Markets - Individual binary markets that traders interact with
When building discovery UIs, you’ll typically start by querying series or events, then drill down to specific markets to access token addresses for trading. See the Discover Prediction Tokens guide for practical examples.

​
Series

A series is a collection of related events that share a common theme, category, or pattern. Events within a series typically:
  • Look at similar data for outcome determination
  • Cover disjoint time periods (e.g., weekly earnings announcements, daily weather forecasts)
  • Have no logical outcome dependency between events
Series serve as templates for recurring events. For example, a “Weekly Earnings Reports” series might contain multiple events, each representing a different company’s quarterly earnings announcement.

​
Series Properties

Series include metadata such as:
  • Ticker: Unique identifier used to filter events (e.g., EARNINGS-Q1)
  • Title: Human-readable series name
  • Category: Organizational category (e.g., “Finance”, “Technology”)
  • Tags: Associated tags for filtering (e.g., “Earnings”, “Stocks”)
  • Frequency: How often events in this series occur (e.g., “Daily”, “Weekly”)
You can query series using the Series API endpoints and filter events by series ticker to discover related markets.

​
Events

An event is a real-world occurrence or question that prediction markets are based on. Events are the primary unit that applications should interact with when building prediction market UIs. Events can contain:
  • Single Market Event (SMP): One market
  • Group Market Event (GMP): Two or more related markets
For example, an event titled “Which city will host the 2030 World Expo?” might contain 5 separate markets, each asking whether a specific city (e.g., Riyadh, Busan, Rome) will be selected as the host.

​
Event Properties

Events include:
  • Ticker: Unique identifier for the event
  • Title: Human-readable event name
  • Subtitle: Additional context or description
  • Series Ticker: Links the event to its parent series
  • Markets: Array of markets associated with the event (when requested with withNestedMarkets=true)
Events are organized into series and can be queried using the Events API endpoints. When fetching events with withNestedMarkets=true, you’ll receive the associated markets nested within each event response.

​
Markets

A market is the fundamental trading unit: a specific binary market that allows traders to bet on a particular outcome. Each market has two outcome tokens:
  • YES tokens: Represent a position that the outcome will occur
  • NO tokens: Represent a position that the outcome will not occur
Markets contain the on-chain token addresses (yesMint and noMint) that you use when trading through the DFlow Trade API.

​
Market Properties

Markets include:
  • Ticker: Unique identifier for the market
  • Title: Market question or description
  • Status: Current market status (e.g., active, initialized, settled)
  • Accounts: Object containing token addresses (yesMint, noMint) keyed by settlement mint
  • Volume: Trading volume for the market
  • Open Interest: Current open positions
  • Timing: Open time, close time, and expiration time
You can query markets directly using the Markets API endpoints or access them nested within event responses.

​
Working with the Hierarchy

​
Discovery Flow

When building discovery UIs, you’ll typically follow this flow:
  1. Start with Series or Categories: Query series by category or tags to find relevant themes
  2. Filter Events: Use series tickers to filter events, or query events directly with status filters
  3. Access Markets: Request events with withNestedMarkets=true to get market data including token addresses

​
Direct Market Access

You can also query markets directly by mint address or market ticker:

​
Key Takeaways

  • Series organize related events around common themes and categories
  • Events are the primary interaction unit and can contain one or more markets
  • Markets are the fundamental trading units with YES/NO outcome tokens
  • Use the Events API with withNestedMarkets=true to efficiently discover markets
  • Market accounts objects contain the token addresses needed for trading

Discover Prediction Market Outcome Tokens

Learn how to use the Prediction Market Metadata API to discover markets and access token addresses

Events API Reference

Complete reference for querying events and filtering by series, status, and other parameters

Markets API Reference

Access market data, token addresses, pricing, and trading information

Series API Reference

Query series templates and filter by categories and tags