MarikaA prediction market chart might show that the price of an outcome moved from $0.40 to $0.65.
But what actually happened between those two prices?
Did a large trade move the market?
Did liquidity disappear?
Were buyers gradually pushing up the best bid, or did the market reprice almost instantly?
Historical odds and OHLCV candles cannot answer all of these questions.
For that, you need historical prediction market data at the event level: individual trades, bid and ask quotes, and order-book updates.
This guide explains how to retrieve that data using the FinFeedAPI Prediction Markets API, select the correct market outcome, handle timestamps, and prepare the records for market replay or backtesting.
1. What Can Historical Trades, Quotes, and Order Books Tell You?
Not all historical market data describes the same activity.
| Dataset | What it records | What you can analyze |
| OHLCV | Aggregated price and volume over an interval | Price trends and volatility |
| Historical trades | Individual executed transactions | Trade flow, execution prices, and volume |
| Historical quotes | Best available bid and ask updates | Spreads, quoted liquidity, and changing trading conditions |
| Order-book updates | Changes to resting orders and liquidity | Order flow, depth changes, and historical book reconstruction |
Consider a prediction market where an outcome is trading around $0.60.
A candle tells you the price reached $0.60. A historical trade tells you where an actual execution occurred. A quote shows the available bid and ask at a particular moment.
Order-book updates provide another layer: how the liquidity available to traders changed over time.
These differences matter when developing execution models, studying market reactions to news, or evaluating whether a historical trading strategy could realistically have executed at a particular price.
2. Find the Correct Prediction Market and Outcome ID
Before downloading historical data, you need two identifiers:
exchange_id— the prediction market venue, such asPOLYMARKET.market_id— the specific tradable market outcome.
This second identifier is especially important.
A binary prediction market may have two outcomes, YES and NO, represented by separate identifiers.
For example:
WILL-EVENT-HAPPEN_YES
WILL-EVENT-HAPPEN_NO
These are illustrative IDs, but they demonstrate why selecting only the parent event or question is not sufficient.
Step 1: Discover the market
Use the historical market listing:
This returns paginated market records, including outcome names, titles, and statuses.
If you only need currently active identifiers, use:
Unlike the historical listing, /active returns market IDs without full market metadata.
Step 2: Confirm the outcome
Before proceeding, check that the selected market_id corresponds to the intended YES, NO, or other tradable outcome.
Mixing different outcomes can invalidate a backtest before the first trade is analyzed.
For more details, see the FinFeedAPI market discovery tutorial.
3. Download Historical Trades, Quotes, and Order-Book Updates
Once you have the correct market ID, you can retrieve three different historical datasets.
The examples below use a placeholder outcome ID. Replace it with the actual ID returned by market discovery.
Historical trades
Trade records can include execution prices, quantities, taker sides, trade identifiers, and timestamps.
Use these records to analyze trading intensity, execution flow, and price changes around specific events.
Historical quotes
Quote records provide best bid and ask prices, along with their associated sizes.
They are useful for calculating bid-ask spreads and observing changes in top-of-book liquidity.
Historical order-book updates
This endpoint retrieves historical limit-order events from flat files, rather than a ready-made historical snapshot for every point in time.
Depending on the dataset, records may contain update types, order identifiers, prices, sizes, sides, and timestamps.
Choose a historical time window
Each historical endpoint supports two retrieval approaches:
| Parameter | Usage |
| date=2026-04-07 | Request a particular day |
| time_start / time_end | Request a bounded time window |
| limit | Maximum records returned; default 100, maximum 10,000 |
For example, a bounded trade-history request could look like:
Historical datasets use hourly file granularity with fallback to daily files.
One important detail: setting a full-day date does not override the record limit. For larger datasets, split extraction into smaller windows and verify that all required records have been collected.
Explore the historical trades and quotes documentation for available datasets and fields.
4. Understand Timestamps Before Replaying the Market
Historical market data commonly contains two timestamps:
time_exchange— when the source exchange reports that an event occurred.time_coinapi— when CoinAPI received and processed the event.
They can differ.
For example, imagine an exchange reports a trade at 12:00:00.100, but the data is received at 12:00:00.350.
The difference may result from source latency, polling, or other processing delays.
Here is the important part:
FinFeedAPI historical requests are filtered using time_coinapi, not time_exchange.
That distinction matters for reproducible research.
If you request data from 12:00 to 13:00, the extraction window applies to processing time. An event with an earlier exchange timestamp may still appear within that window.
For backtesting, choose your sequencing rule deliberately:
- Use processing time when modeling when data became available to your system.
- Use exchange time when studying the source-reported sequence of market events, while accounting for delayed or reordered arrivals.
Do not assume the two clocks are interchangeable.
5. Reconstruct Order Books and Validate Your Historical Data
Downloading order-book updates is not the same as downloading a sequence of complete historical order books.
Historical records describe changes to the book. Reconstructing its state requires applying those changes in the correct order.
A basic reconstruction workflow looks like this:
- Identify an appropriate starting book state, such as an applicable snapshot or initial snapshot event.
- Collect the historical updates for the selected outcome and time window.
- Establish deterministic event ordering using the available timestamps and identifiers.
- Apply additions, modifications, deletions, and snapshot replacements according to the dataset's update semantics.
- Check the reconstructed book for inconsistencies before using it in a backtest.
A current snapshot can be retrieved with:
However, a snapshot captured today is not automatically a valid starting point for reconstructing yesterday's book.
For reconstruction techniques, see our companion guide: Order Book Reconstruction: What Can Go Wrong?. The general principles of sequencing and validation are useful, although prediction-market datasets may differ from crypto L2/L3 feeds in structure and depth.
Five checks before using the data
| Check | What to verify |
| Outcome identity | The market_id matches the intended outcome |
| Timestamp consistency | Records fall within the requested processing-time window |
| Quote validity | Bid does not exceed ask when both are available and comparable |
| Sizes and duplicates | Quantities are non-negative; repeated events are identified using available IDs and timestamps |
| Price representation | Prices are interpreted according to the venue and instrument, without assuming universal probability bounds |
The last point is easy to overlook.
Prediction market prices are frequently expressed as probability-like values between 0 and 1. But this should not become a universal validation rule.
Some published historical trade samples contain values above 1. Whether those values reflect contract representation, normalization, or a data-quality issue must be established before treating them as valid probabilities or erroneous observations.
Likewise, exchange timestamps generally precede processing timestamps, but this relationship should be investigated rather than enforced as an unconditional rule.
For serious research, validation is part of the data pipeline, not something performed after the backtest produces surprising results.
Build Historical Prediction Market Research With FinFeedAPI
Odds show how market expectations changed. Historical trades, quotes, and order-book updates help explain the trading activity behind those changes.
With the FinFeedAPI Prediction Markets API, developers can retrieve outcome-specific historical data, inspect execution and liquidity conditions, and prepare event-level datasets for replay, backtesting, and quantitative research.
The key is to preserve the right market identifiers, timestamps, and update semantics from the beginning.
Related Topics
- Tracking Hyperliquid HIP-4: How to Connect Outcome Markets to Your Crypto Projects
- What Are Hyperliquid Outcome Markets? HIP-4 Prediction Contracts Explained
- Prediction Markets: Complete Guide to Betting on Future Events
- Markets in Prediction Markets
- 10 Things You Should Never Do With Prediction Market Data
- Can Prediction Markets Predict Better Than Polls?
- From Market ID to Resolved Outcome: Implementing a Prediction Market Lifecycle Monitor
