PredictionData Python Client
A Python library for streaming historical market data from the PredictionData API. Access order books, trades, and on-chain fills for prediction markets.
Installation
pip install predictiondata
Quick Start
from predictiondata import PredictionDataClient, Channel
# Initialize client with your API key
client = PredictionDataClient(api_key="<YOUR_API_KEY>")
# Stream historical data
messages = client.replay(
exchange="polymarket",
from_date="2024-11-01",
to_date="2024-11-15",
filters=[Channel(name="trades", symbols=["will-trump-win-2024/YES"])]
)
async for exchange_timestamp, message in messages:
print(f"Time: {exchange_timestamp}ms, Trade: {message}")
Features
- Async streaming - Efficiently stream large amounts of historical data
- Multiple data types - Access order books, trades, and on-chain fills
- Flexible filtering - Filter by market slug or token ID
- Type-safe - Full type hints for better IDE support
Data Types
Order Books
Incremental order book reconstructions with bid/ask prices and sizes.
Channel(name="books", symbols=["will-trump-win-2024/YES"])
Schema:
exchange_timestamp(int): Exchange timestamp in millisecondslocal_timestamp(int): Server capture timestamp in millisecondsask_prices(str): Comma-separated ask pricesask_sizes(str): Comma-separated ask sizesbid_prices(str): Comma-separated bid pricesbid_sizes(str): Comma-separated bid sizes
Trades
Executed trades from the order book.
Channel(name="trades", symbols=["will-trump-win-2024/YES"])
Schema:
exchange_timestamp(int): Exchange timestamp in millisecondslocal_timestamp(int): Server capture timestamp in millisecondsside(str): "BUY" or "SELL"size(float): Trade sizeprice(float): Trade price
On-chain Fills
On-chain settlement data from the Polygon blockchain.
Channel(name="onchain_fills", symbols=["will-trump-win-2024/YES"])
Schema:
block_number(int): Blockchain block numberblock_timestamp(int): Block timestamp in millisecondsside(str): "BUY" or "SELL"size(float): Fill sizeprice(float): Fill pricemaker(str): Maker addresstaker(str): Taker address
Usage Examples
Stream Multiple Markets
from predictiondata import PredictionDataClient, Channel
async def main():
client = PredictionDataClient(api_key="your_api_key")
messages = client.replay(
exchange="polymarket",
from_date="2024-11-01",
to_date="2024-11-15",
filters=[
Channel(name="trades", symbols=[
"will-trump-win-2024/YES",
"will-biden-win-2024/YES"
])
]
)
async for exchange_timestamp, message in messages:
print(f"Market: {message['_symbol']}")
print(f"Side: {message['side']}, Size: {message['size']}, Price: {message['price']}")
await client.close()
# Run with asyncio
import asyncio
asyncio.run(main())
Use Token IDs Instead of Slugs
Channel(name="onchain_fills", token_ids=["0x1234567890abcdef..."])
Fetch Single Day
For non-streaming use cases, fetch a complete day of data:
async def fetch_example():
client = PredictionDataClient(api_key="your_api_key")
data = await client.fetch_day(
exchange="polymarket",
data_type="trades",
identifier="will-trump-win-2024/YES",
date="2024-11-15"
)
print(f"Found {len(data)} trades")
await client.close()
Context Manager
Use async context manager for automatic cleanup:
async def main():
async with PredictionDataClient(api_key="your_api_key") as client:
messages = client.replay(
exchange="polymarket",
from_date="2024-11-01",
to_date="2024-11-15",
filters=[Channel(name="books", symbols=["btc-above-100k/YES"])]
)
async for exchange_timestamp, message in messages:
# Process messages
pass
API Reference
PredictionDataClient
Main client class for accessing the PredictionData API.
Constructor:
PredictionDataClient(api_key: str, base_url: str = "http://datasets.predictiondata.dev")
Methods:
-
replay(exchange, from_date, to_date, filters)- Stream historical data- Returns:
AsyncIterator[Tuple[int, Dict[str, Any]]](yields exchange_timestamp, message)
- Returns:
-
fetch_day(exchange, data_type, identifier, date, use_slug=True)- Fetch single day- Returns:
List[Dict[str, Any]]
- Returns:
-
close()- Close the client session
Channel
Represents a data channel filter.
Constructor:
Channel(name: str, symbols: List[str] = None, token_ids: List[str] = None)
name: Data type - "books", "trades", or "onchain_fills"symbols: List of market slugs (format: "event-slug/OUTCOME")token_ids: List of token IDs (alternative to symbols)
Market Identifiers
Markets can be identified by either:
-
Slug (format:
event-slug/OUTCOME):- Example:
will-trump-win-2024/YES - Use for human-readable queries
- Example:
-
Token ID (contract address):
- Example:
0x1234567890abcdef... - Use for programmatic queries
- Example:
Error Handling
The client handles missing data gracefully:
async for exchange_timestamp, message in client.replay(...):
try:
# Process message
pass
except Exception as e:
print(f"Error processing message: {e}")
Missing data files (404 responses) are skipped automatically.
Development
Install Development Dependencies
pip install -e ".[dev]"
Run Tests
pytest
Format Code
black predictiondata/
License
MIT License
Support
- Documentation: https://predictiondata.dev/docs
- Issues: https://github.com/predictiondata/predictiondata_client/issues
- Email: calder@predictiondata.dev
Changelog
0.1.0 (2025-11-17)
- Initial release
- Support for books, trades, and on-chain fills
- Async streaming API
- Market filtering by slug or token ID
Metadata
Release files for predictiondata 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| predictiondata-0.1.1.tar.gz | 11.9 kB | Without provenance | Details for predictiondata-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| predictiondata-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for predictiondata-0.1.1-py3-none-any.whl |
Total release size: 20.8 kB
Release files / predictiondata-0.1.1.tar.gz
| Download URL | predictiondata-0.1.1.tar.gz |
|---|---|
| Size | 11.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8fcc54d189e5c1fe85aa0ffbb9046847ef267b3e51f3ad9c930ae735eceeeb48
|
|
BLAKE2b-256 checksum How to use checksums |
6ec443edde5c8acd0d1bddc439dab388a58847a39fba852495ea41cdbc578403
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / predictiondata-0.1.1-py3-none-any.whl
| Download URL | predictiondata-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4e2080234627a7f4aef24ec83bf054674ec5d27a6fb2fa163255d35d0f6861d2
|
|
BLAKE2b-256 checksum How to use checksums |
f22e2c884fd62b883fa49d74849b1015feb0a8f8731fe51ace220f6f19d1d4b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for predictiondata 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.