polymarket-pandas 0.13.2

Pandas API client to Polymarket

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.DataFrame with automatic type coercion (datetimes, numerics, booleans)
• Sync + Async HTTP clients — PolymarketPandas and AsyncPolymarketPandas
• 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):

1. Per-call kwarg — build_order(..., builder_code="0x...")
2. Constructor field — PolymarketPandas(builder_code="0x...")
3. Env var — POLYMARKET_BUILDER_CODE=0x...
4. 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