DEV Community: Bo$onaX

Polymarket Arbitrage Bot: Production Architecture

Bo$onaX — Thu, 27 Aug 2026 14:31:52 +0000

Build a Polymarket arbitrage bot with real-time order books, fee-aware execution, risk controls, and production-ready Python architecture.

Introduction

A useful Polymarket arbitrage bot is not simply a script that checks whether two prices add up to less than $1.

The difficult part is turning a theoretical pricing discrepancy into an executable trade after accounting for fees, spread, available liquidity, partial fills, stale quotes, execution failure, and inventory risk.

Polymarket's current production trading stack uses CLOB V2. The official Python client is py-clob-client-v2, while real-time market data is available through the public WebSocket market channel. ([Polymarket Documentation][1])

This article presents a compact architecture for building an arbitrage engine around those primitives.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
Github: https://github.com/n9xdev/poly-alpha-lab
X: https://x.com/xxniiinxx
Telegram: https://t.me/bosonax

What You'll Learn

How to structure an arbitrage engine
How to consume Polymarket order-book updates
How to calculate fee-aware opportunities
How to separate detection from execution
How to manage two-leg execution risk
How to test and monitor the system

1. The Architecture

A production bot should separate market data, strategy, risk, execution, and observability.

flowchart LR
    WS[Polymarket WebSocket] --> BOOK[Order Book Cache]
    META[Market Metadata] --> BOOK
    BOOK --> DETECT[Arbitrage Detector]
    DETECT --> COST[Fee + Slippage Model]
    COST --> RISK[Risk Engine]
    RISK --> EXEC[Execution Engine]
    EXEC --> CLOB[Polymarket CLOB V2]
    CLOB --> FILLS[Fill Events]
    FILLS --> POS[Position Manager]
    POS --> MON[Metrics + Logs]
    EXEC --> MON

The key design principle is simple: never let the strategy directly control the exchange client.

The strategy produces an opportunity. The risk layer decides whether it is allowed. The execution layer determines how it is actually traded.

2. Real-Time Market Data

Polymarket provides a public WebSocket market channel for order-book snapshots and incremental updates. The documented channel supports book updates, price changes, last-trade events, tick-size changes, and other market lifecycle events. Clients should also send the documented heartbeat. ([Polymarket Documentation][2])

For an arbitrage system, maintain an in-memory book:

from dataclasses import dataclass

@dataclass
class Quote:
    bid: float
    ask: float
    bid_size: float
    ask_size: float

books: dict[str, Quote] = {}

Do not repeatedly poll REST endpoints for every strategy decision when streaming data is available. The detector should react to book events and operate against the latest validated local state.

3. Detecting an Arbitrage Opportunity

For a binary market, a simple conceptual parity check is:

cost = yes_ask + no_ask

If the combined executable cost is below the eventual combined payout, there may be an opportunity.

But yes_ask + no_ask < 1 is not sufficient.

The actual decision should look more like:

net_edge =
    guaranteed_or_expected_value
    - execution_cost
    - taker_fee
    - slippage
    - inventory_risk_buffer

Polymarket currently applies taker fees only to fee-enabled markets, with fees calculated at match time. The market's fee configuration can be queried through the CLOB market information API. Makers are not charged the trading fee, and eligible maker activity can receive rebates. ([Polymarket Documentation][3])

Therefore, hard-coding a universal fee percentage into your arbitrage bot is a mistake.

4. Strategy Layer

Keep the strategy deliberately small:

def find_opportunity(yes, no, min_edge):
    combined = yes.ask + no.ask

    if combined >= 1.0:
        return None

    edge = 1.0 - combined

    if edge < min_edge:
        return None

    return {
        "yes_price": yes.ask,
        "no_price": no.ask,
        "edge": edge,
    }

In production, min_edge should represent the minimum executable edge after all known costs, not an arbitrary percentage.

The detector should also verify:

sufficient size exists at both prices
quotes are fresh
both tokens belong to the intended market
market is still tradable
tick sizes are valid
current fee configuration is known
available capital supports both legs

5. Execution Is the Hard Part

The biggest architectural mistake is treating arbitrage as a detection problem.

It is primarily an execution problem.

Suppose the detector sees:

YES ask = 0.47
NO ask  = 0.51
Combined = 0.98

That does not mean you can buy both at those prices.

The YES order might fill while the NO ask disappears. You now have directional exposure.

A safer execution engine therefore tracks every opportunity as a state machine:

DETECTED
   ↓
VALIDATED
   ↓
LEG_A_SUBMITTED
   ↓
LEG_A_FILLED
   ↓
LEG_B_SUBMITTED
   ↓
COMPLETE

Failure states should include:

EXPIRED
PARTIAL
CANCELLED
UNWOUND
ERROR

The execution layer should never assume that submission equals execution.

6. Python Project Structure

A practical project can remain compact:

polymarket_arb/
├── config.py
├── market_data.py
├── orderbook.py
├── strategy.py
├── fees.py
├── risk.py
├── execution.py
├── positions.py
├── monitoring.py
└── main.py

The official documentation currently recommends the V2 Python client, py-clob-client-v2, for CLOB integrations. Legacy V1 clients are no longer supported against production CLOB V2. ([Polymarket Documentation][1])

Keep credentials outside source code:

import os

API_KEY = os.environ["POLY_API_KEY"]
API_SECRET = os.environ["POLY_API_SECRET"]
API_PASSPHRASE = os.environ["POLY_API_PASSPHRASE"]

Private keys should be handled separately and never logged.

7. Risk Engine

Before submitting either leg, enforce hard limits:

def allowed(size, available_capital, max_position):
    return (
        size > 0
        and size <= available_capital
        and size <= max_position
    )

Production systems should additionally enforce:

maximum market exposure
maximum simultaneous opportunities
maximum one-leg exposure
stale-book timeout
daily loss limit
emergency shutdown
duplicate-order protection

A particularly important control is a one-leg timeout. If the hedge does not fill quickly enough, the bot must have a predefined response rather than waiting indefinitely.

8. Performance Considerations

Latency matters, but optimizing Python syntax before optimizing architecture is usually backwards.

Prioritize:

WebSocket market data
local order-book state
event-driven strategy evaluation
persistent connections
asynchronous execution
minimal network hops
measured order submission latency

Polymarket's documentation currently identifies eu-west-2 as the primary CLOB server region and documents direct co-location availability for eligible users. ([Polymarket Documentation][4])

Measure your actual pipeline:

market event
→ detector
→ validation
→ signing
→ submission
→ acknowledgement
→ fill

Do not claim a latency target without measuring your own infrastructure.

9. Failure Modes

Common failures include:

Stale books: A cached opportunity is no longer executable.

Partial fills: One leg executes while the hedge disappears.

Fee blindness: Gross spread looks profitable while net execution is negative.

Liquidity blindness: The best displayed price exists only for a tiny quantity.

Duplicate execution: Multiple event handlers trigger the same opportunity.

Market lifecycle errors: The market changes state while orders are being prepared.

Credential leakage: API credentials or private keys enter logs, repositories, or telemetry.

The bot should treat every external response as untrusted input and every order as an asynchronous state transition.

10. Testing Strategy

Start with deterministic replay.

Store historical order-book events and feed them into the same detector used in production.

Test:

normal book updates
disappearing liquidity
crossed quotes
partial fills
rejected orders
WebSocket disconnects
duplicate events
stale timestamps
fee changes
market closure

Then run the exact strategy in simulation before enabling live execution.

The goal is not merely to prove that the detector finds arbitrage. It is to prove that the whole state machine behaves correctly when arbitrage disappears halfway through execution.

11. Monitoring

Track at minimum:

opportunities_detected
opportunities_rejected
orders_submitted
orders_filled
partial_fills
unwinds
gross_edge
realized_pnl
fees_paid
slippage
data_age
order_latency

Structured logs should include a unique opportunity ID so that detection, orders, fills, and position changes can be reconstructed later.

Polymarket also provides an authenticated user WebSocket channel for real-time order and trade events, making it useful for synchronizing execution state with actual account activity. ([Polymarket Documentation][5])

12. Practical Example

Consider a hypothetical opportunity:

YES ask:  $0.46
NO ask:   $0.51
Gross cost: $0.97
Gross edge: $0.03

A naive bot immediately buys both.

A production bot asks:

Is the book fresh?
Is enough size available?
Are fees enabled?
What is the effective fee?
What happens if only YES fills?
Can NO still be executed?
What is the maximum acceptable unwind loss?

Only after those checks does the risk engine authorize execution.

That difference is what separates an arbitrage detector from an arbitrage trading system.

13. Advanced Improvements

Once the core engine works, add:

multi-market opportunity ranking
fee-aware dynamic thresholds
execution simulation
inventory-aware sizing
cross-market arbitrage models
persistent event storage
automatic strategy kill switches
latency histograms
replay-based regression tests

You can also separate alpha generation from execution completely, allowing multiple strategies to share one execution and risk framework.

Frequently Asked Questions

Is a Polymarket arbitrage bot risk-free?

No. A theoretical arbitrage can still suffer from partial fills, changing liquidity, execution failure, fees, and operational risk.

Does YES + NO below $1 always mean profit?

No. You must evaluate executable size, fees, slippage, and execution risk.

Should I use REST or WebSocket?

For real-time order-book-driven strategies, WebSocket is the natural primary market-data path. REST remains useful for queries and account operations. ([Polymarket Documentation][2])

Which Python SDK should new integrations use?

Polymarket's current documentation specifies py-clob-client-v2 for the CLOB V2 integration. ([Polymarket Documentation][1])

Can arbitrage be profitable?

It can be theoretically attractive, but profitability is strategy-, market-, liquidity-, fee-, and execution-dependent. No specific return should be assumed.

Conclusion

A serious Polymarket arbitrage bot is not a price-comparison script.

The durable architecture is:

stream → normalize → detect → price costs → validate risk → execute → reconcile → monitor.

Build those boundaries correctly and you can change the arbitrage strategy without rebuilding the entire trading infrastructure.

Trading and arbitrage involve substantial risk. Examples in this article are educational and do not imply profitability.

How to Build a Polymarket Trading Bot in Python
Anchor: build a Polymarket trading bot in Python
Why: foundational implementation.
Polymarket API Explained for Developers
Anchor: Polymarket API architecture
Why: explains the API layer behind the bot.
Build a Real-Time Polymarket Order Book Monitor
Anchor: real-time Polymarket order book monitor
Why: directly supports the market-data layer.
Polymarket CLOB Architecture Explained
Anchor: Polymarket CLOB architecture
Why: explains the execution venue.
Polymarket Trading Bot Risk Management
Anchor: Polymarket bot risk management
Why: expands the risk engine.
Polymarket WebSocket Trading Data
Anchor: Polymarket WebSocket data
Why: supports event-driven architecture.

Useful Resources

Official Polymarket — platform and market interface.
Polymarket Developer Documentation — primary technical reference.
Polymarket CLOB Trading Overview — CLOB architecture, authentication, and SDKs.
CLOB V2 Migration Guide — essential for current integrations.
Polymarket Fees Documentation — current fee mechanics.
Polymarket Market WebSocket Documentation — real-time order-book data.
Polymarket Developers on X — developer announcements.
Polymarket arbitrage bot — Medium example — third-party implementation discussion; useful for comparison, not authoritative.
Polymarket arbitrage bot — YouTube example — practical community demonstration; not an official technical source.

Polymarket Trading Bot Setup: Practical 2026 Guide

Bo$onaX — Wed, 26 Aug 2026 14:12:25 +0000

Learn Polymarket Trading Bot Setup with Python, CLOB V2, authentication, WebSockets, execution, testing, security, and monitoring.

Introduction

A serious Polymarket auto-trading bot is more than a Python script that submits orders. The difficult part is connecting market discovery, real-time order-book data, strategy logic, risk controls, authenticated execution, and monitoring without allowing one component to corrupt the others.

Polymarket's current CLOB architecture uses off-chain matching with on-chain settlement on Polygon. Its official documentation currently recommends the V2 clients, including py-clob-client-v2 for Python.

This walkthrough builds the foundation for a production-oriented Polymarket Trading Bot Setup without pretending that the infrastructure itself creates an edge.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: https://x.com/xxniiinxx
Telegram: https://t.me/bosonax
Github: https://github.com/n9xdev/poly-alpha-lab

What You'll Learn

How to structure a Polymarket trading bot
How CLOB V2 authentication works
How to separate market data from execution
How to use Python safely
How to test before live execution
How to monitor orders, fills, errors, and connectivity

1. Recommended Architecture

A clean bot should separate responsibilities:

flowchart LR
    A[Market Discovery] --> B[Market Data Engine]
    B --> C[Strategy Engine]
    C --> D[Risk Manager]
    D --> E[Execution Engine]
    E --> F[Polymarket CLOB]
    F --> G[Order / Trade Events]
    G --> H[Portfolio State]
    H --> D
    B --> I[Monitoring]
    E --> I
    H --> I

The key design principle is simple: the strategy should decide what it wants to do; the execution layer should decide how to safely submit it.

Polymarket provides public methods for market data, prices, and order books without user credentials, while authenticated methods are required for trading operations.

2. Install the Current Python Client

Do not blindly copy older tutorials using the legacy package. Polymarket's migration documentation says the old py-clob-client package is for the previous CLOB version and recommends the V2 client for production integrations.

python -m venv .venv
source .venv/bin/activate

pip install py-clob-client-v2

Pin the version you validate in production rather than allowing an unattended dependency upgrade to change trading behavior.

3. Configure Secrets

Never hard-code wallet credentials.

export PRIVATE_KEY="your_private_key"
export CLOB_API_KEY="your_api_key"
export CLOB_SECRET="your_secret"
export CLOB_PASSPHRASE="your_passphrase"

For real deployments, use a secrets manager or protected environment configuration rather than committing .env files to Git.

Polymarket's current authentication model has two layers: wallet-based signing for L1 authentication and HMAC-based API credentials for L2 authenticated operations.

4. Initialize the Trading Client

A minimal authenticated client can be structured like this:

import os
from py_clob_client_v2 import ApiCreds, ClobClient

HOST = "https://clob.polymarket.com"

creds = ApiCreds(
    api_key=os.environ["CLOB_API_KEY"],
    api_secret=os.environ["CLOB_SECRET"],
    api_passphrase=os.environ["CLOB_PASSPHRASE"],
)

client = ClobClient(
    host=HOST,
    chain_id=137,
    key=os.environ["PRIVATE_KEY"],
    creds=creds,
)

print("Trading client initialized")

The official V2 Python client documents this L1/L2 model and uses Polygon chain ID 137 for mainnet.

Before using live capital, verify the account configuration, signer type, funder address, and permissions required by your account setup.

5. Build the Market-Data Layer

Do not make your strategy responsible for API requests.

Instead:

class MarketData:
    def __init__(self, client):
        self.client = client

    def order_book(self, token_id: str):
        return self.client.get_order_book(token_id)

For slower workflows, REST is sufficient. For event-driven strategies, use the public Market WebSocket. The official stream provides order-book snapshots and price-change updates, among other market events.

This gives you a much cleaner architecture:

WebSocket → local market state → strategy → risk → execution

rather than:

strategy → repeatedly poll API → make decision → submit order

6. Add a Strategy Interface

Keep strategy logic independent from Polymarket-specific networking.

def generate_signal(book, fair_value: float):
    if not book.asks:
        return None

    best_ask = float(book.asks[0].price)

    if best_ask < fair_value:
        return {
            "side": "BUY",
            "price": best_ask,
            "reason": "model_edge",
        }

    return None

This is deliberately hypothetical. A model's estimated fair value is not guaranteed to predict the outcome correctly.

A real strategy should account for spread, liquidity, fees, slippage, execution probability, position exposure, and model uncertainty before deciding that an apparent edge is tradable.

7. Put Risk Before Execution

The risk layer should be able to reject a valid-looking signal.

Typical controls include:

Maximum position per market
Maximum total exposure
Maximum order size
Maximum daily loss
Maximum number of outstanding orders
Price sanity checks
Market-status checks
Kill switch
Duplicate-order protection

Conceptually:

signal = generate_signal(book, fair_value)

if signal and risk_manager.allows(signal):
    execution.submit(signal)

That one boundary prevents strategy bugs from becoming unrestricted order flow.

8. Execution

Polymarket's current CLOB API supports order types including GTC, FOK, GTD, and FAK. The official order endpoint also returns an order ID and status such as live, matched, or delayed.

The execution layer should therefore record:

signal_id
market
token_id
side
requested_price
requested_size
order_id
status
fill_size
fill_price
timestamp
error

Never treat a successful HTTP response as equivalent to a successful fill.

9. Production Considerations

A production bot needs more than working code.

Connectivity: reconnect WebSockets after disconnects and rebuild local state when necessary.

State: persist open orders and positions so a process restart does not create duplicate exposure.

Retries: retry transient network failures carefully. Never blindly retry an order submission without understanding whether the previous request succeeded.

Clock: synchronize timestamps and log server/client timing consistently.

Dependencies: pin and test SDK versions.

Latency: optimize only after measuring the actual path from market event → decision → order submission. Network placement, serialization, strategy computation, and connection reuse can all matter.

10. Failure Modes

Common mistakes include:

Using outdated SDK examples.
Recreating clients for every order.
Polling when a WebSocket architecture is more appropriate.
Assuming an accepted order means it filled.
Ignoring partial fills.
Losing local state after a restart.
Retrying non-idempotent actions blindly.
Storing private keys in source code.
Trading without position limits.
Assuming historical strategy performance will continue.

The CLOB V2 migration is especially important: Polymarket explicitly states that legacy clients should not be used for current production CLOB V2 integrations.

11. Testing Strategy

Build in stages:

Stage 1 — Read only: discover markets and inspect books.

Stage 2 — Replay: feed recorded market events into the strategy.

Stage 3 — Paper execution: simulate orders, fills, fees, and inventory.

Stage 4 — Small live test: validate authentication and execution with controlled exposure.

Stage 5 — Production: enable full monitoring and risk controls.

The most important test is not “does the bot place an order?” It is:

What happens if the network fails immediately after the order request?

Your system must be able to reconcile its state instead of guessing.

12. Monitoring

At minimum, expose metrics for:

WebSocket connection state
REST request latency
API errors
Orders submitted
Orders rejected
Orders filled
Fill ratio
Open exposure
Realized/unrealized P&L
Strategy decisions
Risk rejections

The authenticated User WebSocket can provide real-time order and trade events, making it useful for keeping execution state synchronized.

13. Practical Example

Suppose your model estimates a hypothetical outcome at 62%, while the executable price is $0.55.

The bot should not simply say:

62% > 55% → BUY

Instead:

Model probability
        ↓
Fair-value estimate
        ↓
Spread + liquidity check
        ↓
Fee/slippage estimate
        ↓
Position-risk check
        ↓
Order-size calculation
        ↓
Submit
        ↓
Verify actual order/fill

That difference separates a trading experiment from a trading system.

14. Advanced Improvements

Once the foundation works, add:

Local order-book reconstruction
Event-driven strategy evaluation
Persistent state
Order reconciliation
Portfolio-level risk
Strategy replay
Structured JSON logging
Prometheus/Grafana metrics
Multiple strategy modules
Market-specific configuration
Automated kill switches

For builders using Polymarket's Builder ecosystem, order attribution can also be attached to orders through the documented builder-code mechanism.

Frequently Asked Questions

Is Python suitable for a Polymarket trading bot?

Yes. Polymarket officially provides Python tooling, including its current CLOB client ecosystem.

Do I need API credentials to read market data?

Public market-data methods do not require user credentials. Trading operations do.

Should I start with live trading?

No. Validate market data, strategy behavior, order handling, and recovery logic before committing meaningful capital.

Does automation guarantee profitability?

No. Infrastructure can improve consistency and execution, but it cannot guarantee a positive trading edge.

Should I use REST or WebSockets?

Use REST where request/response access is appropriate and WebSockets when your strategy benefits from continuous market-event updates. Polymarket documents both interfaces.

Conclusion

A reliable Polymarket Trading Bot Setup is fundamentally an engineering problem.

Start with clean separation between data, strategy, risk, execution, and state. Use the current CLOB tooling, protect credentials, test failure scenarios, and measure execution instead of assuming it.

The bot's first objective should not be making money.

It should be behaving correctly when the market, network, API, strategy, or process does something unexpected.

Risk disclaimer: This article is educational and does not constitute financial advice. Automated prediction-market trading can result in losses. Strategy performance is uncertain, and historical or hypothetical examples do not guarantee future results.

Useful Resources

Polymarket — Official prediction-market platform.
Polymarket Documentation — Primary technical reference for APIs, SDKs, trading, and developer tooling.
Polymarket Trading Quickstart — Official end-to-end order setup.
Polymarket Python CLOB Client V2 — Official Python implementation reference.
Polymarket GitHub Organization — Official developer repositories and SDKs.
Medium: CLOB V2 Execution Deep Dive — Useful third-party explanation of the CLOB V2 execution lifecycle; verify implementation details against official docs.
DEV.to: Low-Latency Polymarket Bot in Python — Practical third-party discussion of WebSockets and execution architecture; not an authoritative source.
YouTube: Polymarket API Tutorial — Practical video walkthrough; use official documentation to validate current API details.
Polymarket Developers on X — Useful for following developer announcements; verify important technical changes against the documentation.

Polymarket Trading Bot Position Sizing: A Practical Guide

Bo$onaX — Tue, 25 Aug 2026 09:00:53 +0000

Polymarket Trading Bot Position Sizing

A profitable signal is not enough. A Polymarket trading bot also needs to decide how much capital to risk.

Position sizing is one of the most important—and most underestimated—parts of Polymarket algorithmic trading. A bot with a good signal can still perform badly if it repeatedly overcommits capital, ignores liquidity, or treats correlated markets as independent opportunities.

This guide shows how to build a practical Python position-sizing engine for a Polymarket bot using estimated probability, market price, fractional Kelly sizing, liquidity caps, and portfolio-level risk controls.

Polymarket provides developer resources for programmatic market interaction, including market data and trading infrastructure. Builders should verify implementation details against the current official documentation before connecting production capital.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: https://x.com/xxniiinxx
Telegram: https://t.me/bosonax
Youtube: https://youtu.be/fbtzTnPiRW0?si=alLrul9Rw75m2fVf

What You'll Learn

How to convert a probability model into a position size
Why market price alone should not determine size
How to calculate binary-contract Kelly sizing
Why fractional Kelly is usually safer for uncertain models
How to cap positions using portfolio and liquidity constraints
How to implement the logic in Python
How to monitor and test a production sizing engine

The Core Position-Sizing Problem

Suppose your model estimates:

Probability of YES: 62%
Market price:        55¢

Your estimated edge is:

edge = 0.62 - 0.55 = 0.07

The obvious conclusion is to buy YES. But how much?

A fixed strategy might buy $100 every time. That ignores an important distinction:

62% model vs 55¢ market
52% model vs 45¢ market

Both have a 7 percentage-point difference, but the payout structure and model confidence may differ.

A robust Polymarket trading strategy should separate:

Signal generation
Probability estimation
Position sizing
Execution
Portfolio risk management

flowchart LR
    A[Market Data] --> B[Probability Model]
    B --> C[Estimated Edge]
    C --> D[Position Sizing Engine]
    D --> E[Risk & Liquidity Caps]
    E --> F[Polymarket Order Book]
    F --> G[Execution]
    G --> H[Portfolio State]
    H --> D

The sizing engine should never assume that a signal is automatically worth the maximum possible trade.

Step 1: Calculate Edge

For a YES contract:

edge = estimated_probability - market_price

Example:

estimated_probability = 0.62
market_price = 0.55

edge = estimated_probability - market_price

print(edge)  # 0.07

This is only the beginning. Before sizing the trade, your bot should account for execution costs, spread, potential slippage, and model uncertainty.

A practical approximation is:

net_edge = model_probability - entry_price - cost_buffer

The cost_buffer is strategy-specific. Do not hard-code a universal Polymarket fee or slippage value without checking the current market and official documentation.

Step 2: Use Kelly Criterion

For a binary position, a simplified Kelly calculation can be expressed as:

f = (p × b - q) / b

Where:

p = estimated probability of winning
q = 1 - p
b = potential profit relative to the amount risked
f = fraction of bankroll to allocate

For a YES contract purchased at price c, the theoretical profit multiple at resolution is approximately:

b = (1 - c) / c

Python implementation:

def kelly_fraction(probability: float, price: float) -> float:
    if not 0 < probability < 1:
        raise ValueError("Probability must be between 0 and 1")

    if not 0 < price < 1:
        raise ValueError("Price must be between 0 and 1")

    b = (1 - price) / price
    q = 1 - probability

    fraction = (probability * b - q) / b

    return max(0.0, fraction)

Example

p = 0.62
price = 0.55

kelly = kelly_fraction(p, price)

print(f"Kelly fraction: {kelly:.4f}")

The output is a theoretical fraction of bankroll.

But full Kelly can be dangerous when your probability estimate is imperfect—which, in real trading, it almost always is.

Step 3: Use Fractional Kelly

A more conservative approach is:

fractional_kelly = kelly * 0.25

For example:

KELLY_MULTIPLIER = 0.25

def fractional_kelly_size(
    bankroll: float,
    probability: float,
    price: float,
    multiplier: float = KELLY_MULTIPLIER,
) -> float:
    fraction = kelly_fraction(probability, price)
    fraction *= multiplier

    return bankroll * fraction

The exact multiplier is a strategy parameter, not a universal rule. A smaller multiplier may be appropriate when:

the probability model is poorly calibrated
historical data is limited
markets are highly correlated
execution costs are uncertain
liquidity is thin

Step 4: Add Hard Risk Caps

Kelly alone should not control your Polymarket bot.

A production sizing engine should apply multiple limits.

from dataclasses import dataclass


@dataclass
class RiskLimits:
    max_position_pct: float = 0.05
    max_portfolio_exposure_pct: float = 0.40
    max_market_liquidity_pct: float = 0.10


def calculate_position_size(
    bankroll: float,
    probability: float,
    price: float,
    available_liquidity: float,
    limits: RiskLimits,
    kelly_multiplier: float = 0.25,
) -> float:

    raw_size = fractional_kelly_size(
        bankroll=bankroll,
        probability=probability,
        price=price,
        multiplier=kelly_multiplier,
    )

    position_cap = bankroll * limits.max_position_pct

    liquidity_cap = available_liquidity * limits.max_market_liquidity_pct

    final_size = min(
        raw_size,
        position_cap,
        liquidity_cap,
    )

    return max(0.0, final_size)

The result is not simply:

model edge → maximum capital

Instead:

model edge
    ↓
Kelly estimate
    ↓
fractional Kelly
    ↓
portfolio cap
    ↓
liquidity cap
    ↓
final position size

Position Sizing and the Polymarket Order Book

Your model may recommend a $2,000 position, but the visible Polymarket order book may not support a $2,000 trade at your expected price.

That creates execution risk.

Before sending an order, a production Polymarket API Python client should estimate:

available size at target prices
average fill price
spread
potential slippage
whether the trade itself moves the market

A simple position-size formula can therefore become:

final_size =
min(
    model_size,
    portfolio_cap,
    liquidity_cap,
    slippage_cap
)

For active strategies, live market data can be monitored through the relevant Polymarket data infrastructure and websocket interfaces described in the current developer documentation.

Production Architecture

A clean Polymarket trading bot Python architecture should keep sizing independent from execution.

strategy/
    signal.py
    probability_model.py

risk/
    position_sizing.py
    exposure.py
    correlation.py

execution/
    orderbook.py
    orders.py
    fills.py

monitoring/
    metrics.py
    alerts.py

This separation is important because your signal model may change while your risk engine should remain conservative.

Retry Carefully

Do not blindly retry an order because a request failed. First determine whether the order may have been accepted.

Use exponential backoff for safe retryable network operations:

import time
import logging

logger = logging.getLogger(__name__)


def retry(operation, attempts=3):
    for attempt in range(attempts):
        try:
            return operation()
        except Exception as exc:
            logger.warning(
                "Operation failed on attempt %d: %s",
                attempt + 1,
                exc,
            )

            if attempt == attempts - 1:
                raise

            time.sleep(2 ** attempt)

Order submission requires idempotency and order-state reconciliation. Network failure does not necessarily mean that an order was rejected.

Common Failure Modes

1. Full Kelly with an overconfident model

A small probability-estimation error can dramatically affect recommended size.

Use conservative sizing until calibration has been validated.

2. Ignoring correlated exposure

Five positions may look diversified but actually depend on the same event or price movement.

Portfolio-level exposure matters more than the number of open trades.

3. Sizing from the last traded price

Your actual fill may occur at a worse price.

Size from executable order-book liquidity, not an outdated snapshot.

4. Treating paper trading as live trading

Paper systems often fail to model partial fills, queue position, slippage, and adverse selection accurately.

5. No maximum loss controls

Every automated system should have hard limits independent of the strategy model.

Testing and Monitoring

Test the sizing engine independently from the Polymarket market making bot or execution layer.

At minimum:

def test_no_positive_edge_returns_zero():
    size = fractional_kelly_size(
        bankroll=10_000,
        probability=0.50,
        price=0.55,
    )

    assert size == 0

Monitor:

bankroll
open exposure
gross and net exposure
largest position
position size as percentage of equity
estimated versus realized fill price
model probability versus market probability
rejected orders
partial fills
daily drawdown

The current Polymarket exchange stack has undergone recent upgrades, including changes described by Polymarket to exchange contracts and order-book behavior, so production bots should be maintained against the latest official migration and developer documentation rather than relying on old SDK assumptions.

Practical Example

Assume:

Bankroll:                 $10,000
Model probability:        0.62
YES entry price:          0.55
Fractional Kelly:         25%
Maximum position:         5% bankroll

Your sizing engine calculates a theoretical Kelly amount, reduces it using the fractional Kelly multiplier, and then checks the hard position limit.

Even if the model recommends more, the final position cannot exceed:

$10,000 × 5% = $500

If order-book liquidity or expected slippage requires an even smaller amount, the bot should reduce the position further.

That is the central principle:

The best position size is not the largest mathematically possible position. It is the largest position your strategy, liquidity, execution system, and portfolio risk limits can realistically support.

Advanced Improvements

More advanced Polymarket automated trading systems can add:

probability calibration curves
confidence-weighted Kelly sizing
correlation-aware portfolio sizing
dynamic exposure limits
volatility-aware capital allocation
strategy-level capital budgets
real-time fill-quality feedback
model-specific risk multipliers

A useful next step is to make the sizing multiplier dynamic:

final_kelly_multiplier =
base_multiplier
× model_confidence
× liquidity_quality
× portfolio_risk_factor

This allows a Polymarket arbitrage bot or directional strategy to reduce capital automatically when execution quality deteriorates.

Frequently Asked Questions

How much should a Polymarket trading bot risk per trade?

There is no universal number. Use estimated edge, model confidence, available liquidity, portfolio exposure, and a hard maximum position cap.

Is Kelly Criterion good for a Polymarket bot?

It can be useful, but full Kelly assumes accurate probabilities. Fractional Kelly and hard risk caps are generally more robust for uncertain real-world models.

Should a Polymarket arbitrage bot use position sizing?

Yes. Arbitrage still has execution risk, partial-fill risk, capital constraints, and settlement or inventory considerations.

Should I size trades from the best bid or ask?

Use realistic executable prices and enough order-book depth to estimate the actual average fill price.

Can a Polymarket websocket improve position sizing?

Yes. Real-time market data can help update liquidity and pricing inputs, but the final implementation should follow the current official Polymarket developer documentation.

Useful Resources

Polymarket Official Website — Market access and platform information.
Official Polymarket Documentation — Primary technical authority for API and trading implementation.
— Official starting point for developers looking for programmatic resources.
— Useful for developers building applications and infrastructure around Polymarket.
Polymarket Official X Account — Official announcements and platform updates.

Third-party Medium, DEV.to, and YouTube resources were not included here because a current, directly relevant resource could not be verified confidently enough for this technical article.

Conclusion

Position sizing is the bridge between a Polymarket trading strategy and actual capital risk.

A production system should not simply ask:

“Is this trade profitable?”

It should ask:

“How much should we risk after accounting for edge, model uncertainty, liquidity, execution quality, and existing exposure?”

For most systems, a strong starting architecture is:

Probability model
→ Net edge
→ Fractional Kelly
→ Position cap
→ Liquidity cap
→ Portfolio risk check
→ Order execution
→ Fill reconciliation

That framework works for directional strategies, Polymarket arbitrage, market making, and more complex algorithmic systems.

Educational and trading-risk disclaimer: This article is for educational and software-development purposes only. Prediction-market trading involves substantial risk. No position-sizing formula guarantees profit or prevents losses. Test thoroughly and independently verify current platform behavior before deploying capital.

How Polymarket CLOB Works
Anchor text: “Polymarket CLOB architecture”
Why: Helps readers understand how orders interact with the exchange.
Polymarket Order Book Explained
Anchor text: “Polymarket order book liquidity”
Why: Essential for liquidity-aware position sizing.
How to Handle Slippage in a Polymarket Bot
Anchor text: “slippage-aware position sizing”
Why: Connects sizing decisions with realistic execution costs.
How to Build a Polymarket Trading Bot
Anchor text: “build a Polymarket trading bot”
Why: Broad pillar article for implementation architecture.
Polymarket WebSocket Guide
Anchor text: “real-time Polymarket market data”
Why: Supports live price and liquidity updates.
Polymarket Arbitrage Bot Development
Anchor text: “Polymarket arbitrage bot”
Why: Explains sizing in multi-leg strategies.
Polymarket TWAP Trading Bot
Anchor text: “Polymarket TWAP strategy”
Why: Connects position sizing with time-sensitive market strategies.

Build a Real-Time Polymarket Order Book Monitor with Python

Bo$onaX — Sat, 22 Aug 2026 12:35:31 +0000

Build a Real-Time Polymarket Order Book Monitor

A trading bot should not make decisions from stale snapshots. If you want to understand liquidity, spread, depth, or changes in market structure, you need a continuously updated view of the Polymarket order book.

This tutorial builds a lightweight Polymarket order book Python monitor using the public CLOB Market WebSocket. Polymarket documents this channel as a real-time feed for order-book, price, and market lifecycle updates.

The implementation intentionally focuses on market data—not order execution—so it can be used as the foundation for research, dashboards, alerts, or an automated trading system.

What You'll Learn

How Polymarket token IDs relate to order-book subscriptions
How to connect to the CLOB Market WebSocket
How to process book and price_change events
How to calculate best bid, best ask, and spread
How to handle reconnects and heartbeats
How to detect stale market data
How to turn raw WebSocket events into trading signals

Architecture

flowchart LR
    A[Polymarket CLOB] --> B[Market WebSocket]
    B --> C[Python Async Client]
    C --> D[Order Book State]
    D --> E[Spread / Depth Metrics]
    D --> F[Trading Signal Engine]
    D --> G[Logging / Monitoring]

The important design decision is separating transport from state. The WebSocket delivers events; your application maintains the current book.

1. Install the Dependencies

For this monitor, authentication is not required because the Market WebSocket is public.

pip install websockets

You need a Polymarket asset ID/token ID for the outcome you want to monitor. The Market Channel subscribes using assets_ids.

For example:

TOKEN_ID = "YOUR_TOKEN_ID"

Do not hard-code credentials into a market-data monitor. In this example, there are no credentials at all.

2. Connect to the Market WebSocket

The documented Market Channel endpoint is:

wss://ws-subscriptions-clob.polymarket.com/ws/market

The subscription message contains type: "market" and one or more asset IDs.

A minimal monitor looks like this:

import asyncio
import json
import logging
import websockets

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
TOKEN_ID = "YOUR_TOKEN_ID"

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s"
)


async def monitor():
    async with websockets.connect(
        WS_URL,
        ping_interval=None
    ) as ws:

        await ws.send(json.dumps({
            "type": "market",
            "assets_ids": [TOKEN_ID]
        }))

        logging.info("Subscribed to %s", TOKEN_ID)

        async for raw_message in ws:
            if raw_message == "PONG":
                continue

            message = json.loads(raw_message)
            await handle_message(message)


async def handle_message(message):
    event_type = message.get("event_type")

    if event_type == "book":
        print_book(message)

    elif event_type == "price_change":
        logging.info(
            "Price update: %s",
            message.get("price_changes", [])
        )

    elif event_type == "last_trade_price":
        logging.info(
            "Trade: %s @ %s",
            message.get("size"),
            message.get("price")
        )


def print_book(book):
    bids = book.get("bids", [])
    asks = book.get("asks", [])

    if not bids or not asks:
        return

    best_bid = max(float(x["price"]) for x in bids)
    best_ask = min(float(x["price"]) for x in asks)

    spread = best_ask - best_bid

    print(
        f"Bid={best_bid:.4f} "
        f"Ask={best_ask:.4f} "
        f"Spread={spread:.4f}"
    )


asyncio.run(monitor())

The initial book event contains aggregated bid and ask levels. Polymarket also documents price_change as an order-book price-level delta event.

3. Don't Ignore the Heartbeat

A production client should implement the documented application-level heartbeat. Polymarket's current documentation specifies that clients send PING every 10 seconds and receive PONG.

Add a dedicated heartbeat task:

async def heartbeat(ws):
    while True:
        await asyncio.sleep(10)
        await ws.send("PING")

Then start it after connecting:

heartbeat_task = asyncio.create_task(heartbeat(ws))

try:
    async for raw_message in ws:
        ...
finally:
    heartbeat_task.cancel()

This is preferable to relying blindly on the WebSocket library's protocol-level ping mechanism because the Polymarket feed specifies its own application-level heartbeat.

4. Maintain Book State

For research, repeatedly printing snapshots is not enough.

Store price levels in dictionaries:

book = {
    "bids": {},
    "asks": {}
}

For every snapshot:

for level in message["bids"]:
    book["bids"][level["price"]] = float(level["size"])

for level in message["asks"]:
    book["asks"][level["price"]] = float(level["size"])

A real implementation should also process every documented price-level change according to its side, price, and size fields.

The key principle is simple:

The WebSocket is the event stream. Your local order book is the state machine.

5. Useful Real-Time Metrics

Once the book is normalized, you can calculate:

Best bid

best_bid = max(book["bids"])

Best ask

best_ask = min(book["asks"])

Spread

spread = best_ask - best_bid

Midpoint

mid = (best_bid + best_ask) / 2

Top-of-book imbalance

A simple research metric is:

imbalance = (
    bid_size - ask_size
) / (
    bid_size + ask_size
)

These metrics do not constitute a profitable strategy by themselves. They are observations that can become inputs to a broader execution or pricing model.

Production Considerations

A production monitor should add:

Automatic reconnection
Exponential backoff
Subscription restoration
Heartbeat monitoring
Message validation
Sequence/state consistency checks
Stale-data detection
Structured logging
Persistent event storage
Graceful shutdown

Do not assume that an open TCP/WebSocket connection means your market data is healthy.

Polymarket's status history has documented WebSocket incidents and CLOB maintenance events, so operational monitoring matters even when your application code is correct.

Failure Modes

Connection succeeds but no data arrives

Check the asset ID, subscription payload, market state, and application heartbeat.

Your book becomes inconsistent

Do not treat every message as an independent snapshot. Distinguish full book events from incremental price_change events.

Your monitor silently becomes stale

Track the timestamp of the most recent valid market event and raise an alert when it exceeds your application's freshness threshold.

The code breaks after a Polymarket API change

Pin and regularly review dependencies, then check the official documentation and changelog before upgrading production infrastructure. Polymarket's changelog records significant CLOB/API changes, including the 2026 CLOB V2 production migration.

Performance Considerations

Do not perform expensive calculations inside the WebSocket receive loop.

A better architecture is:

WebSocket
   ↓
Parser
   ↓
Book State
   ↓
Event Queue
   ↓
Analytics Workers
   ↓
Strategy

The receive loop should process messages quickly and hand heavier work to another component.

For high-frequency research, avoid unnecessary JSON transformations, excessive logging, database writes on every event, and repeated full-book sorting.

Security

A public order-book monitor does not need private keys or trading credentials.

Keep the market-data process separate from execution credentials whenever possible. If you later connect the monitor to order placement, store secrets in environment variables or a proper secret-management system.

Never put private keys, API secrets, or seed phrases inside source code.

Testing Strategy

Use recorded WebSocket messages to build deterministic tests.

Test at least:

Empty books
One-sided books
Multiple price levels
Price-level removal
Price changes
Malformed JSON
Unknown event types
Reconnection
Heartbeat failure
Stale timestamps
Tick-size changes

A particularly useful test is replaying a historical event sequence and verifying that your reconstructed book matches the expected final state.

Monitoring and Observability

Expose metrics such as:

websocket_connected
last_message_timestamp
messages_received
book_events
price_change_events
reconnect_count
parse_errors
book_age_seconds

For trading infrastructure, data freshness is itself a metric.

A strategy using a technically correct but stale order book can make decisions based on a market that no longer exists.

Advanced Improvements

Once the basic monitor works, extend it into a research-grade market-data engine:

Subscribe to multiple tokens
Maintain separate books per asset
Store normalized events in Parquet
Calculate depth at multiple price levels
Track spread changes
Detect liquidity withdrawals
Build order-book imbalance features
Compare Polymarket prices with external models
Feed normalized data into a signal engine
Replay recorded books for backtesting

This creates a clean separation between market-data collection, feature generation, strategy logic, and execution.

Frequently Asked Questions

Is the Polymarket order book available through WebSocket?

Yes. The public Market Channel provides real-time order-book and market updates.

Do I need API credentials to monitor an order book?

No. The Market Channel is public. The authenticated User Channel is separate and is used for user-specific order and trade updates.

What is an asset ID?

It identifies a specific outcome token used by the CLOB Market WebSocket subscription.

Should I poll the order book instead?

Polling can be useful for snapshots and recovery, but a streaming architecture is more appropriate when you need continuous market-data updates.

Does an order-book monitor guarantee trading profits?

No. Market-data quality is only one component of a trading system. Slippage, fees, liquidity, latency, adverse selection, execution risk, and model error can all affect results.

Conclusion

Building a Polymarket order book Python monitor is less about printing bids and asks and more about building a reliable market-data pipeline.

Start with the public CLOB Market WebSocket, maintain local book state, process snapshots and price changes correctly, implement heartbeats and reconnection, and measure data freshness.

Once that foundation is reliable, you can build analytics and trading logic on top of it without coupling strategy code to the raw WebSocket transport.

Educational disclaimer: This article is for software-development and market-data research purposes. Order-book signals do not guarantee profitable trading, and automated trading involves financial and technical risks.

How to Build a Polymarket Trading Bot in Python
Anchor: Polymarket trading bot in Python
Connects market-data infrastructure to the complete bot architecture.
Polymarket API Explained for Developers
Anchor: Polymarket API
Provides broader API architecture and endpoint context.
How Polymarket CLOB Works
Anchor: Polymarket CLOB
Explains the central-limit order-book model behind the monitor.
Polymarket WebSocket API Guide
Anchor: Polymarket WebSocket API
Natural follow-up for streaming architecture.
How to Calculate Polymarket Market Probability
Anchor: Polymarket probability calculation
Connects prices and order-book observations to quantitative analysis.
Building a Polymarket Market-Making Bot
Anchor: Polymarket market-making bot
Extends the data layer toward automated quoting.

Useful Resources

Polymarket — Official prediction-market platform.
Polymarket Documentation — Primary technical reference.
Market Channel documentation — Current CLOB Market WebSocket message and subscription reference.
Polymarket Changelog — Useful for tracking API and CLOB changes.
Polymarket Status — Operational status and incident history.

I have intentionally omitted Medium, DEV.to, and YouTube resources because I could not verify a specific current resource that is sufficiently relevant to this exact implementation without fabricating a URL.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: https://x.com/xxniiinxx
Telegram: https://t.me/bosonax

Polymarket Market Scanner in Python: Build One

Bo$onaX — Fri, 21 Aug 2026 16:52:39 +0000

Build a Polymarket Market Scanner in Python

A trading bot should not start by placing orders. It should first answer a simpler question:

Which Polymarket markets are worth looking at right now?

That is the job of a market scanner.

A useful Polymarket market scanner continuously turns a large universe of prediction markets into a smaller, structured candidate set based on conditions such as market status, liquidity, volume, expiration, price, category, and order-book availability.

Polymarket currently exposes public market data without authentication, including market discovery through the Gamma API and order-book/pricing data through the CLOB API. ([Polymarket Documentation][1])

In this tutorial, we will build a read-only Python scanner that discovers active markets, applies quantitative filters, and produces candidates that a later strategy or execution engine can evaluate.

Trading-risk disclaimer: A scanner identifies markets matching predefined conditions. It does not establish that a trade is profitable. Spread, liquidity, fees, slippage, latency, adverse selection, model error, and resolution risk still matter.

What You'll Learn

By the end, you will understand:

How Polymarket market discovery works
How to use the current keyset market endpoint
How to paginate through markets safely
How to filter markets quantitatively
How to separate discovery from price/order-book analysis
How to design a scanner that can evolve into a trading system
What changes are required for production deployment

1. Market Scanner Architecture

The important design decision is to separate market discovery from market evaluation.

A scanner should not download every order book every time it scans the entire market universe. That creates unnecessary network traffic and makes scaling harder.

A better architecture is:

flowchart LR
    A[Gamma Market Discovery] --> B[Market Universe]
    B --> C[Basic Filters]
    C --> D[Candidate Markets]
    D --> E[CLOB Price / Order Book]
    E --> F[Quantitative Filters]
    F --> G[Ranked Opportunities]
    G --> H[Strategy Engine]
    H --> I[Execution Engine]

The Gamma API provides market discovery and metadata. The CLOB API provides market prices and order-book information. Polymarket documents these as separate parts of its market-data architecture. ([Polymarket Documentation][1])

That separation is useful because metadata changes much more slowly than order-book state.

2. Which API Should the Scanner Use?

For broad market discovery, the current documentation provides a keyset-paginated endpoint:

GET https://gamma-api.polymarket.com/markets/keyset

It supports filters such as closed, liquidity ranges, volume ranges, date ranges, tags, and ordering. The endpoint uses an opaque next_cursor returned by one request as after_cursor for the next request. Its maximum limit is currently 100. ([Polymarket Documentation][2])

This is preferable for a large scanner to repeatedly requesting arbitrary offsets.

The CLOB API is then appropriate when the scanner needs order-book information such as bids, asks, midpoint, or prices. ([Polymarket Documentation][1])

For a read-only scanner, authentication is not required for public market data. ([Polymarket Documentation][1])

3. Project Setup

For a simple scanner, Python's standard HTTP tooling is enough.

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

pip install httpx

A minimal project can look like:

polymarket-scanner/
├── scanner.py
├── requirements.txt
└── README.md

requirements.txt:

httpx

No private key or trading credential is necessary for this version.

4. Fetch Markets With Keyset Pagination

The first component is a market-discovery client.

from __future__ import annotations

import time
import httpx

GAMMA_URL = "https://gamma-api.polymarket.com/markets/keyset"


def fetch_markets(
    client: httpx.Client,
    limit: int = 100,
    max_pages: int = 5,
) -> list[dict]:
    markets: list[dict] = []
    cursor: str | None = None

    for _ in range(max_pages):
        params = {
            "limit": limit,
            "closed": "false",
            "ascending": "false",
        }

        if cursor:
            params["after_cursor"] = cursor

        response = client.get(GAMMA_URL, params=params)
        response.raise_for_status()

        payload = response.json()

        page = payload.get("markets", [])
        markets.extend(page)

        cursor = payload.get("next_cursor")

        if not cursor or not page:
            break

        time.sleep(0.05)

    return markets

The key detail is that the cursor is treated as opaque data. Do not try to construct or interpret it yourself.

The official documentation specifically describes next_cursor → after_cursor pagination and rejects the offset parameter for this endpoint. ([Polymarket Documentation][2])

5. Add Basic Market Filters

The raw market universe is usually much larger than the universe a strategy actually needs.

For example, a scanner might require:

market is active
market is not closed
sufficient liquidity
sufficient volume
a known question
an acceptable expiration horizon

def filter_markets(
    markets: list[dict],
    min_liquidity: float = 10_000,
    min_volume: float = 25_000,
) -> list[dict]:

    candidates = []

    for market in markets:
        if market.get("closed"):
            continue

        if not market.get("active"):
            continue

        liquidity = float(market.get("liquidity") or 0)
        volume = float(market.get("volume") or 0)

        if liquidity < min_liquidity:
            continue

        if volume < min_volume:
            continue

        candidates.append(market)

    return candidates

The numbers above are example configuration values, not claims about optimal thresholds.

A production scanner should make them configurable rather than hard-coding assumptions.

The market API exposes fields including liquidity, volume, question, outcome information, dates, and other metadata. ([Polymarket Documentation][3])

6. Parsing Outcome Prices

Polymarket's market data represents outcomes and outcome prices as corresponding arrays. For binary markets, the first outcome and first price can commonly represent the first outcome in that market's outcome ordering. ([Polymarket Documentation][1])

Because API representations can contain serialized JSON strings, parse them defensively:

import json


def parse_outcomes(market: dict) -> list[tuple[str, float]]:
    outcomes_raw = market.get("outcomes", "[]")
    prices_raw = market.get("outcomePrices", "[]")

    try:
        outcomes = json.loads(outcomes_raw)
        prices = json.loads(prices_raw)
    except (TypeError, json.JSONDecodeError):
        return []

    result = []

    for outcome, price in zip(outcomes, prices):
        try:
            result.append((outcome, float(price)))
        except (TypeError, ValueError):
            continue

    return result

The scanner can now reason about price levels without making assumptions about the underlying market question.

7. A Complete Basic Scanner

Putting the components together:

from __future__ import annotations

import json
import logging
import httpx

GAMMA_URL = "https://gamma-api.polymarket.com/markets/keyset"

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
)


def parse_outcomes(market: dict) -> list[tuple[str, float]]:
    try:
        outcomes = json.loads(market.get("outcomes", "[]"))
        prices = json.loads(market.get("outcomePrices", "[]"))
    except (TypeError, json.JSONDecodeError):
        return []

    result = []

    for outcome, price in zip(outcomes, prices):
        try:
            result.append((str(outcome), float(price)))
        except (TypeError, ValueError):
            pass

    return result


def scan_markets(
    min_liquidity: float = 10_000,
    min_volume: float = 25_000,
    max_pages: int = 5,
) -> list[dict]:

    candidates = []

    with httpx.Client(timeout=10.0) as client:
        cursor = None

        for _ in range(max_pages):
            params = {
                "limit": 100,
                "closed": "false",
                "ascending": "false",
            }

            if cursor:
                params["after_cursor"] = cursor

            try:
                response = client.get(GAMMA_URL, params=params)
                response.raise_for_status()
                payload = response.json()
            except httpx.HTTPError as exc:
                logging.error("Market request failed: %s", exc)
                break

            for market in payload.get("markets", []):
                if not market.get("active"):
                    continue

                liquidity = float(market.get("liquidity") or 0)
                volume = float(market.get("volume") or 0)

                if liquidity < min_liquidity:
                    continue

                if volume < min_volume:
                    continue

                candidates.append({
                    "id": market.get("id"),
                    "question": market.get("question"),
                    "slug": market.get("slug"),
                    "liquidity": liquidity,
                    "volume": volume,
                    "outcomes": parse_outcomes(market),
                })

            cursor = payload.get("next_cursor")

            if not cursor:
                break

    return candidates


if __name__ == "__main__":
    for market in scan_markets():
        print(
            f"{market['liquidity']:>12,.0f} "
            f"{market['volume']:>12,.0f} "
            f"{market['question']}"
        )

This is deliberately read-only.

That is a useful engineering boundary: discovery should not have permission to trade.

8. Scanner → Order Book Evaluation

Metadata filtering is only the first stage.

Suppose 5,000 markets exist but only 100 satisfy your basic liquidity and volume criteria. There is little reason to request detailed order books for all 5,000.

Instead:

5,000 markets
     ↓
metadata filters
     ↓
100 candidates
     ↓
order-book queries
     ↓
20 liquid candidates
     ↓
strategy/model evaluation

The CLOB provides endpoints for individual and batch order-book and price queries. ([Polymarket Documentation][1])

For a latency-sensitive scanner, the WebSocket market channel is another option. The documented market channel provides real-time order-book, price, and market-lifecycle updates. ([Polymarket Documentation][4])

This creates two different scanner modes:

Batch scanner

Useful for research, scheduled screening, dashboards, and periodic candidate discovery.

Streaming scanner

Useful when the system must react to changing market state rather than repeatedly polling.

9. Ranking Candidates

Filtering answers:

Does this market qualify?

Ranking answers:

Which qualifying markets deserve attention first?

A simple ranking function could combine normalized liquidity and volume:

def score_market(market: dict) -> float:
    liquidity = market["liquidity"]
    volume = market["volume"]

    return (liquidity ** 0.5) * (volume ** 0.5)

This is not a trading signal. It is merely a prioritization mechanism.

A more sophisticated scanner could rank by:

bid/ask spread
displayed depth
recent volume
time to expiration
price distance from a model estimate
volatility
market category
event-level concentration
historical price movement

The crucial principle is to keep market selection separate from trade prediction.

A scanner should tell the strategy engine where to look, not secretly become the strategy itself.

10. Production Considerations

Rate limits

Polymarket documents rate limits across the Gamma, Data, and CLOB APIs. Current documentation lists Gamma /markets at 300 requests per 10 seconds and CLOB /book at 1,500 requests per 10 seconds, among other limits. ([Polymarket Documentation][5])

Do not build a scanner around the assumption that unlimited polling is acceptable.

Use:

bounded concurrency
batching where supported
caching
exponential backoff
incremental updates
WebSockets for continuously changing data

Rate-limit values can change, so production systems should treat the official rate-limit documentation as the source of truth.

Keyset pagination

Use the current keyset endpoint for large market scans rather than designing new code around offset pagination. Polymarket announced the keyset endpoints in April 2026 and subsequently documented a maximum limit of 100. ([Polymarket Documentation][6])

SDK selection

Polymarket now maintains a unified Python SDK, polymarket-client, which is currently described by the project as beta. ([GitHub][7])

The older py-clob-client repository is archived, while Polymarket's current Python SDK repository recommends the unified SDK for new projects. ([GitHub][8])

For a small scanner, direct documented HTTP calls can be perfectly reasonable. For a larger application, evaluate the current official SDK and its stability before committing your architecture to a particular interface.

11. Failure Modes and Common Mistakes

Scanning every order book

This wastes requests and increases latency.

Better: filter the universe first.

Using stale market assumptions

Market APIs evolve. Fields, endpoints, SDKs, and pagination behavior can change.

Better: verify production assumptions against the current documentation and changelog.

Treating liquidity as executable liquidity

A liquidity number does not tell you exactly how much size you can execute at your desired price.

Better: inspect the actual order book before making execution decisions.

Assuming the displayed probability is your edge

A market price is not automatically a trading opportunity.

Better: compare market state against an independently constructed model and account for execution costs.

Mixing discovery and execution

A scanner that can also immediately submit trades creates unnecessary operational risk.

Better: keep discovery, signal generation, risk management, and execution as separate components.

12. Performance Considerations

The first optimization should usually be reducing unnecessary requests, not micro-optimizing Python.

A sensible progression is:

Fetch market metadata.
Filter locally.
Batch price/order-book requests when appropriate.
Cache relatively static metadata.
Move continuously changing data to WebSockets.
Parallelize only within documented limits.
Measure request latency and processing time.

For example, maintain two datasets:

market_metadata
    id
    question
    category
    liquidity
    volume
    end_date

market_state
    best_bid
    best_ask
    midpoint
    depth
    timestamp

This prevents the scanner from repeatedly rebuilding static information.

13. Security

A market scanner does not need a private key.

Keep it that way.

If the scanner eventually connects to a trading engine:

keep private keys outside source code
use environment variables or a secret manager
restrict credentials to the minimum required permissions
separate research and production environments
never log secrets
never commit .env files
isolate order execution from market discovery

Polymarket's authenticated trading workflows require credentials, but public market discovery does not. ([Polymarket Documentation][1])

A read-only scanner is therefore an excellent first component to build and test before introducing trading credentials.

14. Testing Strategy

A scanner should be testable without contacting the live API.

Separate network access from filtering logic:

def select_candidates(
    markets: list[dict],
    min_liquidity: float,
) -> list[dict]:

    return [
        market
        for market in markets
        if market.get("active")
        and float(market.get("liquidity") or 0) >= min_liquidity
    ]

Then test synthetic inputs:

def test_liquidity_filter():
    markets = [
        {"active": True, "liquidity": "50000"},
        {"active": True, "liquidity": "1000"},
        {"active": False, "liquidity": "90000"},
    ]

    result = select_candidates(markets, 10_000)

    assert len(result) == 1

Also test:

missing fields
malformed JSON
HTTP errors
empty pages
expired cursors
duplicate markets
unexpected API fields
rate-limit responses

Network tests should be separate integration tests.

15. Monitoring and Observability

A production scanner should answer:

How many markets were discovered?
How many passed each filter?
How long did discovery take?
How many CLOB requests were made?
How many requests failed?
What is the current scan cycle duration?
When was each candidate last updated?

Useful metrics include:

markets_discovered
markets_filtered
candidate_count
api_request_count
api_error_count
scan_duration_ms
candidate_age_seconds

Logging the number of candidates rejected by each filter is especially valuable.

If liquidity filtering suddenly eliminates 99% of markets, you want to know whether the market changed—or your API parsing broke.

16. Practical Example: Building a Shortlist

Imagine a strategy only wants markets that satisfy:

active = true
closed = false
liquidity >= configured threshold
volume >= configured threshold

The scanner creates:

[
    {
        "id": "123",
        "question": "Example question?",
        "liquidity": 25000,
        "volume": 80000,
    },
    {
        "id": "456",
        "question": "Another question?",
        "liquidity": 42000,
        "volume": 150000,
    },
]

The next component can then request detailed market state.

This architecture is much easier to reason about than a single Python script that simultaneously discovers markets, calculates signals, manages risk, signs orders, and submits trades.

17. Advanced Improvements

Once the basic scanner works, several upgrades become possible.

Tag-aware scanning

Use market tags to build specialized scanners for categories such as politics, crypto, sports, or economics.

Expiration-aware scanning

Prioritize markets based on time remaining until their end date.

Spread filtering

Exclude markets where the executable spread is too wide for your model.

Depth-aware filtering

A market can appear liquid while having insufficient depth at the price your strategy needs.

Model-driven scanning

Instead of simply ranking markets by volume, calculate:

model_probability - market_probability

Then investigate candidates with sufficiently large discrepancies.

That discrepancy is not automatically profit. It is a research signal that still requires execution and risk analysis.

Real-time architecture

For continuously updating systems:

flowchart TD
    A[Market Discovery] --> B[Candidate Registry]
    B --> C[WebSocket Subscriptions]
    C --> D[Live Order Book State]
    D --> E[Feature Engine]
    E --> F[Signal Engine]
    F --> G[Risk Engine]
    G --> H[Execution]

The scanner becomes the front door to the trading system rather than the entire system.

Frequently Asked Questions

What is a Polymarket market scanner?

A Polymarket market scanner is software that discovers and filters markets according to predefined conditions such as activity, liquidity, volume, price, expiration, or order-book characteristics.

Does a Polymarket scanner need API credentials?

Not for public market discovery. Polymarket documents public market data as accessible without authentication. ([Polymarket Documentation][1])

Should I use the Gamma API or CLOB API?

Use Gamma for broad market discovery and metadata, then use CLOB data when you need current prices or order-book information. ([Polymarket Documentation][1])

Can a scanner identify profitable trades?

It can identify candidates that satisfy a model's conditions, but it cannot guarantee profitability. Execution costs, liquidity, model error, and market risk remain.

Should a scanner use REST or WebSockets?

REST is appropriate for discovery and periodic scans. WebSockets are useful when the system needs continuously updated order-book and market-state information. ([Polymarket Documentation][4])

Conclusion

A good Polymarket market scanner is not complicated because of its number of lines of Python. It is complicated because it sits at the boundary between market discovery, real-time data, quantitative filtering, and eventually execution.

The strongest architecture is therefore modular:

discover → filter → enrich → rank → evaluate → execute

Start with public market data. Use keyset pagination for broad discovery. Reduce the universe before requesting expensive real-time data. Keep your scanner read-only until its data pipeline is reliable. Then add order-book state, quantitative models, risk controls, and execution as independent components.

That approach produces infrastructure that can evolve from a simple research script into a serious automated trading system without turning the scanner itself into an untestable monolith.

How to Build a Polymarket Trading Bot in Python
Anchor: Polymarket trading bot in Python
Why: Natural next step after market discovery.
Polymarket API Explained for Developers
Anchor: Polymarket API
Why: Explains the API architecture behind the scanner.
How to Read Polymarket Order Books in Python
Anchor: Polymarket order book data
Why: Extends candidate discovery into executable market-state analysis.
Building a Real-Time Polymarket WebSocket Client
Anchor: Polymarket WebSocket market data
Why: Moves from periodic scanning to streaming data.
Polymarket Trading Bot Architecture
Anchor: Polymarket trading bot architecture
Why: Shows how scanners fit into larger trading infrastructure.
Polymarket Probability and Fair-Value Modeling
Anchor: Polymarket fair-value model
Why: Connects market selection with quantitative evaluation.

Useful Resources

Polymarket — The trading platform and market interface.
Polymarket Documentation — Primary technical reference for APIs, SDKs, WebSockets, and market infrastructure. ([Polymarket Documentation][9])
Market Data Overview — Overview of Gamma, CLOB, and Data APIs and how market data is organized. ([Polymarket Documentation][1])
List Markets — Keyset Pagination — Relevant reference for implementing the scanner's market-discovery loop. ([Polymarket Documentation][2])
Polymarket Python SDK — Official unified Python SDK; currently documented as beta. ([GitHub][7])
Polymarket GitHub organization — Official developer repositories and tooling. ([GitHub][10])
Polymarket on X — Official Polymarket account.
Polymarket changelog — Useful for tracking API and platform changes. ([Polymarket Documentation][6])

I could not verify the specific Medium, DEV.to, or YouTube resources belonging to your content series from the information provided, so I have intentionally not fabricated those URLs.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: [https://x.com/xxniiinxx]
Youtube: [https://youtube.com/@bosonax]
Telegram: [https://t.me/bosonax]

Polymarket API Explained for Developers: CLOB, Gamma, Data & WebSockets

Bo$onaX — Wed, 19 Aug 2026 15:13:31 +0000

Polymarket API Explained: CLOB, Gamma, Data & WebSockets

Learn the Polymarket API from a developer’s perspective: Gamma, CLOB, Data API, WebSockets, authentication, Python SDKs, rate limits and bots.

Polymarket API Explained for Developers

If you are building a Polymarket trading bot, analytics system, market scanner, dashboard, or automated execution engine, the difficult part is not sending an HTTP request.

The difficult part is understanding which Polymarket API should own which responsibility.

Polymarket currently exposes several developer surfaces: Gamma for market discovery and metadata, the CLOB API for prices, order books and trading, the Data API for positions and historical activity, and WebSocket channels for real-time updates. The official documentation also provides SDKs for interacting with these systems.

There is another important reason to understand the architecture before writing a bot: Polymarket's production trading stack changed substantially in 2026. CLOB V2 went live on the production CLOB host in April 2026, and legacy V1 SDKs and V1-signed orders are no longer supported in production.

This guide builds a developer-oriented mental model of the current Polymarket API, shows how the different services fit together, demonstrates Python integration patterns, and explains what changes when you move from a research script to a production trading system.

Technical note: Polymarket's APIs evolve. Endpoint names, SDK surfaces, limits, and authentication requirements should always be checked against the current official documentation before deploying a live trading system.

What You'll Learn

By the end of this guide, you will understand:

How the Polymarket API architecture is divided
When to use Gamma API versus CLOB API versus Data API
How market IDs, condition IDs, and token IDs relate
How to retrieve market metadata with Python
How to inspect prices and order books
How Polymarket WebSockets differ from REST polling
How CLOB authentication works
The distinction between L1 wallet authentication and L2 API credentials
How the current CLOB V2 architecture affects integrations
How to design retries, rate-limit handling, and reconnect logic
How to structure a production trading bot around the API
What to log and monitor
Which security mistakes can turn a bot into a liability

1. The Polymarket API Architecture

The first mistake developers make is thinking of the Polymarket API as one REST API.

It is better to think of it as a collection of services with different jobs.

At a high level:

                         Your Application
                                |
              +-----------------+-----------------+
              |                 |                 |
              v                 v                 v
        Gamma API           CLOB API          Data API
        Discovery        Prices / Books      Positions /
        Metadata          Trading            Analytics
              |                 |                 |
              +-----------------+-----------------+
                                |
                           WebSocket
                         Real-time events
                                |
                                v
                       Trading / Strategy
                                |
                                v
                         Polygon settlement

Polymarket's official market-data documentation describes three primary REST surfaces:

API	Primary responsibility	Typical use
Gamma API	Events, markets and discovery	Find markets and metadata
CLOB API	Prices, order books and trading	Trading and execution
Data API	Positions, trades and analytics	Portfolio and historical analysis
WebSocket	Streaming market/user events	Real-time systems

The official documentation explicitly separates Gamma, CLOB and Data API functionality in this way.

That separation should also appear in your application architecture.

A trading bot should generally not use the same request loop for market discovery, order-book updates, account reconciliation, and order execution.

2. Gamma API: Market Discovery and Metadata

The Gamma API is where you typically start.

Its production base URL is:

https://gamma-api.polymarket.com

Gamma exposes market and event discovery endpoints such as:

GET /events
GET /events/{id}
GET /markets
GET /markets/{id}
GET /public-search
GET /tags
GET /series
GET /sports
GET /teams

These endpoints are public market-data endpoints and do not require wallet authentication.

For example, retrieving a market by ID uses:

GET https://gamma-api.polymarket.com/markets/{id}

and the response contains metadata including the question, condition ID, slug, dates, category and other market attributes.

Why Gamma matters to a trading bot

Suppose your strategy trades only:

active markets,
markets closing within a particular time window,
markets containing a specific category,
markets with sufficient liquidity,
or markets matching a particular question pattern.

You should solve that filtering problem before your execution engine ever considers placing an order.

A useful architecture is:

Gamma
  |
  | market discovery
  v
Market Registry
  |
  | eligible token IDs
  v
Strategy Engine
  |
  v
CLOB

This avoids repeatedly querying metadata during latency-sensitive execution.

3. Market IDs, Condition IDs and Token IDs

This is one of the most important concepts for Polymarket developers.

A market can have multiple identifiers representing different layers of the system.

You will encounter concepts such as:

market ID
event ID
condition ID
token ID / asset ID
slug

Do not treat these as interchangeable strings.

The Gamma API is primarily concerned with market and event metadata. The CLOB operates on outcome token IDs when you request prices, order books, or create orders.

The official market-data documentation describes a market as mapping to CLOB token IDs, a market address, a question ID and a condition ID.

For a binary market, your application will typically need to identify the appropriate outcome token before asking the CLOB for its book.

Conceptually:

Event
  |
  +-- Market
       |
       +-- Condition ID
       |
       +-- YES token ID
       |
       +-- NO token ID

This distinction matters because an order-book request needs an asset/token identifier, not merely the human-readable question.

Practical rule

Store identifiers explicitly in your internal model:

from dataclasses import dataclass


@dataclass(frozen=True)
class MarketRef:
    market_id: str
    condition_id: str
    yes_token_id: str
    no_token_id: str
    slug: str

Do not scatter raw IDs throughout your strategy code.

4. CLOB API: The Trading Layer

The CLOB is the part of the Polymarket API that matters most when your application actually needs to trade.

The production CLOB host is:

https://clob.polymarket.com

The official documentation describes Polymarket's CLOB as a hybrid-decentralized trading system: orders are matched off-chain while matched trades settle onchain. Orders are EIP-712 signed messages, and settlement occurs on Polygon.

The CLOB exposes functionality for:

prices,
order books,
spreads,
midpoint prices,
historical prices,
order creation,
order cancellation,
open orders,
trades,
account information,
and related trading operations.

The public market-data surface includes endpoints such as:

GET /price
GET /prices
GET /book
POST /books
GET /prices-history
GET /midpoint
GET /spread

according to the current official documentation.

5. Reading an Order Book

An automated strategy should rarely make a trading decision from a single displayed price.

The order book provides a more useful execution picture.

Conceptually:

ASKS
0.63   500
0.62   350
0.61   200
----------------
0.60   250   <- best bid
0.59   400
0.58   700
BIDS

From this you can derive:

best bid,
best ask,
spread,
depth,
available size,
estimated execution price,
and potential slippage.

The CLOB exposes /book for an individual token and /books for multiple books.

A simple read-only request can be implemented without exposing any trading credentials:

import requests


CLOB_URL = "https://clob.polymarket.com"


def get_order_book(token_id: str) -> dict:
    response = requests.get(
        f"{CLOB_URL}/book",
        params={"token_id": token_id},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


book = get_order_book("YOUR_TOKEN_ID")

print(book)

Replace YOUR_TOKEN_ID with a real token ID obtained from your market-discovery workflow.

Do not assume the first price is the executable price

A common bot-design error is:

price = get_price(...)
buy(price)

A production execution engine should instead reason about:

signal
  |
  v
target price
  |
  v
current book
  |
  +--> spread
  |
  +--> available depth
  |
  +--> expected fill price
  |
  +--> slippage
  |
  v
risk checks
  |
  v
order

The distinction becomes especially important when the strategy trades meaningful size.

6. Price, Midpoint and Spread

The CLOB provides separate concepts for:

price,
midpoint,
spread,
order book.

Do not collapse them into one variable called market_price.

For example:

import requests


def get_json(path: str, params: dict | None = None) -> dict:
    response = requests.get(
        f"https://clob.polymarket.com{path}",
        params=params,
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


token_id = "YOUR_TOKEN_ID"

price = get_json("/price", {"token_id": token_id})
midpoint = get_json("/midpoint", {"token_id": token_id})
spread = get_json("/spread", {"token_id": token_id})

print("Price:", price)
print("Midpoint:", midpoint)
print("Spread:", spread)

For strategy research, these values answer different questions.

Price can be useful for a specific side.

Midpoint gives you a reference between the current bid and ask.

Spread tells you something about the cost of crossing the market.

Order-book depth tells you whether your intended size can actually be executed near the displayed price.

7. Tick Size and Fee Information

A robust trading engine should not hard-code assumptions about every market.

The CLOB provides endpoints for market-specific properties such as tick size and fee rate.

For example, the current documentation exposes:

GET /tick-size
GET /fee-rate

with token_id identifying the relevant asset.

The tick-size endpoint returns a minimum_tick_size, while the fee-rate endpoint returns a base fee rate in basis points.

That means an execution engine should conceptually do this:

market selected
      |
      v
fetch market parameters
      |
      +--> tick size
      |
      +--> fee information
      |
      +--> neg-risk / market configuration
      |
      v
validate order
      |
      v
sign
      |
      v
submit

Do not assume every market can accept arbitrary decimal prices.

The official Python SDK changelog also documents validation around prices being multiples of the tick size.

8. Data API: Positions, Trades and Analytics

The Data API answers a different class of questions.

Its production host is:

https://data-api.polymarket.com

The current documentation includes endpoints for:

GET /positions
GET /closed-positions
GET /activity
GET /value
GET /oi
GET /holders
GET /trades

These are intended for positions, activity, market analytics and historical trade information.

For example, current positions can be requested through:

GET https://data-api.polymarket.com/positions

The response contains fields such as asset, condition ID, size, average price, current value, PnL-related fields, outcome and market metadata.

Why not use the CLOB for everything?

Because the services answer different questions.

A clean bot architecture might use:

Gamma
  -> What markets exist?

CLOB
  -> What can I trade right now?

Data API
  -> What positions/activity do I have?

WebSocket
  -> What changed since the last event?

That division is much easier to maintain than a single giant API wrapper.

9. WebSockets: Stop Polling When You Need Real-Time State

REST is excellent for snapshots.

It is not always the right abstraction for continuous state.

Polymarket provides public WebSocket market channels for real-time order-book, price and market-lifecycle updates. The current market channel includes book snapshots, price changes, last-trade-price events and tick-size changes.

The market channel is:

/wss/market

A subscription contains asset IDs.

Conceptually:

REST
 |
 +--> initial snapshot
 |
 v
WebSocket
 |
 +--> book update
 +--> price change
 +--> trade
 +--> tick-size change
 +--> lifecycle event

The official market-channel documentation also specifies a client heartbeat: send a ping every 10 seconds and expect a pong response.

That detail matters in production.

A WebSocket client should not simply:

ws.recv()
ws.recv()
ws.recv()

forever.

It needs:

heartbeat handling,
reconnect logic,
subscription restoration,
sequence/state validation where applicable,
logging,
connection metrics,
and a recovery path back to REST snapshots.

10. User WebSocket Channel

For authenticated applications, Polymarket also provides a user WebSocket channel.

The user channel can stream order and trade events. Its subscription uses API credentials and supports market subscriptions.

This is particularly useful for execution engines.

Instead of repeatedly asking:

"Is my order filled?"

your application can maintain an event-driven order state.

For example:

ORDER_SUBMITTED
      |
      v
ORDER_ACKNOWLEDGED
      |
      v
LIVE
      |
      +--------+
      |        |
      v        v
PARTIAL    CANCELLED
FILL          |
      |        |
      v        |
FILLED <-------+

The event stream should update your local order state, while periodic reconciliation against the REST API protects against missed messages or connection failures.

11. The Authentication Model: L1 vs L2

One of the most important pieces of the Polymarket API is its authentication model.

The current CLOB documentation describes two authentication levels:

Level	Mechanism	Purpose
L1	EIP-712 wallet signature	Create/derive API credentials
L2	HMAC-SHA256 API credentials	Authenticated trading/account requests

The official documentation states that your private key is used to derive L2 credentials, consisting of an API key, secret and passphrase.

This distinction is important because API credentials do not replace order signing.

For order creation, the order itself still requires an appropriate EIP-712 signature. L2 authentication authenticates the API request; it is not the same thing as authorizing the signed order.

Think about it this way:

Wallet private key
       |
       | EIP-712 authentication
       v
L2 API credentials
       |
       | HMAC-authenticated API request
       v
CLOB
       |
       | EIP-712 signed order
       v
Order matching

This is why simply obtaining an API key is not equivalent to having a complete trading integration.

12. Never Put Private Keys in Source Code

This should be non-negotiable.

Bad:

PRIVATE_KEY = "0x123..."

Better:

import os

private_key = os.environ["POLYMARKET_PRIVATE_KEY"]

For local development:

export POLYMARKET_PRIVATE_KEY="..."

For production, use a proper secrets manager or protected environment configuration.

Never commit:

private keys,
seed phrases,
API secrets,
passphrases,
wallet credentials,
.env files containing production credentials.

A trading bot with a leaked private key is not merely a software bug. It can become a direct loss-of-funds event.

13. Current SDK Situation

This is an area where older tutorials can become dangerous.

Polymarket's older py-clob-client repository was archived on May 25, 2026.

Polymarket now maintains an official unified Python SDK under the polymarket-client package. Its repository describes it as the official Python SDK and says it provides a unified interface across public data, authenticated accounts, trading, builder attribution and wallet workflows.

However, the unified SDK is explicitly marked beta.

That produces an important practical distinction:

New project
   |
   +--> Evaluate official unified Python SDK
   |
   +--> Verify current API surface
   |
   +--> Pin/test the version
   |
   +--> Build integration tests

For CLOB-specific integrations, the official documentation currently points developers toward the CLOB V2 Python client:

pip install py-clob-client-v2

The CLOB trading overview lists the Python V2 client alongside the current TypeScript and Rust clients.

Do not copy an old 2025 tutorial's dependency list into a production system without checking whether it targets the current CLOB architecture.

14. A Minimal Python Market-Discovery Client

For market discovery, plain HTTP is often enough.

from __future__ import annotations

import logging
from typing import Any

import requests


logger = logging.getLogger(__name__)

GAMMA_URL = "https://gamma-api.polymarket.com"


class GammaClient:
    def __init__(self, timeout: float = 10.0) -> None:
        self.timeout = timeout
        self.session = requests.Session()

    def list_markets(self, limit: int = 10) -> list[dict[str, Any]]:
        response = self.session.get(
            f"{GAMMA_URL}/markets",
            params={"limit": limit},
            timeout=self.timeout,
        )
        response.raise_for_status()

        payload = response.json()

        if isinstance(payload, list):
            return payload

        if isinstance(payload, dict) and "data" in payload:
            return payload["data"]

        raise ValueError("Unexpected Gamma API response format")


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)

    client = GammaClient()

    try:
        markets = client.list_markets(limit=5)

        for market in markets:
            logger.info(
                "market=%s question=%s",
                market.get("id"),
                market.get("question"),
            )

    except requests.RequestException:
        logger.exception("Gamma request failed")
    except ValueError:
        logger.exception("Unexpected Gamma response")

This example is intentionally read-only.

It does not require:

a private key,
API credentials,
a wallet,
or order-signing logic.

That makes it a good first integration test.

15. Using the Official Unified Python SDK

The official unified SDK currently supports a public client interface.

The official repository documents:

pip install polymarket-client

and provides a synchronous PublicClient as well as an asynchronous AsyncPublicClient.

A basic read-only example is:

from polymarket import PublicClient


with PublicClient() as client:
    market = client.get_market(
        slug="YOUR_MARKET_SLUG"
    )

    print(market)

The SDK's public client source confirms that market lookup supports identifiers such as ID, slug, and URL.

Because the unified SDK is still beta, production systems should pin the dependency, run integration tests against the exact version being deployed, and monitor the project's release notes.

16. Building a Production-Oriented API Layer

Do not allow strategy code to directly construct HTTP requests.

Instead:

Strategy
   |
   v
MarketService
   |
   +--> Gamma
   |
   +--> CLOB
   |
   +--> Data API
   |
   +--> WebSocket

For example:

class MarketService:
    def __init__(
        self,
        gamma_client,
        clob_client,
        data_client,
    ):
        self.gamma = gamma_client
        self.clob = clob_client
        self.data = data_client

    def get_market_snapshot(self, market):
        metadata = self.gamma.get_market(market)
        book = self.clob.get_order_book(metadata.yes_token_id)

        return {
            "market": metadata,
            "book": book,
        }

Your strategy should not care whether the data came from:

requests,
httpx,
an SDK,
a cache,
or a WebSocket-maintained local book.

That separation makes later infrastructure changes much easier.

17. Rate Limits Are Part of the API Contract

A production Polymarket integration needs explicit rate-limit handling.

The current official rate-limit documentation states that API limits are enforced through Cloudflare throttling and that requests exceeding limits can be delayed/queued rather than immediately rejected. The limits operate over sliding windows.

Examples currently documented include:

Surface	Endpoint	Documented limit
Gamma	`/markets`	300 req / 10s
Gamma	`/events`	500 req / 10s
Data	`/positions`	150 req / 10s
Data	`/trades`	200 req / 10s
CLOB	`/book`	1,500 req / 10s
CLOB	`/price`	1,500 req / 10s
CLOB	`/midpoint`	1,500 req / 10s

The official page contains the complete current table, including trading endpoint burst and sustained limits.

Do not build this:

while True:
    GET /markets
    GET /book
    GET /price
    sleep(0.01)

Build this instead:

Startup
  |
  +--> Discover markets
  |
  +--> Cache metadata
  |
  v
WebSocket stream
  |
  +--> update market state
  |
  v
Strategy
  |
  +--> request REST snapshot only when required

Streaming plus caching is usually a much cleaner architecture than aggressive REST polling.

18. Retry Strategy

Retries should distinguish between transient infrastructure errors and permanent application errors.

A basic pattern:

import random
import time

import requests


RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}


def get_with_retry(
    session: requests.Session,
    url: str,
    *,
    params: dict | None = None,
    attempts: int = 5,
    timeout: float = 10.0,
) -> requests.Response:

    for attempt in range(attempts):
        try:
            response = session.get(
                url,
                params=params,
                timeout=timeout,
            )

            if response.status_code not in RETRYABLE_STATUS_CODES:
                response.raise_for_status()
                return response

        except requests.RequestException:
            if attempt == attempts - 1:
                raise

        if attempt == attempts - 1:
            response.raise_for_status()

        delay = min(
            5.0,
            0.25 * (2 ** attempt) + random.uniform(0, 0.1),
        )

        time.sleep(delay)

    raise RuntimeError("Unreachable")

But retries require more thought for trading operations.

A retry of:

GET /book

is usually straightforward.

A retry of:

POST /order

can be materially different.

Before automatically retrying an order submission, your system should determine whether the original request was:

rejected,
accepted,
processed but response lost,
or actually matched.

Blindly submitting the same trading instruction again can create duplicate exposure.

19. Idempotency and Order State

A production execution engine should maintain its own order lifecycle.

For example:

strategy signal
      |
      v
risk approval
      |
      v
order intent created
      |
      v
signed order
      |
      v
submission
      |
      v
local state = SUBMITTED
      |
      +--> WebSocket event
      |
      +--> REST reconciliation
      |
      v
LIVE / PARTIAL / FILLED / CANCELLED / REJECTED

The database should store enough information to reconstruct what happened.

At minimum, consider persisting:

client order identifier
market
token ID
side
requested price
requested size
order type
creation timestamp
submission timestamp
exchange order ID
status
matched size
average execution price
error code

This becomes extremely valuable when debugging a bot after a network failure.

20. WebSocket + REST Reconciliation

Never assume a WebSocket connection is perfect.

A robust system treats WebSocket events as a fast state-update mechanism and REST as a reconciliation mechanism.

For example:

                +----------------+
                | Local State DB |
                +-------+--------+
                        ^
                        |
            +-----------+-----------+
            |                       |
            |                       |
      WebSocket                 REST
      real-time                 snapshot
      updates                   reconciliation

If the WebSocket disconnects:

mark the stream stale;
stop making decisions that depend on unknown state if necessary;
reconnect;
restore subscriptions;
obtain a fresh snapshot;
reconcile local state;
resume normal processing.

This is far safer than simply reconnecting and continuing from stale memory.

21. Practical Example: Market Scanner

Let's build a small research-oriented scanner.

The objective is not to trade.

It will:

query Gamma;
identify markets;
obtain token IDs;
query CLOB market data;
calculate a simple spread metric;
print candidates.

from __future__ import annotations

import requests


GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

session = requests.Session()


def get(url: str, **kwargs):
    response = session.get(
        url,
        timeout=10,
        **kwargs,
    )
    response.raise_for_status()
    return response.json()


def get_markets(limit: int = 20):
    payload = get(
        f"{GAMMA}/markets",
        params={"limit": limit},
    )

    if isinstance(payload, list):
        return payload

    return payload.get("data", [])


def get_book(token_id: str):
    return get(
        f"{CLOB}/book",
        params={"token_id": token_id},
    )


def best_prices(book: dict):
    bids = book.get("bids", [])
    asks = book.get("asks", [])

    if not bids or not asks:
        return None, None

    best_bid = max(float(level["price"]) for level in bids)
    best_ask = min(float(level["price"]) for level in asks)

    return best_bid, best_ask


for market in get_markets():
    question = market.get("question")

    # The exact field containing outcome/token information
    # should be validated against the current Gamma response
    # for the markets you intend to support.
    token_ids = market.get("clobTokenIds")

    if not token_ids:
        continue

    try:
        first_token = token_ids[0]
        book = get_book(first_token)

        bid, ask = best_prices(book)

        if bid is None or ask is None:
            continue

        print(
            f"{question}\n"
            f"  bid={bid:.4f} ask={ask:.4f} "
            f"spread={ask - bid:.4f}"
        )

    except (requests.RequestException, ValueError, TypeError) as exc:
        print(f"Skipping market: {exc}")

This is intentionally a research example, not a production trading engine.

The important engineering idea is the separation:

Gamma -> identify candidate
CLOB  -> inspect execution conditions
Strategy -> decide
Risk -> approve/reject
Execution -> trade

22. What a Real Trading Bot Should Look Like

A production Polymarket bot should be closer to this:

flowchart TD
    A[Gamma Market Discovery] --> B[Market Registry]
    B --> C[Eligibility Filter]

    C --> D[WebSocket Market Stream]
    D --> E[Local Market State]

    E --> F[Strategy Engine]
    F --> G[Risk Engine]

    G -->|Approved| H[Execution Engine]
    G -->|Rejected| I[Log Decision]

    H --> J[CLOB V2]
    J --> K[Order Events]

    K --> L[Order State Store]
    L --> M[Portfolio / Position Reconciliation]

    N[Data API] --> M
    M --> G

    O[Monitoring] --> D
    O --> H
    O --> M

This architecture creates explicit boundaries between:

discovery,
market data,
strategy,
risk,
execution,
portfolio state,
and observability.

That separation is more important than whether your strategy is 100 lines or 10,000 lines.

23. Performance Considerations

Performance is not simply about making HTTP requests faster.

For an automated trading system, the relevant pipeline is:

market event
   ↓
network transport
   ↓
message parsing
   ↓
state update
   ↓
strategy calculation
   ↓
risk checks
   ↓
order creation
   ↓
signature
   ↓
submission
   ↓
matching

Optimizing only one stage can produce little improvement if another stage dominates the path.

Use WebSockets for continuously changing state

If you need continuous order-book updates, streaming is generally more appropriate than repeatedly requesting snapshots.

Keep market metadata local

Do not repeatedly retrieve the same market description every time a price changes.

Precompute strategy state

If your strategy repeatedly calculates the same features, maintain incremental state rather than rebuilding the entire dataset.

Separate hot and cold paths

A useful distinction:

Cold path

market discovery,
historical analysis,
configuration,
metadata refresh.

Hot path

order-book events,
signal evaluation,
risk checks,
order submission,
order-state updates.

This architecture lets you optimize the latency-sensitive portion without turning the entire codebase into a low-level networking project.

24. Do Not Confuse Latency With Edge

A fast API client does not automatically create a profitable trading strategy.

Even if your infrastructure reacts quickly, you still face:

spread,
slippage,
liquidity constraints,
adverse selection,
fees where applicable,
market impact,
stale information,
model error,
execution uncertainty,
resolution risk.

The correct optimization target is therefore not:

"Make the bot as fast as possible."

It is:

"Make the complete decision-to-execution pipeline reliable enough that the strategy's assumptions remain valid."

Speed is one component of execution quality.

25. Security Architecture

A trading system should have at least three security boundaries.

Boundary 1: Secrets

Private keys and API secrets belong in a secrets-management layer.

Boundary 2: Strategy

Strategy code should not automatically have permission to transfer arbitrary funds or modify infrastructure.

Boundary 3: Execution

The execution engine should enforce limits independently of strategy code.

For example:

class RiskLimits:
    max_order_size: float
    max_position_size: float
    max_daily_loss: float
    max_open_orders: int

Then:

def approve_order(order, limits) -> bool:
    if order.size > limits.max_order_size:
        return False

    if order.projected_position > limits.max_position_size:
        return False

    return True

The point is not that these exact limits are appropriate.

The point is that risk controls should not depend on the strategy remembering to apply them.

26. Geographic and Account Constraints

API access does not mean every user or institution can necessarily trade every product.

Polymarket's documentation includes geographic restrictions and eligibility requirements, and developers should validate the applicable restrictions for their users and deployment. The institutional site also states that institutional eligibility depends on jurisdiction.

Do not build an application that assumes:

API accessible = trading permitted

Those are different questions.

Your onboarding flow should validate the applicable account, geographic and product restrictions before attempting live trading.

27. Failure Modes You Should Expect

Failure 1: Using an outdated SDK

Older tutorials may reference the archived py-clob-client.

Fix: verify the current CLOB V2 documentation and official SDK repositories before installing dependencies.

Failure 2: Treating a market ID as a token ID

The CLOB's price and order-book operations operate on asset/token identifiers.

Fix: explicitly maintain the mapping between market metadata and CLOB token IDs.

Failure 3: Polling everything

A bot that repeatedly requests:

markets
prices
books
positions
orders

can become unnecessarily expensive and difficult to scale.

Fix: cache metadata, use streaming where appropriate, and use REST for snapshots/reconciliation.

Failure 4: Retrying POST blindly

If a response disappears after an order was accepted, automatically submitting the same order again can create unintended exposure.

Fix: implement order-state reconciliation.

Failure 5: Ignoring tick size

A strategy can calculate a mathematically valid price that is not valid for the market's configured increment.

Fix: retrieve and enforce the applicable tick size.

Failure 6: Hard-coding fees

Market economics can change, and the current CLOB provides a fee-rate endpoint.

Fix: retrieve the applicable fee information and include it in execution calculations.

Failure 7: Trusting WebSocket state forever

A disconnected or partially processed stream can leave local state stale.

Fix: reconnect and reconcile against authoritative REST data.

Failure 8: Logging secrets

Avoid:

logger.info("credentials=%s", credentials)

Instead log:

request_id
market_id
token_id
latency
status
error_code
order_id

but never private keys or API secrets.

28. Testing Strategy

A trading integration should have several levels of testing.

Unit tests

Test:

price rounding,
tick-size validation,
spread calculations,
position calculations,
risk limits,
retry behavior,
order-state transitions.

Example:

def test_price_matches_tick_size():
    tick_size = 0.01
    price = 0.55

    assert round(price / tick_size) * tick_size == price

Integration tests

Test:

Gamma market retrieval,
CLOB connectivity,
WebSocket subscriptions,
Data API queries,
authentication,
order lifecycle handling.

The official unified SDK repository itself distinguishes ordinary unit tests from opt-in integration tests and separately protects metered tests that can spend funds or mutate live state.

That is a useful model for your own test suite.

Failure-injection tests

Simulate:

HTTP 429,
HTTP 500,
connection reset,
malformed JSON,
WebSocket disconnect,
delayed response,
duplicate events,
missing events,
stale market state.

The goal is not merely to prove that the happy path works.

The goal is to discover what the bot does when the network behaves badly.

29. Observability

At minimum, measure:

API metrics

request_count
error_count
429_count
latency_ms
timeout_count

WebSocket metrics

connection_count
disconnect_count
reconnect_count
last_message_age
subscription_count

Trading metrics

orders_submitted
orders_rejected
orders_cancelled
orders_filled
partial_fills

Strategy metrics

signals_generated
signals_rejected_by_risk
signals_executed

Portfolio metrics

position_size
cash_balance
open_order_count
realized_pnl
unrealized_pnl

The Polymarket status system separately tracks the Trading API, WebSocket, Markets/Position data and on-chain settlement infrastructure.

Your monitoring should therefore avoid treating "Polymarket is up" as one binary condition.

A bot can have:

Gamma: healthy
CLOB: healthy
WebSocket: disconnected
Data API: healthy

and still be unable to operate correctly.

30. Production Deployment Checklist

Before enabling live trading:

[ ] Verify the current official API documentation
[ ] Confirm the SDK version
[ ] Test market discovery
[ ] Test token-ID mapping
[ ] Validate tick size
[ ] Validate fee assumptions
[ ] Test order signing
[ ] Test authentication
[ ] Test cancellation
[ ] Test WebSocket reconnection
[ ] Test REST reconciliation
[ ] Implement risk limits
[ ] Implement rate-limit handling
[ ] Implement structured logging
[ ] Remove credentials from logs
[ ] Run a dry-run strategy
[ ] Test failure scenarios
[ ] Pin dependencies
[ ] Set up alerts
[ ] Verify jurisdiction/account eligibility
[ ] Start with deliberately constrained exposure

31. Advanced Improvement: Build a Local Market State Engine

For sophisticated bots, the API client should not be the strategy's state store.

Instead, maintain:

@dataclass
class MarketState:
    token_id: str
    best_bid: float | None
    best_ask: float | None
    midpoint: float | None
    spread: float | None
    last_trade_price: float | None
    updated_at: float

Then WebSocket messages mutate this state.

Your strategy consumes:

state = market_state.get(token_id)

rather than issuing a network request every time it wants a price.

This changes the architecture from:

strategy -> API -> response -> strategy

to:

WebSocket -> local state -> strategy

That is a much stronger foundation for event-driven systems.

32. Advanced Improvement: Separate Decision Time From Execution Time

Store both.

For example:

signal_created_at
risk_check_at
order_signed_at
order_submitted_at
exchange_ack_at
first_fill_at
final_fill_at

Then calculate:

signal -> risk
risk -> signing
signing -> submission
submission -> acknowledgement
acknowledgement -> fill

This lets you identify where execution actually spends time.

Without these timestamps, "the bot is slow" is not an actionable diagnosis.

33. Advanced Improvement: Treat Market Metadata as Versioned State

Market metadata can change.

Do not assume:

market = load_once_forever()

A better design periodically refreshes metadata and records changes:

Market Registry
      |
      +--> metadata version
      +--> active/closed state
      +--> token mapping
      +--> tick size
      +--> market configuration

If your bot behaves differently after a market configuration change, you should be able to reconstruct what metadata it was using at the time.

34. Advanced Improvement: Add a Kill Switch

Every automated trading system should have a mechanism to stop opening new exposure.

For example:

class TradingMode:
    ENABLED = "enabled"
    REDUCE_ONLY = "reduce_only"
    DISABLED = "disabled"

Then the execution layer checks the mode before accepting an order.

This gives you a way to respond to:

broken market data,
unexpected API behavior,
strategy anomalies,
excessive losses,
corrupted state,
infrastructure incidents.

A kill switch should be implemented outside the strategy itself.

35. Current Polymarket API Architecture in One Diagram

The entire system can be reduced to this mental model:

flowchart LR
    A[Gamma API] --> B[Market Registry]
    B --> C[Token IDs]

    C --> D[CLOB REST]
    C --> E[CLOB WebSocket]

    D --> F[Prices / Books]
    E --> F

    G[Data API] --> H[Positions / Trades / Analytics]

    F --> I[Strategy]
    H --> I

    I --> J[Risk Engine]
    J --> K[CLOB V2 Order Signing]
    K --> L[Order Submission]

    L --> M[User WebSocket]
    M --> N[Order State]

    N --> H

If you remember only one thing from this article, remember this:

Gamma tells your application what exists. CLOB tells it what can be traded and executes orders. Data API tells it what happened to positions and activity. WebSockets tell it what is changing now.

That division is the foundation of a maintainable Polymarket integration.

36. Frequently Asked Questions

What is the Polymarket API?

The Polymarket API is the collection of developer interfaces used to access Polymarket market data, trading infrastructure, positions, analytics and real-time events. The primary REST surfaces are Gamma, CLOB and Data API, complemented by WebSocket channels.

Does Polymarket have a Python API?

Yes. Polymarket maintains an official Python SDK, currently distributed as polymarket-client. The project is currently in beta. Polymarket also documents a Python CLOB V2 client for CLOB trading integrations.

Can I access Polymarket market data without authentication?

Yes. The official market-data documentation states that public market data is available without an API key, authentication or wallet.

Which API should I use to build a trading bot?

A typical bot will use Gamma for market discovery, CLOB for order books and execution, Data API for portfolio/activity information, and WebSockets for real-time market and user events.

What are L1 and L2 authentication?

L1 uses an EIP-712 wallet signature and is used to create or derive API credentials. L2 uses HMAC-SHA256 API credentials for authenticated API operations. Orders themselves still require appropriate wallet-based order signing.

Is the old `py-clob-client` still the right SDK?

The original Polymarket/py-clob-client repository was archived in May 2026. The current documentation points developers toward the CLOB V2 client, while Polymarket also maintains a newer unified Python SDK that is currently beta.

Should I poll the CLOB or use WebSockets?

For continuously changing market state, WebSockets are generally the more appropriate architecture. REST remains useful for snapshots, queries and reconciliation. The official market channel provides order-book and price events.

Does a faster Polymarket API integration guarantee trading profits?

No. API performance does not guarantee profitability. Execution quality depends on liquidity, spread, slippage, fees, adverse selection, strategy quality, model risk and other factors.

37. Conclusion

The most important lesson when working with the Polymarket API is that you should stop thinking about it as a single endpoint collection.

Think in systems.

Gamma handles discovery and metadata.

CLOB handles prices, order books and trading.

Data API handles positions, trades and analytics.

WebSockets handle continuously changing state.

Wallet signatures and L2 credentials provide the authentication and authorization layers needed for authenticated trading.

And your own application must provide the parts Polymarket cannot provide for you:

strategy logic,
risk controls,
state management,
retries,
reconciliation,
observability,
secrets management,
testing,
and operational safeguards.

The difference between a five-minute API experiment and a serious trading system is not the ability to call GET /book.

It is everything surrounding that call.

If you are building a Polymarket bot, start with read-only market discovery, build a reliable local market-state layer, add WebSocket processing, implement risk controls, and only then introduce authenticated execution.

That sequence keeps the system understandable—and makes failures much easier to diagnose.

Educational/trading-risk disclaimer: This article is for software-development and educational purposes only. Automated prediction-market trading involves financial risk, execution risk, liquidity risk and the possibility of losing capital. API behavior and market rules can change. Always verify current Polymarket documentation and test integrations before deploying live funds.

Build these as a topic cluster around the Polymarket API pillar article:

How to Build a Polymarket Trading Bot in Python

Anchor: build a Polymarket trading bot in Python
Why: Converts API knowledge into a complete automation workflow.

Polymarket CLOB API: Order Books, Prices and Order Execution

Anchor: Polymarket CLOB API
Why: Deepens the execution/API layer introduced here.

Polymarket Gamma API: Market Discovery and Metadata

Anchor: Polymarket Gamma API
Why: Targets developers primarily interested in market discovery.

How Polymarket WebSockets Work

Anchor: Polymarket WebSocket API
Why: Expands the real-time architecture section.

Polymarket API Authentication: L1, L2 and EIP-712

Anchor: Polymarket API authentication
Why: Provides a dedicated security/authentication resource.

How to Read a Polymarket Order Book With Python

Anchor: read a Polymarket order book with Python
Why: Targets a practical implementation query.

Polymarket Trading Bot Architecture

Anchor: Polymarket trading bot architecture
Why: Extends the architecture diagrams into a full system-design article.

Polymarket CLOB V2 Migration Guide for Python Developers

Anchor: Polymarket CLOB V2 migration
Why: Captures developers maintaining older integrations.

Useful Resources

Official Polymarket

Polymarket

Useful for understanding the live market interface and validating how market metadata is presented to users.

Official API Documentation

Polymarket Developer Documentation

The primary technical authority for current endpoints, authentication, SDKs, rate limits and trading behavior.

Relevant API Reference

Polymarket Market Data Overview

A particularly useful starting point because it explains how Gamma, CLOB and Data API responsibilities are separated.

Official Python SDK

Polymarket Python SDK on GitHub

The official unified Python client. It is currently beta, so developers should check its release history and test the exact dependency version they deploy.

Medium: Polymarket API for Developers

Polymarket API for Developers: Data, CLOB, and Polygon RPC

A useful third-party overview of the API architecture. It should be treated as supplementary rather than authoritative; current API behavior should be verified against Polymarket's official documentation.

YouTube: Polymarket API With Python

A practical third-party walkthrough covering API setup, market data, order books and Python-based trading. It was published before the current CLOB V2 migration, so developers should cross-check implementation details against current official documentation.

Official Polymarket X

Polymarket on X

Useful for product and ecosystem announcements. Technical implementation details should still be verified against the official developer documentation.

Official Developer Resources

Polymarket GitHub Organization

Contains official SDKs, client libraries and developer tooling. The organization's repositories include the current Python SDK and CLOB V2 clients.

DEV.to resource: No sufficiently relevant DEV.to article was verified during research, so it is intentionally omitted rather than publishing an unverified URL.

About the Author

Bo$onaX

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: [https://x.com/xxniiinxx]
Telegram: [https://t.me/bosonax]

Polymarket Trading Bot in Python: Build Guide for 2026

Bo$onaX — Tue, 18 Aug 2026 19:24:50 +0000

Build a Polymarket trading bot in Python with market discovery, order books, execution, risk controls, testing, and production monitoring.

How to Build a Polymarket Trading Bot in Python

Current-API note: Polymarket's developer stack is evolving. This guide reflects the official documentation and repositories checked on August 18, 2026. The official Python SDK, polymarket-client, is currently in beta; the older py-clob-client repository has been archived and its README explicitly says it should not be used for new integrations.

Introduction

A useful Polymarket trading bot is not simply a Python loop that fetches a price and submits an order.

The difficult part is building the system around the order:

discovering a market that is actually tradable,
identifying the correct outcome token,
maintaining a current view of the order book,
converting a model signal into an executable order,
respecting market tick-size and minimum-size constraints,
controlling exposure,
handling partial fills and cancellations,
recovering from network failures,
and proving that the bot behaved correctly before allowing it to trade real capital.

Polymarket's current developer documentation exposes separate market-data, trading, account, and real-time workflows, while the official Python SDK provides PublicClient and SecureClient abstractions for those workflows.

This article builds the architecture behind a production-oriented Python bot rather than presenting a fictional "profitable strategy."

The strategy used in the examples is deliberately simple: buy an outcome only when a hypothetical model probability exceeds the executable market price by a configurable edge threshold. The edge is illustrative; it is not a claim that the strategy is profitable.

What You'll Learn

By the end of this guide, you will understand how to:

Choose the current Polymarket Python SDK.
Discover active markets.
Map a market to its outcome token IDs.
Read order-book information.
Build a signal engine.
Add position and exposure limits.
Construct and submit orders safely.
Separate strategy, risk, and execution.
Use WebSockets for real-time market information.
Handle retries, throttling, stale data, and partial fills.
Test a bot without immediately risking capital.
Monitor production behavior.
Extend the architecture toward market making, arbitrage research, or external-signal strategies.

1. Understand the Polymarket Developer Stack

A useful mental model is:

                    ┌─────────────────────┐
                    │   Market Discovery  │
                    │  Gamma / SDK data   │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │    Market Filter    │
                    │ tradable/liquidity  │
                    └──────────┬──────────┘
                               │
             ┌─────────────────┴─────────────────┐
             │                                   │
             ▼                                   ▼
    ┌─────────────────┐                 ┌─────────────────┐
    │ REST / snapshots│                 │    WebSocket    │
    │   market state  │                 │ live book data  │
    └────────┬────────┘                 └────────┬────────┘
             │                                   │
             └─────────────────┬─────────────────┘
                               ▼
                    ┌─────────────────────┐
                    │   Signal Engine     │
                    │ fair value / edge   │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │    Risk Engine      │
                    │ size / exposure /   │
                    │ stale-data checks   │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Execution Engine    │
                    │ sign / submit /     │
                    │ cancel / reconcile  │
                    └──────────┬──────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ Order / Position    │
                    │ State + Monitoring  │
                    └─────────────────────┘

Polymarket's current documentation describes trading as signed orders submitted to the CLOB, followed by matching and settlement on Polygon. The trading workflow is explicitly separated into account setup, outcome selection, order placement, and order management.

That separation should also exist in your code.

Do not put market discovery, strategy logic, signing, and risk management into one 300-line while True loop.

2. Which Python SDK Should You Use?

This is one of the most important current-version details.

The historical py-clob-client was widely used by Python bot tutorials, but the official repository was archived on May 25, 2026, and its README now says the client is no longer maintained and should not be used for new or existing integrations. Polymarket recommends migrating to the unified py-sdk.

The new official repository is:

Polymarket Python SDK — GitHub

It provides a unified Python interface for public data, authenticated accounts, trading, builder attribution, and wallet workflows. The package is currently beta and uses the package name polymarket-client.

The current SDK exposes:

from polymarket import PublicClient, SecureClient

PublicClient is appropriate for public market information, while SecureClient is used for authenticated account, trading, and wallet workflows.

The SDK currently requires Python 3.11 or newer according to its package metadata.

Install it with:

python -m venv .venv
source .venv/bin/activate

pip install --pre polymarket-client

For reproducible production deployments, pin the exact SDK version you have tested rather than floating to whatever beta release happens to be latest.

3. Project Structure

A practical project can start small:

polymarket-bot/
├── pyproject.toml
├── .env
├── .gitignore
├── src/
│   └── bot/
│       ├── __init__.py
│       ├── config.py
│       ├── market.py
│       ├── strategy.py
│       ├── risk.py
│       ├── execution.py
│       ├── state.py
│       └── main.py
└── tests/
    ├── test_strategy.py
    ├── test_risk.py
    └── test_execution.py

The key design principle is dependency direction:

Market Data ─────► Strategy
                      │
                      ▼
                    Risk
                      │
                      ▼
                  Execution
                      │
                      ▼
                    State

The strategy should not know how a private key is stored.

The execution layer should not decide whether a market is attractive.

The risk layer should be able to reject a perfectly valid strategy signal.

That separation makes testing dramatically easier.

4. Configuration and Secret Management

Never hard-code a private key.

Use environment variables:

export POLYMARKET_PRIVATE_KEY="0x..."
export POLYMARKET_DEPOSIT_WALLET="0x..."
export POLYMARKET_DRY_RUN="true"

For local development, a .env file can be convenient, but it must be excluded from Git:

.env
.venv/
__pycache__/
*.pyc

A configuration object keeps the rest of the application independent of the environment:

from dataclasses import dataclass
import os


@dataclass(frozen=True)
class Settings:
    private_key: str
    wallet: str
    dry_run: bool = True

    @classmethod
    def from_env(cls) -> "Settings":
        private_key = os.environ.get("POLYMARKET_PRIVATE_KEY")
        wallet = os.environ.get("POLYMARKET_DEPOSIT_WALLET")

        if not private_key:
            raise RuntimeError("POLYMARKET_PRIVATE_KEY is missing")

        if not wallet:
            raise RuntimeError("POLYMARKET_DEPOSIT_WALLET is missing")

        return cls(
            private_key=private_key,
            wallet=wallet,
            dry_run=os.environ.get(
                "POLYMARKET_DRY_RUN", "true"
            ).lower() == "true",
        )

For a real deployment, secrets should preferably come from a secret manager rather than a plaintext .env file.

5. Discover a Tradable Market

Market discovery is the first place where many beginner bots go wrong.

A market being visible does not automatically mean your strategy should trade it.

Your discovery pipeline should eventually filter for:

market status,
whether orders are being accepted,
outcome structure,
available token IDs,
minimum order size,
minimum price increment,
liquidity,
spread,
time to resolution,
and whatever additional constraints your strategy requires.

The official SDK supports market lookup by ID, slug, or Polymarket URL. It also provides market objects containing trading information such as minimum tick size and minimum order size.

A simple public-data example:

from polymarket import PublicClient


def find_markets() -> None:
    with PublicClient() as client:
        page = client.list_markets(page_size=10).first_page()

        for market in page.items:
            print(
                market.id,
                market.question,
                market.slug,
            )


if __name__ == "__main__":
    find_markets()

The important point is that market discovery should produce structured market objects, not arbitrary strings copied from a webpage.

6. Outcome Tokens Matter More Than the Market URL

Your trading engine ultimately needs an outcome token ID.

For a binary market, the current Polymarket documentation exposes the YES and NO outcome token IDs through the market object.

For example:

yes_token_id = market.outcomes.yes.token_id
no_token_id = market.outcomes.no.token_id

if yes_token_id is None or no_token_id is None:
    raise RuntimeError("Market has no tradable outcome token IDs")

This distinction is critical:

Market
  │
  ├── metadata
  ├── question
  ├── resolution information
  └── outcomes
        ├── YES token ID
        └── NO token ID

Do not confuse:

market ID,
event ID,
condition ID,
outcome token ID,
wallet address,
order ID.

They represent different things.

A robust internal model should make those distinctions explicit.

7. Read the Order Book

The market price alone is not enough for an execution engine.

Suppose your model says:

Fair probability = 0.63

That does not mean you can automatically buy at:

0.63

You need to know what liquidity is actually available.

The current SDK's public client exposes CLOB market data and order-book models, while Polymarket's WebSocket market channel can stream book snapshots and price changes.

Conceptually:

book = client.get_order_book(token_id)

best_bid = ...
best_ask = ...

Your strategy should work with a normalized representation:

from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True)
class Quote:
    best_bid: Decimal
    best_ask: Decimal
    timestamp: float

Then the strategy does not care whether that quote came from REST, WebSocket state, a replay file, or a test fixture.

8. The Simplest Useful Strategy Model

A good educational bot does not need a sophisticated prediction model.

Define:

model_probability = p_model
executable_price = p_market

edge = p_model - p_market

For a BUY strategy:

trade if edge > minimum_edge

For example:

from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True)
class Signal:
    side: str
    token_id: str
    price: Decimal
    size: Decimal
    edge: Decimal


def generate_signal(
    *,
    token_id: str,
    model_probability: Decimal,
    best_ask: Decimal,
    minimum_edge: Decimal,
    size: Decimal,
) -> Signal | None:

    edge = model_probability - best_ask

    if edge < minimum_edge:
        return None

    return Signal(
        side="BUY",
        token_id=token_id,
        price=best_ask,
        size=size,
        edge=edge,
    )

This is deliberately incomplete.

A production model would also consider:

spread,
depth,
expected slippage,
fees,
stale market data,
probability calibration,
model uncertainty,
time to resolution,
correlation with other positions,
adverse selection,
and execution probability.

The purpose is to demonstrate the architecture, not imply a profitable trading signal.

9. Why "Model Probability > Market Price" Is Not Enough

Suppose:

Model probability: 0.62
Best ask:          0.59

The apparent edge is:

0.62 - 0.59 = 0.03

That is not necessarily a 3-cent profit opportunity.

You still need to account for:

gross edge
- trading fees
- spread effects
- expected slippage
- model error
- execution uncertainty
- adverse selection
= expected net edge

Polymarket currently charges taker fees on certain markets. The official fee documentation says fees are determined per market at match time, makers are not charged fees, and the fee formula depends on the traded share price and market-specific fee rate.

That means a strategy should not use one universal hard-coded fee assumption.

A safer abstraction is:

expected_net_edge = (
    model_probability
    - executable_price
    - estimated_fee
    - estimated_slippage
)

Only then should the risk engine evaluate the trade.

10. Respect Tick Size and Minimum Order Size

One of the most common implementation errors is treating price and size as arbitrary decimals.

Polymarket's current order documentation states that price must follow the market's minimum price increment and size must satisfy the market's minimum order size.

The SDK's own examples obtain these values from the selected market:

price = market.trading.minimum_tick_size
size = market.trading.minimum_order_size

rather than assuming universal values.

A production strategy should therefore quantize its desired price.

For example:

from decimal import Decimal, ROUND_DOWN


def round_down_to_tick(
    price: Decimal,
    tick: Decimal,
) -> Decimal:
    units = (price / tick).to_integral_value(
        rounding=ROUND_DOWN
    )
    return units * tick

Then:

price = round_down_to_tick(
    desired_price,
    market.trading.minimum_tick_size,
)

You should perform the same kind of validation for size.

Do not discover an attractive signal and only afterward find that the proposed order violates the market's trading constraints.

11. Authentication With the Current Python SDK

The current unified SDK exposes SecureClient.create() for authenticated workflows.

The official SDK example uses:

from polymarket import SecureClient

client = SecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_DEPOSIT_WALLET"],
)

The SDK's implementation indicates that client creation derives or validates API credentials and establishes the authenticated transports required for secure CLOB operations.

A minimal setup looks like:

import os

from polymarket import SecureClient


def create_client() -> SecureClient:
    private_key = os.environ["POLYMARKET_PRIVATE_KEY"]
    wallet = os.environ["POLYMARKET_DEPOSIT_WALLET"]

    return SecureClient.create(
        private_key=private_key,
        wallet=wallet,
    )

Keep authentication isolated from strategy code.

12. Creating an Order Is Not the Same as Posting It

This distinction is extremely important.

The official Python SDK includes a create_limit_order() workflow that creates and signs an order locally. The SDK's example explicitly states that this does not submit the order. Actual trading requires a posting method such as place_limit_order() or post_order().

That separation is valuable for testing.

You can have:

Strategy
   ↓
Risk
   ↓
create_limit_order()
   ↓
Signed order

without immediately doing:

POST → live exchange

This gives you a natural dry-run boundary.

13. Example Limit Order Flow

The current SDK example follows this general pattern:

from polymarket import SecureClient


def build_order(
    client: SecureClient,
    token_id: str,
    price,
    size,
):
    return client.create_limit_order(
        token_id=token_id,
        price=price,
        size=size,
        side="BUY",
    )

The returned object is a signed order representation.

For actual execution, use the SDK's current posting method rather than assuming that signing automatically submits the order.

A production execution layer should therefore expose two distinct operations:

class ExecutionEngine:

    def prepare_order(self, signal):
        ...

    def submit_order(self, order):
        ...

That design makes dry-run testing much safer.

14. Dry-Run Mode

Before allowing a bot to submit real orders, implement:

DRY RUN

as a first-class execution mode.

Example:

class ExecutionEngine:

    def __init__(self, client, dry_run: bool):
        self.client = client
        self.dry_run = dry_run

    def execute(self, signal):
        order = self.client.create_limit_order(
            token_id=signal.token_id,
            price=signal.price,
            size=signal.size,
            side=signal.side,
        )

        if self.dry_run:
            print(
                "DRY RUN:",
                signal.side,
                signal.token_id,
                signal.price,
                signal.size,
            )
            return order

        return self.client.place_limit_order(
            token_id=signal.token_id,
            price=signal.price,
            size=signal.size,
            side=signal.side,
        )

The exact live-call signature should be pinned against the SDK version you deploy.

The important architectural property is that changing from simulation to execution should happen in one controlled location, not throughout the codebase.

15. WebSockets for Real-Time Market Data

Polling is easy to understand:

GET book
sleep
GET book
sleep
GET book

But a real-time trading system benefits from event-driven data.

Polymarket documents a WebSocket market channel at:

wss://ws-subscriptions-clob.polymarket.com/ws/market

The market channel can deliver events including full book snapshots, price changes, last trade prices, best bid/ask updates, tick-size changes, and market lifecycle events.

The documented channels also include user order/trade activity, sports data, and RTDS.

A sensible architecture is:

                  WebSocket
                      │
                      ▼
             ┌────────────────┐
             │ Local Book     │
             │ State          │
             └───────┬────────┘
                     │
                     ▼
              Signal Engine

The REST API can remain useful for:

initialization,
snapshots,
recovery,
account queries,
order management,
and reconciliation.

Do not make your strategy depend on one network stream being perfect forever.

16. Maintain Local State

A production bot should maintain explicit state.

For example:

from dataclasses import dataclass, field


@dataclass
class BotState:
    positions: dict[str, float] = field(default_factory=dict)
    open_orders: dict[str, dict] = field(default_factory=dict)
    last_market_update: dict[str, float] = field(default_factory=dict)
    realized_pnl: float = 0.0

When a WebSocket event arrives:

event
  ↓
validate
  ↓
update local state
  ↓
evaluate signal

When an order update arrives:

order event
  ↓
update order state
  ↓
update position state
  ↓
recalculate exposure

Do not assume:

submit order = position changed

Those are different states.

17. Risk Management Should Be a Separate Layer

A strategy generates an opinion.

Risk management decides whether that opinion is allowed to become an order.

For example:

from decimal import Decimal


def risk_allows(
    *,
    current_exposure: Decimal,
    proposed_notional: Decimal,
    max_exposure: Decimal,
) -> bool:
    return (
        current_exposure + proposed_notional
        <= max_exposure
    )

But real risk controls should go further.

Useful limits include:

Per-market exposure

maximum dollars/shares in one market

Global exposure

maximum portfolio exposure

Order-size limit

maximum size per individual order

Open-order limit

maximum number of outstanding orders

Loss guard

disable new entries after a configured loss threshold

Stale-data guard

do not trade if market data is older than X seconds

Duplicate-signal guard

do not repeatedly submit the same signal

Emergency kill switch

cancel orders
stop strategy
remain offline

The kill switch is not an optional feature.

18. A Better Decision Pipeline

Instead of:

if price < threshold:
    buy()

use:

Market Update
      │
      ▼
Is market tradable?
      │
      ▼
Is data fresh?
      │
      ▼
Is order book valid?
      │
      ▼
Calculate model fair value
      │
      ▼
Calculate executable edge
      │
      ▼
Estimate costs
      │
      ▼
Risk checks
      │
      ▼
Size order
      │
      ▼
Validate tick/size
      │
      ▼
Submit
      │
      ▼
Reconcile

This pipeline is the difference between a script and a trading system.

19. Handling Rate Limits

Polymarket documents API throttling across its Gamma, Data, CLOB, authentication, and trading APIs. The documented CLOB limits vary by endpoint, with separate burst and sustained limits for trading endpoints.

For example, the current documentation lists:

CLOB general requests: 9,000 requests / 10 seconds
/book: 1,500 / 10 seconds
/price: 1,500 / 10 seconds
POST /order: 3,500 / 10 seconds burst and 36,000 / 10 minutes sustained
DELETE /order: 3,000 / 10 seconds burst and 30,000 / 10 minutes sustained.

These are platform limits, not targets.

A good bot should use substantially less than its theoretical allowance.

Implement exponential backoff:

import random
import time


def retry_delay(attempt: int) -> float:
    base = min(2 ** attempt, 30)
    jitter = random.uniform(0, 0.25)
    return base + jitter

Then retry only errors that are actually safe to retry.

Do not blindly retry order submissions.

That can create duplicate orders if the first request succeeded but the response was lost.

20. The Most Dangerous Failure: Unknown Order State

Imagine:

Bot → POST order
       │
       ├── exchange accepts order
       │
       └── network connection dies

Your bot receives:

timeout

What happened?

You don't know.

The order might be:

rejected,
accepted and resting,
partially filled,
completely filled,
or cancelled elsewhere.

A naive retry could submit a second order.

The correct response is reconciliation.

POST
 │
 ├── response → record order ID
 │
 └── timeout
       │
       ▼
   reconcile
       │
       ▼
 query known order/account state

This is why order IDs and persistent state matter.

21. Limit Orders vs Market Orders

Polymarket currently documents both limit and market orders. A limit order specifies a price and can remain on the book, while a market order is intended to trade against available liquidity.

Use a limit order when:

price control matters,
you can tolerate waiting,
spread is important,
execution certainty is less important.

Use a market-style order when:

immediate execution matters,
the strategy has a sufficiently strong edge,
available liquidity has been evaluated,
and slippage is explicitly modeled.

Neither is universally superior.

For a bot, the real question is:

What execution behavior does the strategy require?

22. Time-in-Force and Stale Quotes

The current documentation supports GTC and GTD behavior for limit orders. GTD orders have documented expiration constraints, including a one-minute security threshold before their stated expiration and a minimum future expiration requirement.

This matters for automated trading.

Suppose your strategy wants:

Buy at 0.42

but the signal becomes invalid after 10 seconds.

A long-lived GTC order could remain exposed after the original thesis has disappeared.

Your execution policy therefore needs to answer:

How long is this quote valid?

That answer belongs to the strategy/execution contract.

23. Practical Example: A Complete Signal Pipeline

Here is a compact educational version:

from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True)
class MarketSnapshot:
    token_id: str
    best_ask: Decimal
    timestamp: float


@dataclass(frozen=True)
class Signal:
    token_id: str
    side: str
    price: Decimal
    size: Decimal
    edge: Decimal


class Strategy:
    def __init__(
        self,
        minimum_edge: Decimal,
        order_size: Decimal,
    ):
        self.minimum_edge = minimum_edge
        self.order_size = order_size

    def evaluate(
        self,
        snapshot: MarketSnapshot,
        model_probability: Decimal,
    ) -> Signal | None:

        edge = model_probability - snapshot.best_ask

        if edge < self.minimum_edge:
            return None

        return Signal(
            token_id=snapshot.token_id,
            side="BUY",
            price=snapshot.best_ask,
            size=self.order_size,
            edge=edge,
        )


class RiskManager:
    def __init__(self, max_exposure: Decimal):
        self.max_exposure = max_exposure

    def approve(
        self,
        current_exposure: Decimal,
        signal: Signal,
    ) -> bool:

        notional = signal.price * signal.size

        return (
            current_exposure + notional
            <= self.max_exposure
        )

Then the application becomes:

signal = strategy.evaluate(
    snapshot,
    model_probability,
)

if signal is None:
    return

if not risk.approve(
    current_exposure,
    signal,
):
    return

execution.execute(signal)

Notice what is missing:

strategy → client.place_order()

The strategy does not directly place orders.

That is intentional.

24. Production Architecture

A more serious system could look like:

flowchart TD
    A[Market Discovery] --> B[Market Registry]
    B --> C[WebSocket Market Feed]
    C --> D[Local Order Book]
    D --> E[Signal Engine]
    E --> F[Cost Model]
    F --> G[Risk Engine]
    G --> H[Execution Engine]
    H --> I[CLOB]
    I --> J[Order Events]
    J --> K[State Reconciliation]
    K --> L[Portfolio State]
    L --> G

    M[External Data] --> E
    N[Metrics] --> O[Monitoring]
    D --> N
    E --> N
    H --> N
    K --> N

This architecture has an important property:

the bot can recover state independently of the strategy.

If your strategy process crashes, you should still be able to determine:

which orders exist,
what positions exist,
what markets are being watched,
and whether the bot is safe to restart.

25. Performance Engineering

Performance should be measured rather than guessed.

Do not begin with:

"I need a 1 ms bot."

Begin with:

Where does time actually go?

Measure:

market event received
       ↓
event parsed
       ↓
local book updated
       ↓
signal generated
       ↓
risk check
       ↓
order signed
       ↓
request sent
       ↓
exchange response

Record timestamps for each stage.

Then calculate:

feed → signal latency
signal → submit latency
submit → acknowledgement latency

The WebSocket market channel is appropriate for reducing dependence on repeated REST polling, but it does not eliminate network, processing, or exchange-side latency. Polymarket's documentation describes the channel as near-real-time rather than promising a fixed end-to-end latency.

Avoid optimizing prematurely.

For most early bots, the biggest performance gains come from:

avoiding unnecessary polling,
keeping connections alive,
reducing redundant API calls,
maintaining local state,
eliminating blocking work from the hot path,
and measuring the actual critical path.

26. Don't Put Logging on the Hot Path

This is easy to overlook.

Avoid doing expensive operations such as:

json.dumps(huge_object)
database.commit()
print(large_book)

for every market update.

Instead:

Market feed
    │
    ├──► hot strategy path
    │
    └──► async logging/metrics pipeline

A lightweight queue works well:

from queue import SimpleQueue

metrics_queue = SimpleQueue()


def record_metric(event):
    metrics_queue.put(event)

A separate worker can batch and persist metrics.

27. Security

A trading bot has two major security surfaces:

Credentials

Protect:

private keys,
API credentials,
builder credentials,
wallet information.

Trading authority

Even if a private key never leaks, a software bug can still lose money.

Therefore:

enforce maximum order size,
enforce maximum exposure,
validate token IDs,
validate market state,
reject impossible prices,
reject stale data,
implement a kill switch,
separate dry-run from live mode,
restrict production credentials,
and audit every order.

Never log:

PRIVATE_KEY
API_SECRET
seed phrase
signed credential material

Be careful with exceptions as well.

An exception object can contain request information or serialized credentials if a poorly designed dependency includes them.

28. Testing Strategy

Do not begin testing with real money.

A useful testing pyramid is:

                 ┌───────────────┐
                 │ Live / tiny   │
                 │ controlled    │
                 └───────┬───────┘
                         │
                 ┌───────┴───────┐
                 │ Integration   │
                 └───────┬───────┘
                         │
                 ┌───────┴───────┐
                 │ Replay tests  │
                 └───────┬───────┘
                         │
                 ┌───────┴───────┐
                 │ Unit tests    │
                 └───────────────┘

Unit tests

Test:

probability calculations,
edge calculations,
price rounding,
position limits,
order sizing,
stale-data checks.

Example:

def test_signal_requires_minimum_edge():
    signal = strategy.evaluate(
        snapshot,
        model_probability=Decimal("0.51"),
    )

    assert signal is None

Replay tests

Save real market-data events and replay them through the strategy.

This is much more useful than testing only synthetic values.

Integration tests

Test:

authentication,
market discovery,
order construction,
cancellation,
reconciliation.

The official Python SDK repository itself distinguishes integration tests from metered tests and warns that tests which place orders, spend funds, or mutate live state require explicit opt-in.

That is a good pattern to copy.

29. Backtesting Prediction-Market Strategies

Traditional OHLC backtesting is often insufficient.

A prediction-market backtest should model:

timestamp
token
bid levels
ask levels
trade events
available depth
your order size
execution assumption
fees
position
resolution

If you only backtest against:

last_price

you can dramatically overestimate execution quality.

A better simulator asks:

If my bot submitted this order at this timestamp, how much of it could realistically have filled?

For market-making strategies, you also need queue-position assumptions.

For taker strategies, you need depth-aware slippage.

30. Monitoring and Observability

A production bot should expose metrics such as:

Market-data metrics

websocket_connected
book_update_age
messages_per_second
reconnect_count

Strategy metrics

signals_generated
signals_rejected
edge_distribution

Execution metrics

orders_submitted
orders_rejected
orders_filled
partial_fills
cancel_count

Risk metrics

current_exposure
maximum_exposure
open_orders

System metrics

process_uptime
CPU
memory
network errors
API errors

You should also log structured events:

{
  "event": "order_submitted",
  "token_id": "...",
  "side": "BUY",
  "price": "0.52",
  "size": "10",
  "strategy": "probability_edge",
  "dry_run": true
}

Never assume your logs are only for debugging.

They become your trading audit trail.

31. Failure Modes You Should Expect

1. Stale market data

Problem: The strategy acts on an old book.

Fix: Attach timestamps to market state and reject stale data.

2. Duplicate orders

Problem: A timeout is interpreted as failure and the bot submits again.

Fix: Reconcile order state before retrying an uncertain submission.

3. Invalid price precision

Problem: Strategy generates a price that violates tick size.

Fix: Quantize against the market's current minimum tick size.

4. Invalid order size

Problem: Size is below the market minimum.

Fix: Validate before signing.

5. Assuming every market has the same fee

Problem: Cost model is wrong.

Fix: Read current market fee configuration where applicable. Polymarket says fees are determined per market at match time.

6. Using an obsolete SDK

Problem: Tutorials tell you to build everything around py-clob-client.

Fix: Check the current official SDK first. The historical repository is archived, and Polymarket now recommends the unified Python SDK.

7. Treating order creation as submission

Problem: Bot believes an order was sent when it only created a signed object.

Fix: Keep create and place/post operations separate.

8. Polling everything

Problem: Unnecessary API traffic and stale snapshots.

Fix: Use the real-time market channel where appropriate and reserve REST for snapshots, recovery, account state, and execution workflows.

32. Advanced Improvement: External Signal Feeds

A stronger strategy architecture can consume external information:

External Feed
     │
     ▼
Feature Engineering
     │
     ▼
Probability Model
     │
     ▼
Polymarket Market
     │
     ▼
Execution

Examples could include:

financial prices,
weather data,
sports data,
economic releases,
news/event data.

The key is not simply receiving another feed.

The model must answer:

What probability does this information imply?

Then compare it against an executable Polymarket price.

33. Advanced Improvement: Market Making

A market-making bot changes the objective.

Instead of:

"I think YES is underpriced."

you might estimate:

fair_value
inventory
spread
adverse_selection_risk

Then quote:

bid = fair_value - spread
ask = fair_value + spread

while controlling inventory.

The strategy becomes:

Fair value
    │
    ├──► Bid quote
    │
    └──► Ask quote

Polymarket currently documents market-making and maker-rebate programs separately, and the current fee documentation states that makers are not charged the applicable taker fee.

That does not mean market making is automatically profitable. Inventory risk, adverse selection, stale quotes, and execution costs remain.

34. Advanced Improvement: Event-Driven State Machines

For more complex bots, model orders as explicit states:

CREATED
   │
   ▼
SIGNED
   │
   ▼
SUBMITTED
   │
   ├───────────────┐
   ▼               ▼
OPEN            REJECTED
   │
   ├───────┐
   ▼       ▼
PARTIAL   CANCELLED
   │
   ▼
FILLED

This is much safer than scattered booleans such as:

order_sent = True
order_filled = False

A state machine makes impossible transitions easier to detect.

35. Advanced Improvement: Reconciliation Loop

Even with WebSockets, periodically reconcile your local state against authoritative API data.

For example:

Continuous WebSocket state
           │
           ▼
      Local state
           │
           │
     periodic check
           ▼
     REST/API state
           │
           ▼
      reconciliation

If:

local_open_orders != remote_open_orders

stop new trading until the discrepancy is understood.

A trading bot should fail closed, not fail open.

36. A Practical Production Loop

Putting the components together:

def run_cycle(
    market,
    snapshot,
    model_probability,
    state,
    strategy,
    risk,
    execution,
):
    if snapshot is None:
        return

    if snapshot.is_stale():
        return

    signal = strategy.evaluate(
        snapshot=snapshot,
        model_probability=model_probability,
    )

    if signal is None:
        return

    if not risk.approve(
        current_exposure=state.current_exposure,
        signal=signal,
    ):
        return

    execution.execute(signal)

This looks almost boring.

That is a good sign.

Production trading infrastructure should be boring at the boundaries.

The complexity belongs inside well-defined components, not in unpredictable interactions between them.

37. Current Polymarket API Details Worth Keeping in Mind

As of the documentation checked for this article:

Polymarket provides a unified official Python SDK named polymarket-client.
The SDK is currently beta.
The historical py-clob-client repository is archived and its README recommends migration.
The official Python SDK exposes PublicClient, AsyncPublicClient, SecureClient, and AsyncSecureClient.
Polymarket provides WebSocket channels for market and user activity.
Current trading documentation supports limit and market orders.
Limit orders must respect the market's tick size and minimum order size.
Fees are market-dependent and applied at match time where enabled.
API throttling applies across the platform and trading endpoints have their own burst/sustained limits.

These details can change.

For a production bot, treat the official documentation as part of your deployment dependency.

Frequently Asked Questions

What is a Polymarket trading bot?

A Polymarket trading bot is software that automatically consumes market information, evaluates a trading rule or model, manages risk, and submits or manages orders through Polymarket's developer interfaces.

A useful bot is an execution system, not merely a price scraper.

Can I build a Polymarket trading bot with Python?

Yes. Polymarket currently maintains an official Python SDK, polymarket-client, which provides public and authenticated client workflows. The SDK is currently beta.

Is `py-clob-client` still the recommended Python SDK?

No. The historical py-clob-client repository was archived in May 2026, and its README says it is no longer maintained and recommends migrating to the unified SDK.

Does a trading bot guarantee profit?

No.

Automation changes execution and consistency; it does not create an economic edge.

A strategy can lose money because of:

incorrect probabilities,
spread,
fees,
slippage,
adverse selection,
low liquidity,
execution failures,
and changing market conditions.

Should I use REST or WebSockets?

Use them for different jobs.

WebSockets are well suited to continuously changing market information. REST remains useful for snapshots, recovery, account information, and trading operations. Polymarket documents both real-time WebSocket channels and REST-based APIs.

How much money do I need to start?

There is no universally correct amount.

Start with an amount whose complete loss would be acceptable to you, and prioritize dry-run, replay, and integration testing before live trading.

Should I start with market making or directional trading?

For a first bot, directional probability-based execution is usually easier to reason about.

Market making introduces additional problems such as inventory management, adverse selection, quote cancellation, and execution quality.

Can I run the bot on a VPS?

Yes, provided the deployment satisfies your operational and security requirements.

The important properties are stable networking, secret protection, process supervision, logging, monitoring, and a recovery strategy—not simply choosing a particular hosting provider.

Conclusion

Building a Polymarket trading bot in Python is fundamentally an engineering problem before it is a strategy problem.

The minimum useful architecture is:

Market Discovery
      ↓
Market Data
      ↓
Signal
      ↓
Cost Model
      ↓
Risk
      ↓
Execution
      ↓
Reconciliation
      ↓
Monitoring

The most important implementation lessons are:

Use the current official SDK rather than copying an obsolete tutorial.
Separate market discovery from execution.
Trade outcome token IDs, not URLs or arbitrary market identifiers.
Respect tick-size and minimum-order constraints.
Model executable prices rather than theoretical prices.
Account for fees, spread, slippage, and adverse selection.
Use WebSockets for appropriate real-time market workflows.
Treat uncertain order submissions as reconciliation problems.
Build dry-run and replay testing before live execution.
Put hard risk limits between every strategy signal and the exchange.
Monitor the bot as an operational system.
Re-check Polymarket's documentation whenever the platform or SDK changes.

The strategy is replaceable.

The infrastructure is what lets you safely test increasingly sophisticated strategies.

Trading-risk disclaimer: This article is educational and technical, not financial advice. Automated prediction-market trading can result in partial or total loss of capital. No strategy described here is guaranteed to be profitable. Validate strategies with historical/replay data and controlled testing before risking meaningful capital.

1. How to Read Polymarket Order Books With Python

Suggested anchor: read Polymarket order books with Python

Why link it: This is the natural next step after market discovery and introduces depth, spread, liquidity, and executable pricing.

2. Polymarket WebSocket API: Build a Real-Time Market Data Feed

Suggested anchor: Polymarket WebSocket market data

Why link it: Readers who understand REST-based polling can move toward event-driven market-data architecture.

3. Polymarket Order Execution in Python

Suggested anchor: Polymarket order execution in Python

Why link it: Deepens the execution section with signing, posting, cancellation, order lifecycle, and reconciliation.

4. How to Build a Polymarket Market-Making Bot

Suggested anchor: build a Polymarket market-making bot

Why link it: Creates a strategy-level progression from directional execution to liquidity provision.

5. Polymarket Trading Bot Risk Management

Suggested anchor: Polymarket bot risk management

Why link it: Expands the most important production layer: exposure, sizing, kill switches, stale-data protection, and portfolio limits.

6. How to Backtest Polymarket Trading Strategies

Suggested anchor: backtest Polymarket trading strategies

Why link it: Connects live bot architecture to historical simulation and execution-aware research.

7. Polymarket API Authentication With Python

Suggested anchor: Polymarket API authentication

Why link it: Gives readers a dedicated security and credential-management tutorial.

8. Polymarket Bot Monitoring and Observability

Suggested anchor: monitor a Polymarket trading bot

Why link it: Extends the production section into metrics, alerting, state reconciliation, and operational reliability.

Useful Resources

Official Polymarket

Polymarket

Use this for the live product, markets, account interface, and market context.

Official Polymarket Documentation

Polymarket Documentation

This should be the primary technical reference for API behavior, trading workflows, market data, authentication, fees, and SDK changes.

Market Discovery

Polymarket Market Discovery Documentation

Useful for understanding how to discover and filter markets before trading.

Python SDK

Official Polymarket Python SDK

The current unified Python SDK for Polymarket integrations. It is currently beta.

WebSocket Market Data

Polymarket WebSocket Overview

Useful when moving from REST polling to real-time market-data processing.

Relevant DEV.to Resource

Building a Low-Latency Polymarket Trading Bot in Python — DEV.to

Useful for discussing engineering considerations around WebSockets and execution architecture. Its latency measurements are author-specific and should not be treated as Polymarket guarantees.

Relevant YouTube Tutorial

Useful as a practical visual walkthrough for developers who prefer seeing a complete bot assembled end-to-end. It is supplementary to the official documentation.

Official Polymarket X

Polymarket on X

Use official social channels for product announcements, but verify technical claims against the documentation.

Polymarket Developer Resources

Polymarket GitHub Organization

The official GitHub organization is useful for tracking SDKs, developer tooling, and other open-source components.

About the Author

[Bo$onaX]

I write about Polymarket trading bots, prediction-market infrastructure, algorithmic trading, Python automation, Web3 development, and quantitative strategies.

Contact:
X: [https://x.com/@xxniiinxx]
Telegram: [https://t.me/bosonax]

How to Build a Polymarket Trading Bot (After 50 ms Taker Delay Edition)

Bo$onaX — Mon, 17 Aug 2026 23:02:28 +0000

Overview

Polymarket has steadily tightened the latency environment on crypto markets. The original 500 ms taker delay was removed in February 2026. A residual 250 ms delay remained for a while, and on August 17, 2026 at 11:00 AM UTC that delay was cut to 50 ms.

This change further reduces the protective buffer market makers previously enjoyed when cancelling stale quotes. Combined with dynamic taker fees, maker rebates, and the move to Chainlink TWAP resolution on short-duration crypto markets, the meta continues to favor fast, fee-aware makers over pure taker latency-arbitrage bots.

The new reality: if you cannot cancel/replace in well under 100 ms end-to-end (ideally closer to 50–70 ms), your resting orders will be adversely selected more often.

What Changed (Recent Timeline)

500 ms taker delay removed (Feb 18, 2026)

Instant matching for takers; makers lost the half-second window to pull quotes.
250 ms residual taker delay + lock-in behavior (June 2026)

Once a taker order entered the delay window it became non-cancellable until the delay expired.
Taker delay reduced to 50 ms (August 17, 2026, 11:00 AM UTC)

Official announcement from @PolymarketDevs. Crypto markets now execute taker fills after only a 50 ms delay. Liquidity and market quality will be monitored and may be adjusted further.
Dynamic taker fees + maker rebates (ongoing since early 2026, refined in CLOB V2)

Current crypto formula (approx.):

   fee = C × 0.07 × p × (1 − p)

Peak ~$1.75 per 100 shares at 50 ¢. Makers pay zero fees and receive ~20 % of collected taker fees as daily USDC rebates (fee-curve weighted).

TWAP resolution on 5-min / 15-min / 4-hour crypto markets (August 2026)

Settlement uses Chainlink time-weighted average price (currently 60 s lookback on 5-min markets). Last-second single-tick sniping is largely dead; bots must model the averaging window.
CLOB V2 (April 2026)

feeRateBps removed from the signed order payload — fees are applied at match time. Order structure simplified.

The New Meta: Still Be a Maker (but even faster)

Zero fees + daily rebates remain the cleanest edge.
50 ms taker delay means the adverse-selection window is now tiny. Your cancel/replace loop must be extremely tight.
Colocation (Amsterdam region is known to be closest to the CLOB) + WebSocket + low-level language (Rust preferred) is close to mandatory for competitive market-making.
Taker strategies only work if you have a genuine information edge larger than the fee curve + the residual 50 ms risk.

How to Build a Compliant Bot (August 2026 Architecture)

Core Requirements

Real-time WebSocket order-book and user-channel streams (REST is too slow).
End-to-end cancel → replace cycle target: < 70–80 ms (ideally under the new 50 ms delay).
Fee-aware position sizing and edge calculation (use the current 0.07 rate curve).
TWAP-aware signal generation for short crypto markets.
Proper approvals, private-key management, and rate-limit awareness (volume-based tiers now live).

Step-by-Step Setup

Private key & approvals

Same as before: export your EOA private key and approve the exchange contracts for USDC / conditional tokens (one-time).
Client choice
- Official: py-clob-client or TypeScript / Rust SDKs (now stable).
- Performance: polyfill-rs, official Rust SDK, or a full HFT framework. Prefer the lowest-latency stack you can reliably maintain.
Connect via WebSocket

Subscribe to market channels for order-book depth and the user channel for fills/cancels. Do not poll REST for critical path logic.
Order construction (post-CLOB V2)

Fees are no longer part of the signed payload. Sign and post clean limit orders. Query any remaining market-specific parameters if needed, but the old feeRateBps field is gone.
Maker quoting on both sides

Post resting limit orders on YES and NO (or the relevant outcomes). Aim to earn rebates while keeping inventory under control.
Ultra-fast cancel/replace loop
- Monitor external price feed (Binance / Chainlink TWAP streams) + Polymarket book.
- On any meaningful move: cancel → immediately replace.
- With only 50 ms of taker delay left, any cycle longer than ~80–100 ms will get picked off regularly.
- Colocate in Amsterdam if possible; residential or distant VPS is no longer viable for serious market-making.

Example Strategy Adjustments for 5-Minute BTC Markets (post-TWAP)

Markets resolve on a 60-second Chainlink TWAP.
Deterministic direction is still often visible well before close, but you now model the average over the lookback window rather than a single last tick.
Near the end of the window (T-10 to T-5 s):
- Compute expected TWAP direction from live feeds.
- Post aggressive maker orders on the winning side (e.g., 90–95 ¢) only if your modeled edge exceeds fees + residual latency risk.
Continue earning maker rebates on any resting volume throughout the market.

Common Mistakes That Still Kill Bots

Relying on REST polling.
Cancel/replace loops slower than ~80 ms.
Ignoring the current fee curve when calculating edge.
Running from high-latency locations.
Treating the market as single-tick settlement (it is now TWAP).
Not merging YES/NO positions or managing inventory.
Attempting pure taker arb without a large enough edge after fees.

Using AI Correctly

Do not ask an LLM “build me a Polymarket bot.” It will regurgitate outdated 2025/early-2026 code.

Instead give it the current constraints:

“Write a maker bot for Polymarket 5-minute BTC markets using the official Rust/Python CLOB client. Use WebSocket order-book + Binance/Chainlink TWAP feeds. Target full cancel/replace under 70 ms. Fees are applied at match time (0.07 × p × (1-p) curve). Post maker quotes on both sides, skew inventory, and respect the 50 ms taker delay environment.”

Always back-test against the live fee curve and the current TWAP window.

Key Takeaway

The bots that win in late 2026 are still the best liquidity providers — just faster ones.

The reduction from 250 ms → 50 ms taker delay removes almost the last meaningful protective buffer. Speed, fee awareness, TWAP modeling, and disciplined risk controls are now non-negotiable.

Build maker bots. Stay under 70 ms. Earn the rebates. Monitor the official @PolymarketDevs channel for further adjustments.

Support team links

Telegram: https://t.me/bosonax
X: https://x.com/xxniiinxx
Polymarket: https://polymarket.com/@bosona

Useful links

Official announcement: https://x.com/PolymarketDevs/status/2089295325660172578
Docs: https://docs.polymarket.com/
Fees: https://docs.polymarket.com/trading/fees
Maker Rebates: https://docs.polymarket.com/market-makers/maker-rebates

rust #python #polymarket #trading #bot #arbitrage #copytrading #marketmaker #polymarkettradingbot #polymarketcopytradingbot #polymarketbot #tradingbot #copytradingbot #arbitragebot

Is Price Action Analysis The Same As Technical Analysis in Polymarket Crypto Up/Down Markets?

Bo$onaX — Fri, 14 Aug 2026 14:53:41 +0000

Is Price Action Analysis the Same as Technical Analysis in Polymarket Crypto Up/Down Markets?

Why pure price action outperforms indicator-heavy technical analysis for short-term binary crypto prediction markets

Is price action analysis the same as technical analysis when trading Polymarket’s Crypto Up/Down markets? The answer is “yes and no.”

Technical analysis is generally defined as a methodology for forecasting the direction of prices through the study of past market data, primarily price and volume. On Polymarket, this definition applies directly to binary Crypto Up/Down markets (e.g., “Will Bitcoin be higher or lower at the end of the hour/day?”), where the sole goal is predicting short-term directional moves in assets like BTC, ETH, or others.

However, technical analysis as commonly practiced often includes a wide array of “technical studies”—indicators, oscillators, and complex patterns—anything that isn’t pure fundamental or news-driven data.

Are all of these technical studies, such as RSI, MACD, Stochastic, or elaborate chart pattern overlays, really necessary or effective for Polymarket Crypto Up/Down trading? Why do some traders become convinced that loading charts with indicators is the path to consistent wins on these binary markets, while others rely solely on raw price action? Here’s a clear breakdown tailored to these short-term prediction markets.

Why All Technical Analysis Methods Are Not Created Equal for Crypto Up/Down Markets

While technical analysis has its place, pure price action traders who focus on reading the raw movement of crypto prices do not subscribe to the idea that “any technical study is a good study.” Instead, the focus stays on a handful of simple, effective price-based principles. There is no need to force what appears on a Bitcoin or Ethereum chart into matching textbook indicator setups or multi-indicator confluence systems that many popular trading approaches promote.

Crypto Up/Down markets on Polymarket resolve based on a specific price at a fixed time (hourly, daily, etc.). Relying heavily on lagging indicators or secondary technical tools that largely ignore the actual price action of the underlying crypto often leads to overcomplication and long-term underperformance. These markets move fast, and hindsight-fitted indicator systems frequently fail in live conditions.

Many common technical analysis tools introduce what can be called “noise.” Indicators such as RSI, Stochastic, MACD, Bollinger Bands, and countless others are simply mathematical derivatives of price. If the goal is to predict whether Bitcoin will finish higher or lower in the next hour or day, analyzing a derivative of price adds unnecessary variables. Why not read the raw price action of the crypto itself?

Adding these extra layers clutters the charts, the decision-making process, and the mind. For Polymarket Crypto Up/Down trading, this is especially counterproductive. All that is needed to form a directional view is the raw, natural price data that any crypto market supplies for free. There is no requirement for complex “systems” or indicator packs—raw price action is sufficient.

Why Price Action Analysis Is the Best Technical Analysis Method for Polymarket Crypto Up/Down Markets

After filtering the noise common in technical analysis resources, what remains effective and logical for these binary markets is pure price action: the movement of price on a clean, indicator-free chart of the underlying cryptocurrency.

In this context, price action means focusing exclusively on the raw candlestick chart of BTC, ETH, or the relevant crypto. Key elements include watching levels of support and resistance, identifying the short-term market bias and trend, and observing how price is behaving relative to the timeframe of the Polymarket contract (e.g., the next hour or the daily close). This is done by visually reading the chart rather than relying on third-party indicators or secondary studies.

A practical approach uses specific price bar patterns or candlestick signals for timing entries into the “Up” or “Down” side of a Polymarket market. First map the market using price action, then wait patiently for a confluence of factors to align before committing capital.

A Simple and Effective Confluence Framework: T.L.S.

A straightforward framework for Crypto Up/Down markets is T.L.S.—Trend, Level, Signal:

Trend: Is the short-term direction of the crypto clearly bullish or bearish on the relevant timeframe?
Level: Is price interacting with a clear support or resistance level that has previously influenced price?
Signal: Is there a clear price action signal (such as a strong rejection candle, pin bar, or engulfing pattern) forming at that level in the direction of the bias?

Look for at least two of these three factors to align. For example, an uptrend + a bounce from a key support level + a bullish rejection candle can create a higher-probability setup to buy the “Up” side of a Polymarket Crypto market. The same logic applies in reverse for “Down” opportunities. When multiple factors line up near the resolution window of the market, the odds improve.

Keep It Simple

Technical analysis for Polymarket Crypto Up/Down markets does not need to be more complicated than identifying the dominant short-term trend, marking key chart levels, and waiting for clear price action signals. Anyone claiming otherwise is usually either selling complexity or overcomplicating a process that works best when kept simple.

Price action remains the cleanest and most direct form of technical analysis for these markets. Strip away the indicators, read the raw crypto price movement, and trade the confluence.

I Built a Live Trading Bot in Python. Here's What Actually Works (Polymarket TWAP Edition).

Bo$onaX — Thu, 13 Aug 2026 15:24:03 +0000

Build a Python trading bot with Claude AI, Polymarket CLOB integration, and live Polymarket TWAP (Chainlink) signals. Paper trading to production in one guide.

TL;DR

I built a production algorithmic trading system using Python, Claude Code for development, Polymarket’s CLOB API for execution, and Polymarket’s Real-Time Data Streaming (RTDS) Chainlink TWAP feeds for signals. This guide covers the full architecture: signal generation from 30s/60s TWAP updates, position management, exit strategies, and the paper-to-live progression that prevented costly mistakes.

Key takeaways

01 A production trading bot needs five core modules: signal generation, position execution, exit management, state persistence, and health monitoring

02 Claude Code wrote 95% of the 4,000-line codebase autonomously, including the asyncio event loop, database layer, and deployment scripts

03 Paper trading with at least 30 signals before going live prevented two strategy failures that would have cost real money

04 The biggest technical challenge was not the trading logic but state recovery after process restarts

05 Polymarket’s CLOB API requires careful order book analysis because liquidity varies dramatically between markets — and TWAP-resolved markets demand even tighter depth checks around resolution windows

Why this matters

I built a production algorithmic trading system using Python, Claude Code for development, Polymarket’s CLOB API for execution, and Polymarket’s public RTDS WebSocket for live Chainlink TWAP price updates (30-second and 60-second windows). This guide covers the full architecture: signal generation from TWAP streams, position management, exit strategies, and the paper-to-live progression that prevented costly mistakes.

A production Python trading bot needs five core modules to run continuously without losing state: signal generation, position management, exit strategies, state persistence, and health monitoring. I built this system using Python and Claude Code across a 4,000-line codebase, with Polymarket RTDS Chainlink TWAP feeds for signals and the CLOB for execution. Paper trading at least 30 signals over 6 weeks before going live prevented two strategy failures — a liquidity trap near TWAP settlement windows and a signal-timing issue during low-liquidity hours — that would have cost real money.

System Architecture Overview

When I started building a trading bot, I expected the hard part to be the trading logic. It wasn’t. The hard part was building a system that could run continuously for weeks without losing state, crashing silently, or entering impossible positions — especially once Polymarket switched crypto up/down markets to TWAP-based resolution (5-minute markets on 30s TWAP, 15-minute and 4-hour markets on 60s TWAP).

A production trading bot needs five core modules that work together:

Signal Generation — Monitors live Chainlink TWAP updates via Polymarket RTDS and generates trade signals
Position Management — Executes trades, tracks holdings, and prevents overlapping positions
Exit Strategies — Knows when to close positions and takes profits or cuts losses
State Persistence — Survives process crashes, power failures, and restarts
Health Monitoring — Detects stuck orders, orphaned positions, and API failures

Each module can fail independently, so the system needs to handle partial failures gracefully. A TWAP signal can fail without crashing position management. An API call can timeout without losing the position state. The monitoring system watches everything and alerts when something goes wrong.

The entire codebase is about 4,000 lines of Python. Claude Code wrote 95% of it, including the most complex parts: the asyncio event loop, the database schema and queries, and the deployment scripts.

Note: The repo is private for now, but I'm planning to open source the core trading logic once it's hardened further.

How Does Signal Generation Work?

Signals are the input to the entire system. My signals come from Polymarket’s RTDS Chainlink TWAP feeds (no Chainlink credentials required).

Polymarket RTDS delivers real-time 30-second and 60-second Chainlink TWAP updates over a public WebSocket. I subscribe to topics such as crypto_prices_twap_thirty and crypto_prices_twap_sixty for pairs like btc/usd, eth/usd, etc. I watch consecutive TWAP prints and detect momentum breakouts when the latest TWAP moves more than 2-sigma relative to the recent window of TWAP values. When a TWAP breakout occurs, I look for corresponding Polymarket up/down prediction markets that are still underpriced relative to the new TWAP trajectory.

The key insight is that prediction-market prices still lag the official TWAP updates by 15–60 seconds in many cases, creating a small window to position ahead of the eventual resolution source.

The TWAP Momentum Window

Here’s how the signal generation actually works in code (using the official polymarket-client):

from polymarket import AsyncPublicClient
from polymarket.streams import CryptoPricesChainlinkTwapSpec
import asyncio
from collections import deque

async def detect_twap_breakout(twap_history: deque, current_twap: float) -> float | None:
    """
    Watch recent Chainlink TWAP values (30s or 60s window) and detect 2-sigma breakouts.
    Returns signal strength (0-1) if breakout detected.
    """
    if len(twap_history) < 20:
        return None

    values = list(twap_history)
    mean = sum(values) / len(values)
    variance = sum((x - mean) ** 2 for x in values) / len(values)
    std_dev = variance ** 0.5

    if std_dev == 0:
        return None

    z_score = (current_twap - mean) / std_dev

    if z_score > 2.0:  # Upside breakout on TWAP
        return min(1.0, z_score / 3.0)  # Cap at 3-sigma
    return None

# Example subscription loop
async def stream_twap_signals():
    history = deque(maxlen=20)
    async with AsyncPublicClient() as client:
        async with await client.subscribe(
            CryptoPricesChainlinkTwapSpec(window_seconds=30, symbols=["btc/usd"])
        ) as stream:
            async for event in stream:
                twap = float(event.payload.value)
                history.append(twap)
                strength = await detect_twap_breakout(history, twap)
                if strength:
                    # Emit signal to position manager queue
                    await signal_queue.put({
                        "symbol": event.payload.symbol,
                        "twap": twap,
                        "window_s": event.payload.window_seconds,
                        "strength": strength,
                        "ts": event.payload.timestamp
                    })

When a signal fires, the system calculates how many standard deviations the latest TWAP has moved above the recent mean of TWAP prints. A 2-sigma TWAP move is rare; when it lines up with an underpriced Polymarket market that resolves on the same TWAP feed, the edge becomes real.

The efficiency gap exists because:

Official Chainlink TWAP updates arrive via RTDS (fast and authoritative)
Retail prediction-market traders react more slowly to the new TWAP level
Markets that resolve on the exact same 30s/60s TWAP still show temporary mispricing in the order book

This isn’t an edge that lasts forever. As more bots subscribe to the same public RTDS feed, the 15–60 second window compresses. But for now, it’s consistent enough to trade.

Signals feed into a queue. The position manager processes signals one at a time, ensuring we never accidentally open two positions on the same market.

How Does Position Management Work?

Once a TWAP signal arrives, the position manager decides: do we take this trade, or skip it?

The decision logic checks:

Do we already have a position in this market? If yes, skip.
Is the order book deep enough to execute at reasonable prices? If no, skip.
Has this market been active for more than 24 hours? Recent markets are illiquid.
Are we at our maximum concurrent positions? If yes, skip.
Is the market’s resolution window (5m / 15m / 4h) still far enough from the TWAP settlement window that we have room to exit?

If all checks pass, the position manager places a limit order on the Polymarket CLOB. The CLOB is Polymarket’s central limit order book. It’s lower latency than the REST API but requires understanding the order book structure — especially critical now that resolution is driven by the same TWAP feeds we are monitoring.

The position manager tracks every open position in SQLite. Each position stores:

Market ID and outcome tokens
Entry price and quantity
Timestamp and signal strength (from TWAP z-score)
Current mark-to-market value
Status (open, closing, closed)
Linked TWAP window (30s or 60s) and symbol

This database survives process restarts. On startup, the position manager reads the database and reconstructs the exact state it was in before the crash.

What Exit Strategies Actually Work?

The hardest part of algorithmic trading is exits. Most retail traders focus on entries but skip profitable or know when to close positions. It’s the difference between “cool idea” and “actual profit.”

I use three exit types:

Profit target — Close 50% of position at 2% profit, rest at 5% profit
Stop loss — Close entire position if it drops 3% below entry
Time decay / TWAP proximity — If a position hasn’t moved in 4 hours, or if the market is approaching its TWAP resolution window with no edge left, close it (markets that aren’t moving are wasting capital)

The exit manager runs every minute, checks all open positions against the latest RTDS TWAP and market mid, and executes exits that meet criteria. It places exit orders as limit orders too, so we get the best available prices.

The Math on Asymmetric Position Sizing

Here’s why the split profit target works. Say I enter a position at $0.45 on a binary market with $100 per trade:

Winning trades (55% of the time):

Exit 50% at $0.459 (2% profit): +$0.90
Exit remaining 50% at $0.4725 (5% profit): +$2.25
Total on winner: +$3.15 (3.15% return on $100)

Losing trades (45% of the time):

Stop loss hits at $0.4365 (3% below entry): -$3.00
Total on loser: -$3.00 (-3% return on $100)

Expected value calculation:

EV = (0.55 × $3.15) + (0.45 × -$3.00)
EV = $1.73 + (-$1.35)
EV = +$0.38 per $100 bet

That’s positive EV at a 55% win rate. Drop to 54% and the math flips negative. This is why signal quality (TWAP z-score strength) matters more than quantity. A 60% win rate turns $0.38 per $100 into $0.60 per $100. Signal strength compounds.

The split exit structure protects against reversal. If the market hits 2% and I’ve already cashed out half, the second half can either hit 5% or get stopped out. Either way, I’ve locked 50% of the winning outcome. That’s risk management.

The asymmetry is deliberate. I lose 3% on losers but capture 2-5% on winners because prices on TWAP-resolved markets still bounce. A tight 1% stop gets triggered by noise. A 3% stop lets the position breathe.

State Tracking for Reliable Exits

The position database tracks exit status for each open position:

CREATE TABLE positions (
    id INTEGER PRIMARY KEY,
    market_id TEXT,
    entry_price REAL,
    entry_qty INTEGER,
    entry_time TEXT,
    stop_loss_price REAL,      -- 0.4365 for 0.45 entry
    target_one_price REAL,     -- 0.459 (2% profit)
    target_two_price REAL,     -- 0.4725 (5% profit)
    exit_status TEXT,          -- 'open', 'half_closed', 'closing', 'closed'
    target_one_filled_at TEXT,
    target_two_filled_at TEXT,
    twap_window INTEGER,       -- 30 or 60
    linked_symbol TEXT         -- e.g. 'btc/usd'
);

On every minute, the exit manager reads the latest RTDS TWAP and current market price and compares against these thresholds. When target one hits, it updates exit_status to ‘half_closed’ and records the fill time. This prevents double-exits and ensures the second half of the position doesn’t exit prematurely.

Limit orders are crucial here. Market orders on Polymarket can slip 0.5-1% depending on order book depth. A limit order at target_one_price of $0.459 sits on the book until filled. If the market only reaches $0.458, the order stays open. If it bounces to $0.461, it fills at $0.459 (better than market order at $0.461). Over 100 trades, limit order precision saves 0.3-0.5% in aggregate slippage.

The real lesson: don’t set stop losses too tight on TWAP-resolved prediction markets. Binary outcomes mean prices bounce around more than equity markets. A 1% stop gets triggered by noise. 3% gives the position room to breathe while still protecting against real reversals.

The trickiest exit is time decay near the TWAP window. As the market approaches resolution, prices converge hard to the TWAP path. If I’m long and the market isn’t moving with the TWAP, the time decay works against me. Exiting stale positions frees capital for new TWAP signals.

One thing that surprised me: the time-decay / TWAP-proximity exit generated more total profit than the pure profit-target exit. Not because individual exits were bigger, but because freeing stale capital meant the bot could take 2-3 more trades per day. Capital velocity matters more than any single trade’s P&L.

How Do You Transition from Paper Trading to Live?

I paper-traded for 6 weeks before going live. Paper trading means simulating trades without real money, just tracking P&L against live RTDS TWAP feeds and CLOB order books.

Paper trading revealed two strategy failures:

Liquidity trap near TWAP windows — The culprit was insidious: entry prices looked good because I was catching markets right after a TWAP update, when stale limit orders still sat on the books. But exit? Nightmare. On markets with under $50K order book depth, especially in the final minutes before the 30s/60s TWAP settlement, I’d win the entry at $0.45 then get forced out at $0.42 because no one was buying. The tight spread at entry reversed hard at exit. Across 30 paper trades, this cost pattern showed up 7 times. Each time: entry P&L looked profitable (+2-3%), but the exit slippage erased it. One trade: up $2.25 on 50% exit at 2% profit, then the final 50% couldn’t execute near target. Ended up closing at $0.41 (-4% from entry) because the order book evaporated near the TWAP window. That single trade went from +$3 to -$1. Multiply that by 7 failed exits across the paper period, and I’m looking at roughly $2,000 in prevented losses once I added the liquidity + proximity check.

The fix was a simple gate before position entry:

async def check_market_liquidity_and_twap_window(market_id: str, twap_window: int) -> bool:
    """
    Only enter if order book has sufficient depth AND we are not too close to the TWAP resolution window.
    Skip if spread > 1% of mid-price or total depth < threshold.
    """
    order_book = await polymarket.get_order_book(market_id)
    best_bid = order_book['bids'][0]['price']
    best_ask = order_book['asks'][0]['price']
    mid = (best_bid + best_ask) / 2
    spread_pct = ((best_ask - best_bid) / mid) * 100

    total_depth = sum(qty for _, qty in order_book['bids'][:5]) + \
                  sum(qty for _, qty in order_book['asks'][:5])

    if spread_pct > 1.0:  # Spread too wide
        return False
    if total_depth < 500:  # Not enough size to exit
        return False
    # Extra guard: skip if market closes within 2× the TWAP window
    if seconds_to_resolution(market_id) < (twap_window * 2):
        return False
    return True

This single filter would have prevented 7 bad trades and saved ~$2,000 in real losses.

Signal timing on thin TWAP books — The second failure was time-dependent. TWAP signals arriving during European market hours (roughly 2-8 AM UTC, when US traders sleep) got filled at punishment prices. Same TWAP move, same market, but the order book was thin and slow-moving. I’d get a 30s/60s TWAP breakout at 5 AM UTC. By the time I placed the order, retail traders on Polymarket hadn’t woken up yet. Bid-ask spread was 0.5-1% instead of 0.2%. Fills were 200-300 basis points worse than signals arriving during US peak hours (12pm-11pm UTC). Over the 30 paper trades, only 6 arrived during European dead hours, but those 6 had 0.5-1% worse fills than identical TWAP signals during US hours. That’s roughly $1,500 in prevented slippage if I’d filtered those out.

The time-of-day filter was even simpler:

async def is_peak_trading_hour() -> bool:
    """
    Only process TWAP signals during peak US trading hours.
    12pm-11pm UTC captures most US market activity.
    """
    now_utc = datetime.datetime.utcnow()
    current_hour = now_utc.hour

    # Peak hours: 12pm-11pm UTC (7am-6pm EST)
    if 12 <= current_hour < 23:
        return True
    return False

async def should_process_signal(signal: dict) -> bool:
    if not await is_peak_trading_hour():
        return False  # Skip this TWAP signal
    return True

That’s it. One hour check prevented $1,500 in unnecessary slippage by avoiding markets where the book moves like molasses around live TWAP updates.

Both failures would have cost real money live. The 6-week cost in time was worth it.

I ran at least 30 paper trades before going live. That’s the minimum to see the major failure modes once you’re trading against the official Chainlink TWAP feeds. Anything less and you’re just guessing.

Find us on:

Python #trading #bot #Polymarket #Chainlink #TWAP #algorithmic #CLOB #API #prediction #markets #crypto #bot #paper #trading #live #trading #asyncio #Claude #Code #RTDS #order #book #exit #strategies #signal #generation #risk #management #TWAP #resolution

What Is Price Action? - Price Action Trading Introduction

Bo$onaX — Tue, 11 Aug 2026 15:12:22 +0000

What is Price Action? - Price Action Trading Explained

Price action trading is a methodology for financial market speculation which consists of the analysis of basic price movement across time. It's used by many retail traders and often by institutional traders and hedge fund managers to make predictions on the future direction of the price of a security or financial market.

Put simply, price action is how price changes, i.e., the 'action' of price. It's most easily observed in markets with high liquidity and volatility, but really anything that is bought or sold in a free market will generate price action.

Price action trading ignores the fundamental factors that influence a market's movement, and instead it looks primarily at the market's price history, that is to say its price movement across a period of time. Thus, price action is a form of technical analysis, but what differentiates it from most forms of technical analysis is that its main focus is on the relationship of a market's current price to its past or recent prices, as opposed to 'second-hand' values that are derived from that price history.

In other words, price action trading is a 'pure' form of technical analysis since it includes no second-hand, price-derived indicators. Price action traders are solely concerned with the first-hand data a market generates about itself; its price movement over time.

Price action analysis allows a trader to make sense of a market's price movement and provides him or her with explanations that serve as a way for the trader to build a mental scenario to describe the current market structure. Experienced price action traders often attribute their unique mental understanding and 'gut feel' of a market as the main reason for their profitable trading.

Price action traders make use of the past history of a market's price movement, most typically focusing on the recent price action of the last 3 to 6 months, with a lighter focus on more distant price history. This price history includes swing highs and swing lows in a market, as well as support and resistance levels.

A trader can use a market's price action to try and describe the human thought process behind a market's movement. Every participant in a market will leave price action 'clues' on a market's price chart as they trade their markets; these clues can then be interpreted and used to try and predict the next move in a market.

Price Action Trading - Keeping it Simple

Price action traders often use the phrase "Keep It Simple Stupid" in reference to the fact that trading is something many people over-complicate by clouding their charts with numerous technical indicators and generally over-analyzing a market.

Price action trading is also sometimes referred to as 'clean chart trading', 'naked trading', or 'raw or natural trading', in reference to trading from a simple price action only price chart.

The simple stripped-down approach of price action trading means there are no indicators on a trader's charts and no economic events or news is used in making one's trading decisions. The sole focus is on a market's price action, and the belief amongst price action traders is that this price action reflects all the variables (news events, economic data etc.) that influence a market and cause it to move. Therefore, the implication is that it's much simpler to just analyze a market and trade from its price action, rather than trying to decipher and sort the many different variables affecting a market each day.

Price Action Trading Strategies (Patterns)

Price action patterns, also called price action 'triggers', 'setups' or 'signals', are really the most important aspect of price action trading, because it's these patterns that provide a trader with strong clues as to what price might do next. Examples of some simple price action trading strategies include:

Inside bar pattern

A two-bar pattern consisting of the inside bar and the prior bar (usually called the "mother bar"). The inside bar is contained completely within the high to low range of the mother bar. This strategy is commonly used as a breakout pattern in trending markets, but it can also be traded as a reversal signal if it forms at a key chart level.

Pin bar pattern

Consists of a single candlestick and shows rejection of price and a reversal in the market. It works well in trending markets, range-bound markets, and can also be traded counter-trend from a key support or resistance level. The pin bar implies that price might move opposite from the direction the tail is pointing, as the tail shows rejection of price and a reversal.

Fakey pattern

Consists of a false breakout of an inside bar pattern. If an inside bar pattern breaks out briefly but then reverses and closes back within the range of the mother bar or inside bar, you have a fakey. It's called a "fakey" because it fakes you out - the market looks like it's breaking one way but then comes back in the opposite direction. Fakeys work well with trends, against trends from key levels, and in trading ranges.

Trading with Price Action Patterns
The article provides real-world chart examples (described in text), including:

A bearish fakey sell signal in a downtrend.

A bullish fakey pin bar combo setup in an upward market.

Inside bar and inside pin bar combo setups in trending markets.

Pin bar buy signals with long tails that led to large up moves.

Trading Price Action Patterns with Confluence
Trading with price action signals is not only about the signal itself, but also about where the signal forms on the chart. The best signals form at 'confluent' points (where multiple factors align), such as a pin bar in the direction of an uptrend at a support level. The more confluent factors supporting a signal, the higher-probability it is considered to be.

Conclusion
The article states that readers now have a solid basic understanding of what price action is and how to trade it, and encourages expanding knowledge further. It promotes the author's price action trading course for more in-depth strategies and professional insights.

Howto #Crypto #Polymarket #Trading #Strategy

Polymarket Crypto Up/Down Markets Are Switching to Chainlink TWAP — Here’s How It Would Have Changed the Last 150 Markets Per Asset

Bo$onaX — Mon, 03 Aug 2026 20:40:21 +0000

What’s changing on August 7

Starting August 7, 2026 at 00:00 UTC, Polymarket’s crypto up/down markets will stop resolving against a single snapshot price at market close.

Instead, resolution will use a Chainlink-computed Time-Weighted Average Price (TWAP):

5-minute markets → 30-second Chainlink TWAP
15-minute markets → 60-second Chainlink TWAP
4-hour markets → 60-second Chainlink TWAP

The target price (price-to-beat) stays exactly the same. Only the closing reference changes.

This is a deliberate move to protect market integrity and reduce the impact of last-second price spikes or thin liquidity at the exact close. Polymarket is also adding $1M in liquidity rewards across the affected markets throughout August.

Chainlink mainnet TWAP feeds are already live. Polymarket’s Real-Time Data Streaming (RTDS) WebSocket for TWAP is scheduled for August 4.

Official docs: Chainlink TWAP Prices on Polymarket

Historical impact: How many outcomes would have flipped?

I pulled the last 50 closed markets for each interval (5m / 15m / 4h) across the major assets and compared:

Snapshot close (current resolution method)
Chainlink TWAP (new resolution method)

Across 150 recent markets per asset, TWAP would have flipped the outcome in:

Asset	Flips	Max absolute difference
BTC	9	6.18 bps
ETH	5	7.05 bps
XRP	9	8.43 bps
SOL	8	9.59 bps
DOGE	8	11.77 bps
BNB	2	11.13 bps
HYPE	6	11.67 bps

The differences are small in absolute terms (most under 12 basis points), but in binary up/down markets that can be enough to flip the result when price is right at the target.

Visuals from the analysis

Here are the charts comparing Target (yellow), Snapshot close (blue), and TWAP (teal) for the last 50 markets of each interval:

BTC:

ETH:

SOL:

XRP:

BNB: / DOGE: / HYPE:

Source data came from the Vatic API (/api/v1/twap/recent). Snapshot close = Chainlink report at market end. TWAP = Chainlink-computed 30s/60s Data Streams report.

Why this matters for traders and builders

Last-second sniping becomes less effective. A single tick at the exact close no longer decides the market.
Bots and strategies that rely on the final snapshot need to adapt. You’ll want the TWAP value (or a running approximation) in the final 30–60 seconds.
Edge cases near the target price become more interesting. Small differences that previously didn’t matter can now flip outcomes.
Developers get cleaner, more robust oracle data. Chainlink Data Streams + upcoming Polymarket RTDS give low-latency access to the exact resolution reference.

Getting the data

Chainlink Data Streams (available now)

Use your existing credentials. Feed IDs for 30s and 60s TWAP are on data.chain.link/streams.

Polymarket RTDS (live August 4)

No credentials required. Topic: prices.crypto.chainlink.twap with windowSeconds: 30 | 60.

Vatic API

We’re adding full support so you can pull in one place:

Target price / price-to-beat
Snapshot close
Chainlink TWAP resolution reference

Get API keys: https://platform.vatic.trading/landing

Lowest-latency target price streaming + WebSocket guides are already available.

Bottom line

The change is modest in basis-point terms but meaningful for binary market outcomes. Most historical markets would have resolved the same way. A non-trivial minority would have flipped — especially on the more volatile assets.

If you’re running market-making, arb, or directional bots on Polymarket crypto up/down, now is the time to switch your resolution reference from snapshot to TWAP.

Questions or want the raw data behind the charts? Drop a comment or reach out.

DEV Community: Bo$onaX

Polymarket Arbitrage Bot: Production Architecture

Introduction

About the Author

What You'll Learn

1. The Architecture

2. Real-Time Market Data

3. Detecting an Arbitrage Opportunity

4. Strategy Layer

5. Execution Is the Hard Part

6. Python Project Structure

7. Risk Engine

8. Performance Considerations

9. Failure Modes

10. Testing Strategy

11. Monitoring

12. Practical Example

13. Advanced Improvements

Frequently Asked Questions

Is a Polymarket arbitrage bot risk-free?

Does YES + NO below $1 always mean profit?

Should I use REST or WebSocket?

Which Python SDK should new integrations use?

Can arbitrage be profitable?

Conclusion

Related Articles

Useful Resources

Polymarket Trading Bot Setup: Practical 2026 Guide

Introduction

About the Author

What You'll Learn

1. Recommended Architecture

2. Install the Current Python Client

3. Configure Secrets

4. Initialize the Trading Client

5. Build the Market-Data Layer

6. Add a Strategy Interface

7. Put Risk Before Execution

8. Execution

9. Production Considerations

10. Failure Modes

11. Testing Strategy

12. Monitoring

13. Practical Example

14. Advanced Improvements

Frequently Asked Questions

Is Python suitable for a Polymarket trading bot?

Do I need API credentials to read market data?

Should I start with live trading?

Does automation guarantee profitability?

Should I use REST or WebSockets?

Conclusion

Related Articles / Internal Topic Cluster

Useful Resources

Polymarket Trading Bot Position Sizing: A Practical Guide

Polymarket Trading Bot Position Sizing

About the Author

What You'll Learn

The Core Position-Sizing Problem

Step 1: Calculate Edge

Step 2: Use Kelly Criterion

Example

Step 3: Use Fractional Kelly

Step 4: Add Hard Risk Caps

Position Sizing and the Polymarket Order Book

Production Architecture

Retry Carefully

Common Failure Modes

1. Full Kelly with an overconfident model

2. Ignoring correlated exposure

3. Sizing from the last traded price

4. Treating paper trading as live trading

5. No maximum loss controls

Testing and Monitoring

Practical Example

Advanced Improvements

Frequently Asked Questions

How much should a Polymarket trading bot risk per trade?

Is Kelly Criterion good for a Polymarket bot?

Should a Polymarket arbitrage bot use position sizing?