polymarket-apis 2.2.0

Unified Polymarket v2 APIs with Pydantic data validation - Clob, Gamma, Data, Web3, Websockets, GraphQL clients.

polymarket-apis

Unified Polymarket v2 APIs with Pydantic data validation - Clob, Gamma, Data, Web3, Websockets, GraphQL clients.

Polymarket Mental Models

Events, Markets and Outcomes

The Polymarket ecosystem is organized hierarchically:

flowchart LR
    A([Event]) --- B([Market A])
    A --- C([Market B])
    A ~~~ Dot1@{ shape: sm-circ}
    A ~~~ Dot2@{ shape: sm-circ}
    A ~~~ Dot3@{ shape: sm-circ}
    A -.- D([Market n])
    B --- E([Outcome 1])
    B --- F([Outcome 2])
    C --- G([Outcome 1])
    C --- H([Outcome 2])

• Event — represents a proposition or question such as “How many Fed rate cuts in 2025?”.

  • Identified by a human-readable slug (e.g. how-many-fed-rate-cuts-in-2025) and an event id (e.g. 16085).

• Market — represents a specific option for the related event (e.g. 1 rate cut in 2025). An Event has 1 or more corresponding Markets. (e.g. 9 options in this case - {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025)

  • Identified by a condition id (e.g. 0x8e9b6942b4dac3117dadfacac2edb390b6d62d59c14152774bb5fcd983fc134e for 1 rate cut in 2025), a human-readable slug (e.g. 'will-1-fed-rate-cut-happen-in-2025') and a market id (e.g. 516724).

• Outcome — represents a binary option related to a market. (most commonly Yes/No, but can be e.g. Paris Saint-Germain/Inter Milan in the case of a match where draws are not possible)

  • Identified by a token id (e.g. 15353185604353847122370324954202969073036867278400776447048296624042585335546 for the Yes outcome in the 1 rate cut in 2025 market)

• The different APIs represent Events/Markets differently (e.g. Event, QueryEvent / ClobMarket, GammaMarket, RewardsMarket) but they all use to the same underlying identifiers.

Tokens

• Tokens are the blockchain implementation of Outcomes - tradable digital assets on the Polygon blockchain that users buy, hold and sell on Polygon.
• This helps ensure the logic of binary outcome prediction markets through smart contracts (e.g. collateralization, token prices going to $1.00 or $0.00 after resolution, splits/merges).

Splits and Merges

• Holding 1 Yes share + 1 No share in a Market (e.g. 'will-1-fed-rate-cut-happen-in-2025') covers the entire universe of possibilities and guarantees a $1.00 payout regardless of outcome. This mathematical relationship enables Polymarket's core mechanisms: splitting (1 pUSD → 1 Yes + 1 No) and merging (1 Yes + 1 No → 1 pUSD) at any point before resolution.
• Splits are the only way tokens are created. Either a user splits pUSD into equal shares of the complementary tokens or Polymarket automatically splits pUSD when it matches an Yes buy order at e.g. 30¢ with a No buy order at 70¢.

Unified Order Book

• Polymarket uses traditional exchange mechanics - a Central Limit Order Book (CLOB), where users place buy and sell orders that get matched by price and time priority.
• However, because the Yes and No outcomes form a complete probability universe, certain orders become mathematically equivalent - allowing the matching engine to find trades as exemplified above.
• This unified structure means every BUY order for Outcome 1 at price X is simultaneously visible as a SELL order for Outcome 2 at price (100¢ - X), creating deeper liquidity and tighter spreads than separate order books would allow.

Negative Risk and Conversions

• If the Markets in and Event collectively cover a complete universe of possibilities (e.g. {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025) and only one winner is possible, two collections of positions (made up of tokens and pUSD) become mathematically equivalent and the Event is said to support negative risk.
  • e.g. Hold 1 No token in the 0 rate cuts in 2025. This is equivalent to holding 1 Yes token in each of the other Markets {1, 2, ..., 7, 8 or more}.
• An interesting consequence is that holding No tokens in more than one Market is equivalent to Yes tokens and some pUSD.
  • e.g. Hold 1 No token on each of {0, 1, 2, ..., 7, 8 or more} rate cuts in 2025. Because only one winner is possible, this guarantees that 8 out of the 9 Markets resolve to No. This is equivalent to a position of 8 pUSD.
  • e.g. Hold 1 No token on each of {0, 1} rate cuts in 2025. This is equivalent to 1 Yes token in {2, ..., 7, 8 or more} and 1 pUSD.
• Polymarket allows for the one way (for capital efficiency) conversion from No tokens to a collection of Yes tokens and pUSD before resolution through a smart contract.

Clients overview

PolymarketReadOnlyClobClient

Read-only order book related operations.

• Order book
  • get one or more order books, best price, spread, midpoint, and last trade price by token_id
• Miscellaneous
  • get market microstructure parameters by condition_id (get_clob_market_info) - tokens, tick size, minimum order size, fees, rewards, RFQ flags, and order-age settings
  • get condition_id and its corresponding token_ids for a market by token_id
  • get crypto outcomes by slug for up/down markets
  • get recent price history by token_id in the last 1h, 6h, 1d, 1w, 1m
  • get price history by token_id in a start/end interval
  • get all price history by token_id in 2-minute increments
  • get ClobMarket by condition_id
  • get all ClobMarkets

PolymarketClobClient

Order book related operations.

• Authentication
  • private_key
  • address
  • signature_type is optional and can be derived from the address
    • signature_type=0 for EOAs (Externally Owned Accounts)
    • signature_type=1 for Email/Magic wallets
    • signature_type=2 for Safe/Gnosis wallets
    • signature_type=3 for Deposit wallets
• All operations from PolymarketReadOnlyClobClient
• Orders
  • create and post limit or market orders
  • cancel one or more orders by order_id
  • cancel all orders for a condition_id/token_id
  • cancel all orders
  • get active orders
  • send heartbeat to keep orders alive
• Trades
  • get trade history for a user with filtering by condition_id, token_id, trade_id, and time window
• Rewards
  • check if one or more orders are scoring for liquidity rewards by order_id
  • get daily earned rewards
  • check if a market offers rewards by condition_id with get_market_rewards()
  • get all active markets that offer rewards, sorted and filtered by multiple criteria, with get_reward_markets()
• Miscellaneous
  • get pUSD balance
  • get token balance by token_id
  • detect wallet signature type

PolymarketGammaClient

Market and event related operations.

• Market
  • get GammaMarket by market_id
  • get GammaMarket by slug
  • get GammaMarkets with pagination and filtering by slug, market_id, token_id, condition_id, tag_id, active/closed/archived status, liquidity window, volume window, start date window, end date window, and ordering
  • get tags for a market by market_id
• Event
  • get Event by event_id
  • get Event by slug
  • get Events with pagination and filtering by slug, event_id, tag_id, active/closed/archived status, liquidity window, volume window, start date window, end date window, and ordering
  • get all Events given some filtration
  • search Events, Tags, and Profiles by text query, tags, status, recurrence, and multiple sort modes
  • grok an event summary by event slug
  • grok an election market explanation by candidate name and election title
  • get tags for an event by event_id
• Tag
  • get Tags with pagination, ordered by any tag field
  • get all Tags
  • get Tag by tag_id
  • get Tag relations by tag_id or slug
  • get tags related to a tag by tag_id or slug
• Sport
  • get Teams with pagination, filtered by league, name, and abbreviation
  • get all Teams given some filtration
  • get Sports with pagination, filtered by name
  • get sports metadata
• Series
  • get Series with pagination, filtered by slug and closed status, and ordered by any series field
  • get all Series given some filtration
• Comments
  • get comments by parent_entity_type and parent_entity_id with pagination, ordered by any comment field
  • get comments by comment_id, returning all comments in a thread
  • get comments by user base address with pagination, ordered by any comment field
• Miscellaneous
  • get public profile by user address

PolymarketDataClient

Portfolio related operations.

• Positions
  • get positions with pagination by user address, filtered by condition_id, position size, redeemability, mergeability, and title
• Trades
  • get trades with pagination, filtered by condition_id, user address, side, taker-only status, cash amount, and token amount
• Activity
  • get activity with pagination by user address, filtered by type, condition_id, time window, side, and sort order
• Holders
  • get top holders by condition_id
• Value
  • get positions value by user address and condition_ids
  • condition_ids is None means total value of positions
  • condition_ids is str means value of positions on one market
  • condition_ids is list[str] means sum of values of positions on multiple markets
• Closed positions
  • get closed positions, filtered by condition_id
• Miscellaneous
  • get total number of markets traded by user address
  • get open interest for a list of condition_ids
  • get live volume for an event by event_id
  • get pnl timeseries by user address for a period (1d, 1w, 1m, all) with frequency (1h, 3h, 12h, 1d)
  • get overall pnl/volume by user address for a recent window (1d, 7d, 30d, all)
  • get user rank on the profit/volume leaderboards by user address for a recent window (1d, 7d, 30d, all)
  • get top users on the profit/volume leaderboards for a recent window (1d, 7d, 30d, all)

PolymarketWeb3Client / PolymarketGaslessWeb3Client

Blockchain clients for blockchain based Polymarket operations. Both clients support the same core operations detailed below

• PolymarketWeb3Client submits transactions directly on-chain, so the base EOA for the provided private_key must hold POL for gas, regardless of signature_type.

• PolymarketGaslessWeb3Client submits transactions through the relayer, and Polymarket pays for gas

• Authentication

  • PolymarketWeb3Client
    • private_key
    • signature_type
  • PolymarketGaslessWeb3Client
    • private_key
    • signature_type
    • either relayer_api_key (create here) - unlimited rate limit
      • the client derives RELAYER_API_KEY_ADDRESS from the wallet automatically
    • or builder_creds (create here) as ApiCreds

• Supported wallet types

  • PolymarketWeb3Client
    • EOA wallets (signature_type=0)
    • Email/Magic proxy wallets (signature_type=1)
    • Safe/Gnosis wallets (signature_type=2)
  • PolymarketGaslessWeb3Client
    • EOA wallets (signature_type=0) are NOT supported for gasless transactions
    • Email/Magic proxy wallets (signature_type=1)
    • Safe/Gnosis wallets (signature_type=2)
    • Deposit wallets (signature_type=3)

• Setup and deployment

  • set approvals/disapprovals for all needed pUSD and conditional token spenders
    • Safe/Gnosis and Deposit wallet holders need to run deploy_safe_wallet() or deploy_deposit_wallet() respectively before using Safe transactions if the Safe has not been deployed yet

• Balances

  • get POL balance by user address
  • get pUSD balance by user address
  • get token balance by token_id and user address

• Transfers

  • transfer pUSD to another address with recipient address and amount
  • transfer token to another address with token_id, recipient address, and amount

• Token/pUSD conversions

  • split pUSD into complementary tokens with condition_id, amount, and neg_risk
  • merge complementary tokens into pUSD with condition_id, amount, and neg_risk
  • redeem tokens into pUSD with condition_id, amounts array of [Yes shares, No shares], and neg_risk
  • convert one or more No tokens in a negative-risk event into pUSD plus Yes tokens on the other markets in the event
  • enable/disable auto-redeem

• Miscellaneous

  • detect wallet signature type
  • get base/poly proxy/safe proxy/deposit wallet address from private_key

AsyncPolymarketWebsocketsClient / PolymarketWebsocketsClient

Market data, authenticated user events, crypto/equity prices, comments/reactions, activity, sports

Use AsyncPolymarketWebsocketsClient for production services, bots, and multi-stream workflows. Use PolymarketWebsocketsClient when you need a blocking wrapper around the same async implementation.

• Connection model

  • open_*_connection() starts a stream and returns a handle for health checks, dynamic subscription management, and explicit shutdown
  • run_*_stream() starts a stream and waits until it closes
  • callbacks may be synchronous or async
  • default callback payloads are parsed Pydantic events
  • set parse_messages=False to receive RawMessage

• Market socket

  • subscribe by token_ids
  • receive book snapshots, price changes, tick-size changes, last-trade prices, best bid/ask updates, new-market events, and market-resolution events
  • tracks whether the local market book state is synchronized after a full snapshot

• User socket

  • subscribe with ApiCreds, optionally restricted by condition_ids
  • receive order events (live, canceled, matched)
  • receive trade events (matched, mined, confirmed, retrying, failed)
  • defaults to disconnecting on queue overflow to avoid silently dropping user activity

• Real-time data socket

  • subscribe with RTDS subscription objects or dictionaries
  • dynamically subscribe() and unsubscribe() without reconnecting
  • receive trades / orders_matched events filtered by event slug or market slug
  • receive crypto/equity prices
  • receive comment/reaction events (created, removed)

• Sports socket

  • receive sports game state updates (game start, score change, period change, game end)

• Reliability

  • automatic reconnect with configurable backoff
  • heartbeats and pong tracking
  • structured lifecycle, parse, subscription, stale-feed, and queue-overflow logs
  • bounded message queues with configurable overflow policy
  • health snapshots via connection.health / get_health()

Notebook quick start:

from polymarket_apis import AsyncPolymarketWebsocketsClient

async def on_event(event: object) -> None:
    print(event)

client = AsyncPolymarketWebsocketsClient()

connection = await client.open_market_connection(
    token_ids=["...", "..."],
    process_event=on_event,
)

check health at:

connection.health() # or get bool at connection.is_healthy()

close:

await connection.close()
await client.close()

PolymarketGraphQLClient / AsyncPolymarketGraphQLClient

Goldsky-hosted subgraph queries.

• Endpoints
  • activity_subgraph
  • fpmm_subgraph
  • open_interest_subgraph
  • orderbook_subgraph
  • pnl_subgraph
  • positions_subgraph
  • sports_oracle_subgraph
  • wallet_subgraph
• Queries
  • query() takes a GraphQL query string and returns the raw JSON