polymarket-pandas
Pandas-native Python client for the full Polymarket API surface — REST, WebSocket, Relayer, and Bridge — with automatic type coercion and DataFrame output.
Documentation | Getting Started | API Reference | Notebooks | Changelog
Features
- 102 public methods across 9 API mixins (Gamma, CLOB, Data, Rewards, Bridge, Relayer, CTF, XTracker)
- Every endpoint returns a
pd.DataFramewith automatic type coercion (datetimes, numerics, booleans) - Sync + Async HTTP clients —
PolymarketPandasandAsyncPolymarketPandas - WebSocket streaming — real-time orderbook, prices, trades, sports, crypto feeds
- pandera schemas for column documentation and optional runtime validation
- TypedDicts for dict-returning endpoints with full IDE autocomplete
- Order building & EIP-712 signing —
build_order,place_order,submit_orders(DataFrame batch) - On-chain CTF operations — merge, split, redeem positions via web3
- Title parsers — extract bracket bounds, directional thresholds, and sports lines from market titles
- Auto-pagination — offset-based and cursor-based
_all()methods - Interactive Streamlit explorer with 11 pages and Plotly charts
- MCP server with 74 tools for Claude Code / Claude Desktop
Installation
pip install polymarket-pandas
Optional extras:
pip install "polymarket-pandas[ctf]" # on-chain merge/split/redeem (web3)
pip install "polymarket-pandas[explorer]" # Streamlit dashboard (11 pages)
pip install "polymarket-pandas[mcp]" # MCP server (74 tools)
Quick Start
from polymarket_pandas import PolymarketPandas
client = PolymarketPandas()
# Get active markets sorted by volume
markets = client.get_markets(closed=False, order="volume24hr", ascending=False, limit=20)
print(markets[["slug", "question", "volume24hr", "endDate"]])
# Orderbook for a token
token_id = markets["clobTokenIds"].iloc[0]
book = client.get_orderbook(token_id)
# Price history
prices = client.get_price_history(market=token_id, interval="1d", fidelity=60)
See the Getting Started guide for a complete walkthrough.
MCP Server
Query Polymarket data from any MCP client with 74 tools covering the full API surface.
polymarket-mcp # stdio transport
polymarket-mcp --sse # SSE transport
Add to Claude Code / Claude Desktop (~/.claude/settings.json):
{
"mcpServers": {
"polymarket": {
"command": "polymarket-mcp"
}
}
}
See the MCP Server guide for the full list of 74 tools and environment variables.
Interactive Explorer
pip install "polymarket-pandas[explorer]"
polymarket-explore
11 pages covering Markets, Events, Series, Tags, Orderbook, Prices, Positions, Trades, Leaderboard, Rewards, and Bridge. Each page shows the raw DataFrame, an interactive Plotly chart, and the equivalent Python code.
Configuration
All credentials are read from environment variables (or a .env file). No auth needed for public endpoints.
export POLYMARKET_ADDRESS=0xYourProxyWallet
export POLYMARKET_API_KEY=your-api-key
export POLYMARKET_API_SECRET=your-secret
export POLYMARKET_API_PASSPHRASE=your-passphrase
Or derive API keys from your private key:
client = PolymarketPandas(private_key="0xYourKey")
creds = client.derive_api_key() # auto-sets L2 credentials
See the Configuration guide for all environment variables and authentication layers.
Builder attribution
Orders signed through this SDK default to the polymarket-pandas builder code (DEFAULT_BUILDER_CODE in polymarket_pandas/client.py) via Polymarket's builder program. Attribution funds development and hosting for the package.
Resolution order (highest priority first):
- Per-call kwarg —
build_order(..., builder_code="0x...") - Constructor field —
PolymarketPandas(builder_code="0x...") - Env var —
POLYMARKET_BUILDER_CODE=0x... - SDK default —
DEFAULT_BUILDER_CODE(polymarket-pandas)
Opting out. Pass an empty string anywhere in the chain:
# Constructor opt-out
client = PolymarketPandas(builder_code="")
# Per-call opt-out
order = client.build_order(..., builder_code="")
# Env var opt-out
# POLYMARKET_BUILDER_CODE=""
Empty string normalizes to 0x000...000 (zero bytes32) and your order will carry no attribution. Your own builder code works the same way as a string — builder_code="0x<your-bytes32>" overrides the SDK default.
The builder field is part of the signed EIP-712 struct, so the value visible in your returned SignedOrder dict is exactly what gets validated on-chain.
Examples
| Script | Description |
|---|---|
btc_5min.py |
Find BTC 5-min market, fetch orderbook and prices |
btc_5min_trade_merge.py |
Full trading flow: submit_orders, cancel, merge |
rewards_overview.py |
All 7 CLOB rewards endpoints |
xtracker_overview.py |
All 7 XTracker endpoints |
market_structures.py |
Event structures + title parsers demo |
post_only_buy.py |
Post-only order example |
rtds_ws.py |
Real-Time Data Streams via WebSocket |
user_ws.py |
Private user channel — live order and trade events |
Stability
See STABILITY.md for the semver commitment and deprecation policy. In short: symbols are deprecated for at least one minor release before removal, via @typing_extensions.deprecated (which IDEs and DeprecationWarning both surface).
Contributing
See CONTRIBUTING.md. TL;DR: uv sync --all-extras && uv run pre-commit install, then the same pytest / ruff / mypy commands CI runs.
Security
See SECURITY.md. Report vulnerabilities privately via GitHub security advisories.
License
Apache-2.0
1 maintainer
Metadata
1 maintainer
Release files for polymarket-pandas 0.13.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| polymarket_pandas-0.13.3.tar.gz | 566.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| polymarket_pandas-0.13.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 753.4 kB
Release files / polymarket_pandas-0.13.3.tar.gz
| Download URL | polymarket_pandas-0.13.3.tar.gz |
|---|---|
| Size | 566.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c49d420d01fc239b12ffea91013b259c926021ff8ab48bb7a51e752e40502d0
|
|
BLAKE2b-256 checksum How to use checksums |
34dfd7b00eeb1fa80b1838bf5decfda73c3f6e0e7d9c1a58bdcf862f4957af36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 15, 2026.
Transparency logRelease files / polymarket_pandas-0.13.3-py3-none-any.whl
| Download URL | polymarket_pandas-0.13.3-py3-none-any.whl |
|---|---|
| Size | 187.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
538e927eb83a3ab7460ae2fb589fea1d976802205c58d4b59e0927a8c5cb9330
|
|
BLAKE2b-256 checksum How to use checksums |
b8b71ff741f5584630e76362aebc3e8fff9b4031672073753d65fef1c660ab87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 15, 2026.
Transparency log
