Market Metadata in Prediction Markets: A Schema Guide

Market metadata is the descriptive layer around a prediction market contract: its identifiers, question text, outcomes, lifecycle status, timestamps, category, and the rules that decide how it resolves. It is not prices or trades. It is the dimension table that tells your code what a contract is, whether it can trade, and how and when it will pay out. If you build bots, research pipelines, or AI agents on Polymarket and Kalshi, getting this layer right matters more than most people expect, because every join, filter, and execution rule depends on it.

Assymetrixdata.assymetrix.comWork with Unified Market DataAssymetrix brings prediction market data from Polymarket, Kalshi, and Limitless into one intelligence layer through a single API integration.Explore the Data API

TL;DR

• Metadata is the dimension table of a prediction market: identifiers, status, timestamps, outcomes, category, and resolution rules. Price and trade data hang off it.

• Venues model the same idea differently. Polymarket keys markets by a condition ID and outcome token IDs. Kalshi keys them by tickers and event tickers, with its own status strings.

• Normalize status into a small shared lifecycle, and keep the raw venue value next to it so you can audit mapping errors.

• Prioritize resolution fields (source, timing, determinacy) over titles and descriptions. Titles are written for people, not programs.

• Store metadata as versioned snapshots, because status, close times, and resolution details change after you first see a market.

Table of Contents

• What counts as market metadata

• How Polymarket and Kalshi describe a market

• Why resolution fields outrank titles

• Normalizing status into a shared lifecycle

• Canonical IDs: the join key that holds everything together

• A minimal normalized schema

• Using metadata in live trading systems

• Our perspective

• Getting normalized metadata without building it yourself

• Common mistakes to avoid

• FAQ

• Sources

What counts as market metadata

A prediction market contract has three kinds of data. Trade data records what happened: fills, quotes, order book depth. State data records what the market is right now: last price, open interest, volume. Metadata records what the market is: a stable description that changes rarely, but matters when it does.

For a binary market, the useful metadata falls into six groups:

1. Identity. The venue’s native IDs and any cross-venue key you assign.

2. Question and outcomes. Title, subtitle or description, and the labels for each outcome.

3. Lifecycle. Status, creation time, open time, close time, expiration, and resolution time.

4. Classification. Category, tags, event grouping, and whether a market belongs to a multi-outcome event.

5. Resolution. Who or what decides the result, the rule text, and the final outcome once known.

6. Mechanics. Price units, tick size, whether the contract can close early, and settlement timers.

Most developers start with titles and categories because those are visible on the venue’s website. That is the wrong priority, and the sections below explain why.

How Polymarket and Kalshi describe a market

The two largest venues in the US conversation structure metadata differently, and your schema has to absorb both.

Polymarket

Polymarket’s market metadata is served through its Gamma API. In one developer walkthrough of the API, a market is described as the basic tradable unit, tied to an on-chain condition identified by a conditionId, with a pair of outcome tokens identified by clobTokenIds for binary markets. That split matters. The condition ID identifies the question. The token IDs identify each side you can actually trade on the order book. Pricing endpoints take the token ID, so a pipeline that stores only the condition ID cannot fetch a quote without a second lookup.

The same walkthrough notes that market listings can be filtered by tag, by a closed flag, and by condition IDs. Note what that implies: the venue’s native status filter is a boolean-style flag, not a rich lifecycle.

Kalshi

Kalshi is organized around tickers. Its Get Markets reference shows a market object carrying a ticker, an event_ticker, a market_type, title and subtitle fields, and a set of timestamps: created, open, close, expiration, and latest expiration. It also exposes a settlement_timer_seconds field, a result field, a can_close_early flag, and price fields in both cents and dollar strings. The listing endpoint documents a status filter with values for unopened, open, closed, and settled markets.

Two details trip people up. First, Kalshi prices appear in more than one unit, so a normalizer must pick one (we suggest decimal probability between 0 and 1) and convert at ingestion. Second, the status values accepted by the filter are not necessarily the full set of values you will see on returned objects, so treat status as an open vocabulary and log anything unrecognized rather than crashing on it.

Side by side

Treat this table as a starting map, not a contract. Venues add and rename fields, so verify against current documentation before you hard-code anything.

Why resolution fields outrank titles

The academic literature has a name for the core problem. The SoK on market microstructure for decentralized prediction markets surveys the history of these markets, and the concept of settlement legibility, meaning how clearly and verifiably a market’s outcome can be determined, is central to how these designs are discussed. For a data engineer, the practical reading is simple: a market is only as machine-usable as its resolution is legible.

Titles and descriptions are written for human discovery. They are fine for a search box. They are poor keys, because they get edited, they are ambiguous across venues (two markets titled almost the same can resolve on different sources or different dates), and they say little about how a dispute would be handled.

So the fields we would rank highest for any trading or research pipeline are:

• Resolution source. Which oracle, data feed, or authority settles the market.

• Resolution rule text. Stored verbatim, hashed, and versioned.

• Close time versus expiration time. These are different things, and the gap is where bots lose money.

• Final outcome and resolution timestamp. Needed for backtests that score predictions.

• Settlement delay. How long between the event ending and funds becoming claimable.

Two markets that look identical on price can have very different risk once you read these fields. A cross-venue spread that looks like free money may exist precisely because one contract resolves on a stricter rule than the other. That is the main reason cross-venue arbitrage is a metadata problem before it is a pricing problem.

Normalizing status into a shared lifecycle

The most common bug in multi-venue prediction market code is a status mismatch. A bot sees one venue’s “closed” and assumes the market is settled, or sees the other venue’s “settled” and does not realize a market can be closed but unresolved for hours or days.

A robust approach is a small shared lifecycle with three or four states, plus the raw value:

Store three columns, not one: status_raw (exactly what the venue sent), status_unified (your mapping), and status_mapped_at or a mapping version. When a venue introduces a new status string, you will see rows where the mapping is null instead of silently wrong values.

A few mapping rules we have found worth writing down:

• Never infer resolved from a timestamp. A close time in the past means trading should be halted, not that an outcome exists. Require a recorded outcome.

• Treat archival as a visibility flag, not a lifecycle state. An archived market may be resolved, or it may be an abandoned one.

• Handle early closure. Where a market can close before its scheduled time, the scheduled close time is a forecast, not a fact. Update it when the venue changes it.

• Keep a terminal state for voided or canceled markets if the venue supports them, so they are not scored as normal outcomes in a backtest.

If you are designing the lifecycle layer as part of a wider system with registries and monitoring, the same discipline appears in model lifecycle management practices for regulated teams: version every artifact, record who changed what, and keep an audit trail you can replay.

Canonical IDs: the join key that holds everything together

A unified metadata table needs one key that survives across venues and across venue-side renames. We call it a canonical ID. The design rules are:

• It is generated by you, not derived from a title.

• It maps one-to-many to venue-native identifiers (condition ID plus token IDs on one side, ticker on the other).

• It is stable when the venue edits the title or description.

• Equivalence across venues is a separate table. Two contracts on the same real-world question get linked by a reviewed relationship with a confidence level and a note on resolution differences, rather than being merged into one row.

That last point is where most naive aggregators fail. “Same question” is a judgment about resolution rules, not about wording. Keep the equivalence link separate and annotate it with the differences you found: source, timing, edge cases. We cover the identifier design in more depth in our guide to canonical IDs for cross-venue prediction market data.

A minimal normalized schema

Here is a compact starting point for a market dimension table. It is deliberately small.

The last two columns are the ones people skip. Metadata changes: close times move, statuses advance, rule text gets clarified. If you overwrite rows in place, your backtest will use information that was not available at the time. Store each version with a validity window and query it point-in-time. Our write-up on reproducible dataset versioning for prediction markets goes through the workflow.

Using metadata in live trading systems

Metadata earns its keep at execution time. Before a bot sends an order, a short pre-trade check against the market dimension table can stop a surprising number of mistakes:

1. Is status_unified equal to open?

2. Is the current time before closes_at, with a buffer for markets that can close early?

3. Has rules_text_hash changed since the strategy was approved?

4. For a cross-venue pair, does the equivalence link still carry an acceptable resolution-difference flag?

5. Is the price in the unit your strategy expects?

The same logic applies when you compare a backtest to live behavior. Gaps between simulated and live fills are well documented in other trading domains, and a verified comparison of backtest versus live trading results is a useful reminder to measure your own slippage rather than assume it. In prediction markets, stale metadata is one of the quieter causes of that gap: the backtest thought a market was tradable when it had already halted.

For AI agents, the metadata layer is even more important. An agent reading a market title may form a confident view about the wrong contract. Give the agent structured fields (resolution source, close time, unified status, outcome definitions) as part of its tool output, not just the headline question. We describe that pattern in how AI agents use prediction market data to trade autonomously.

Our perspective

We index trading activity across Polymarket, Kalshi, and Limitless, and the same lesson keeps repeating: the hard part of cross-venue data is rarely volume. It is meaning. Prices are numbers and they join easily. Metadata is a set of claims about what those numbers refer to, and those claims differ between venues in ways a title will never reveal.

That is why we treat canonical IDs, normalized status, and resolution fields as first-class data instead of decoration. A venue-neutral layer is only useful if it keeps the differences visible. Normalization should compress the mess into a schema your code can use, but it should never hide the raw value or the resolution quirk that makes two similar markets non-equivalent. When a mapping has to be judgment, we want the judgment recorded, versioned, and reversible.

Our advice to anyone building their own pipeline: spend your first week on the dimension table, not the price stream. Every later mistake traces back to it.

— Dean

Getting normalized metadata without building it yourself

If you would rather not maintain venue mappings, our Data API provides cross-venue prediction market data for Polymarket, Kalshi, and Limitless through a single integration, with normalized market schemas and historical depth for backtests. For a Python workflow, start with the Python prediction market data guide.

Common mistakes to avoid

• Joining on titles. They change and they collide.

• Collapsing status into a boolean. Closed and resolved are different states with different risk.

• Overwriting metadata in place. You lose point-in-time correctness.

• Merging equivalent-looking markets. Link them and annotate the rule differences instead.

• Mixing price units. Convert once at ingestion and record the raw unit.

• Ignoring early-close flags. A scheduled close time can move.

FAQ

What is market metadata in a prediction market?

It is the descriptive data about a contract rather than its trading activity: identifiers, question text, outcomes, status, timestamps, category, and resolution rules. Prices and trades reference it through keys such as a condition ID, a token ID, or a ticker.

Why can’t I just use market titles to match Polymarket and Kalshi contracts?

Titles are written for people and are often edited, and similar wording can hide different resolution sources or dates. Match markets through reviewed equivalence links between canonical IDs, and record any differences in resolution rules next to the link.

How many status values should a unified schema have?

Three or four is enough for most trading systems: upcoming, open, closed, and resolved. Keep the venue’s raw status in a separate column so you can audit the mapping and catch new values when a venue adds them.

Which metadata fields matter most for arbitrage?

Resolution source, resolution rule text, close and expiration times, and settlement timing. These determine whether two contracts are truly the same bet and how long capital stays locked, which is what separates a real spread from a mismatched pair.

Sources

• The Polymarket API: Architecture, Endpoints, and Use Cases

• Get Markets, Kalshi API documentation

• SoK: Market Microstructure for Decentralized Prediction Markets (DePMs)