Polymarket API Explained: Gamma, CLOB, WebSocket and SDK

Polymarket API is not one but a whole bunch: one for market discovery, one for prices/orders, one for positions/history, WebSocket feeds, too. No sign-up or authentication are required to read market data, while trading needs a wallet signature and API key. Here is how the structure works mapped out, all calls a bot needs to do explained in-depth, plus the major changes of 2026 that make many tutorials obsolete.

What changed in 2026

• The outdated Python client, py-clob-client, was archived on 25th of May 2026 and stopped functioning. Current version: polymarket-client for Python. TypeScript: @polymarket/client.

• Trading collateral is pUSD, ERC-20 token on Polygon backed by USDC, not USDC.e anymore.

• New accounts use a Deposit Wallet (signature type 3) by default.

• Each signer now gets its own token bucket for orders, tiered by maker trading volume.

Everything here comes from Polymarket's developer documentation, as read on 7th of November 2026. The endpoints change frequently, so confirm details in the docs before a bot goes live.

The Polymarket API at a glance

A regular bot would require one use of Gamma to discover the markets and token IDs, the CLOB to read the order book and trade, and the market WebSocket to stay current.

Reading market data without a key

Public market data needs no account and no access key. Find a market through Gamma, then ask the CLOB for its order book.

# Open markets from Gamma (first 5)
curl "https://gamma-api.polymarket.com/markets?closed=false&limit=5"

# Order book, best price, midpoint and spread for one outcome token
curl "https://clob.polymarket.com/book?token_id=TOKEN_ID"
curl "https://clob.polymarket.com/price?token_id=TOKEN_ID&side=BUY"
curl "https://clob.polymarket.com/midpoint?token_id=TOKEN_ID"
curl "https://clob.polymarket.com/spread?token_id=TOKEN_ID"

# Price history at one-hour intervals
curl "https://clob.polymarket.com/prices-history?market=TOKEN_ID&interval=1w&fidelity=60"

Every market comes with two tokens, Yes and No, and each CLOB call needs the token for the outcome you care about. Gamma's market object stores them in clobTokenIds as a JSON string, so parse it first; newer V2 markets list them under positionIds.

The /book response gives you more information about the rules of the market including tick_size (the allowed price increments, from 0.1 down to 0.0001), min_order_size, and neg_risk. Read them per market instead of hard-coding them, because the tick size can change while a market runs.

Authentication: L1 and L2

Trading uses two levels.

• Level-1: Wallet Signature. You sign an EIP-712 message with your wallet private key to ensure that you have control over the account. Using that, you can either generate credentials (POST /auth/api-key) for the API or derive existing ones (GET /auth/derive-api-key), getting API key, passphrase and a secret.

• Level-2: API credentials. Each trading call is signed with HMAC-SHA256 using those credentials, and the signature travels in the request headers.

The process of placing an order involves both of them – Level-2 validates a particular request, and the signature of order itself provided via the wallet ensures authorization. The SDK handles everything mentioned above based only on your private key.

Signature used on the transaction depends on the wallet connected to the account:

Current SDKs work out the wallet type on their own. If you assemble requests yourself, picking the wrong type can cause order rejections.

Placing an order with the Python SDK

You will need Python 3.11 or later for the unified Python SDK:

python3 -m venv ~/pm && . ~/pm/bin/activate
pip install polymarket-client

This simple script reads a market's order book without credentials, then places one small post-only limit order and cancels it. This is the safest first trade to try because post-only indicates that orders will be rejected, not filled, when they cross the book.

import asyncio
import os

from polymarket import AsyncPublicClient, AsyncSecureClient

MARKET_URL = "https://polymarket.com/event/your-market-slug"


async def main() -> None:
    async with AsyncPublicClient() as public:
        market = await public.get_market(url=MARKET_URL)
        yes = market.outcomes.yes
        asset_id = yes.position_id or yes.token_id
        book = await public.get_order_book(asset_id=asset_id)
        best_bid = book.bids[-1].price if book.bids else None  # bids: lowest first
        best_ask = book.asks[-1].price if book.asks else None  # asks: highest first
        print(market.question, best_bid, best_ask, book.tick_size, book.min_order_size)

    async with await AsyncSecureClient.create(
        private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
    ) as client:
        order = await client.place_limit_order(
            asset_id=asset_id,
            side="BUY",
            price="0.05",  # far below the market; must be a multiple of the tick size
            size=str(book.min_order_size),
            post_only=True,
        )
        if order.ok:
            print("placed", order.order_id, order.status)
            await client.cancel_order(order_id=order.order_id)


asyncio.run(main())

POLYMARKET_PRIVATE_KEY should be set in the environment and not within the code. When you have an account that has a separate signer and account wallet, AsyncSecureClient.create also takes wallet= with the account wallet address.

Order Types Supported by the CLOB:

post_only operates on orders of type “GTC” and “GTD.” On buying through market orders, the amount is in dollars before fees, so set a spend cap if you need a hard limit. The limit of orders you can submit for processing per batch is 15.

Live data over WebSocket

Rather than polling the book and burning rate limit, subscribe:

{"assets_ids": ["TOKEN_ID"], "type": "market"}

Send the subscription frame above to wss://ws-subscriptions-clob.polymarket.com/ws/market to get book, price_change, last_trade_price and tick_size_change events. {"assets_ids": [...], "operation": "subscribe"} lets you add or remove tokens on the same connection. To avoid being disconnected, you must send the text frame PING in 10-second intervals.

The user channel provides your own order and trade updates. It requires your API key, your secret and a passphrase inside the subscription message. A bot should assume a disconnection is temporary – just reconnect, resubscribe and make a REST call to reconcile open orders before placing any trades.

Rate limits

Limits are usually enforced per IP address for 10 seconds; those that exceed them are queued (i.e., throttled) but not denied. Important limits for bots include:

Besides, order sending and cancellations use a token bucket for each signer. In the standard tier there are 40 order tokens per second; other tiers are unlocked by 30-day maker volume. Polymarket has run this limiter in warning mode since July 24, 2026. Once it takes effect, an empty token bucket returns HTTP 429 with a Retry-After response header. The Poly-RateLimit-Remaining header tells you how much is left, so slow down before it reaches zero.

Fees and collateral

Makers pay no fees; only takers do. size × fee rate × p × (1 − p) is the fee per trade for takers; therefore, they get high fees in price intervals close to 0.50, and they will get small fee amounts if the price level is closer to the extremes. Fee amount depends on the market type and starts at 0.04 in politics and finance while it ends at 0.07 in cryptos, and geopolitical markets have zero fees. In most fee-charging categories, makers also receive part of the fees back as rebates.

Polymarket facilitates trades on their platform in pUSD on the Polygon blockchain (chain ID 137). There is a Polymarket onramp contract to convert USDC.e into pUSD, and the exchange contracts need token approvals before your first order. The SDK requests a missing approval automatically when an order is rejected for allowance.

Where you can call the trading API from

Polymarket validates the source of request. Function GET https://polymarket.com/api/geoblock returns blocked status for requesting IP and detected location.

• Completely blocked countries: OFAC countries, for example Iran, Syria, Cuba, North Korea and occupied areas in Ukraine.

• Close-only on the website and API: a long list which includes countries like the USA, the UK, Germany, France and several Canadian provinces. Existing positions can be closed, but no new ones opened.

• Close only on website: some countries like Netherlands and Japan. Docs explicitly state that there's no restriction on the API for these countries.

Restrictions have to be considered when choosing a server because this particular check is based on the origin of the request. Perform geoblock call from your server prior to deploying the trading algorithm. Restrictions also apply to you personally: Polymarket's terms follow where you are, and a server in another country does not change that.

Within these restrictions, latency is still important factor for MM or arbitrage loop. Instead of assuming, measure: our latency checker is configurable host wise, so you can point it at clob.polymarket.com and compare the round trip from each of our locations. Also looking glass runs network tests from our network to the same host. You can rent VPS from Amsterdam and from Tokyo - our two locations in countries where the docs leave the API unrestricted.

Frequently asked questions

Is the Polymarket API free?

Yes. The market information, market history, and order book have no charges and costs. Trading costs the taker fee on filled orders; makers pay no fees.

Does py-clob-client still work?

No. It was archived on May 25, 2026, and Polymarket's notice says to stop using it in both new and existing integrations. Go for polymarket-client (for Python) or @polymarket/client (for TypeScript).

How do I get a Polymarket API key?

L1-sign the messages using your wallet’s private key and call POST /auth/api-key on CLOB, or derive the necessary credentials by invoking GET /auth/derive-api-key. SDKs take care of all of these automatically when you create a secure client from your private key.

Can I use the Polymarket API from the United States?

As per documentation, the US is marked “close only” in both websites and APIs, hence no further position openings will be available in this regard through this method. Polymarket links to separate documentation for its US offering.

What do I need to run a Polymarket bot 24/7?

A persistent server, static IP, process management and proper key management. The step-by-step procedure on Polymarket bot setup guide covers the server side, and the sizing guideline is covered on where to host a Polymarket trading bot. A modest OrbitServers VPS from $39.99/mo is all that's required for a single-market loop.