DEV Community

Cover image for How Polymarket Orders Actually Execute in CLOB V2: A Developer's Deep Dive
Benjamin-Cup
Benjamin-Cup

Posted on

How Polymarket Orders Actually Execute in CLOB V2: A Developer's Deep Dive

#tutorial #opensource #polymarket #typescript

Understanding the complete lifecycle of an order—from API request to on-chain settlement.

Introduction

If you've built trading bots, market-making systems, or analytics tools around Polymarket, you've probably used the API to place orders.

How to make the polymarket trading bot

A typical workflow looks simple:

const order = await client.createOrder({...});
await client.postOrder(order);
Enter fullscreen mode Exit fullscreen mode

The order appears in the market almost instantly.

But what actually happens behind the scenes?

Many developers assume every order is immediately submitted to Polygon. Others believe Polymarket operates like a traditional decentralized exchange where matching and settlement happen entirely on-chain.

Neither is true.

With the introduction of Polymarket CLOB V2, the platform uses a hybrid architecture that combines the performance of centralized exchanges with the security guarantees of blockchain settlement.

Understanding this architecture is critical if you're building:

  • Trading bots
  • Arbitrage systems
  • Market-making infrastructure
  • Data pipelines
  • Portfolio trackers
  • Risk engines
  • Quantitative trading strategies

In this article, we'll follow an order through the entire execution pipeline and explain exactly how Polymarket V2 processes trades.

What Is CLOB V2?

CLOB stands for Central Limit Order Book.

Unlike automated market makers (AMMs) that determine prices using mathematical formulas, a CLOB matches buyers and sellers directly through an order book.

If you've traded on exchanges such as Binance, Coinbase, Kraken, or NASDAQ, you've already used a CLOB.

Polymarket V2 brings this model to prediction markets.

Instead of trading cryptocurrencies, users trade outcome tokens representing probabilities of future events.

Example:

Will Bitcoin exceed $200,000 before Jan 1, 2027?
Enter fullscreen mode Exit fullscreen mode

The market may trade at:

YES = $0.68
NO  = $0.32
Enter fullscreen mode Exit fullscreen mode

These prices represent market-implied probabilities.

Under the hood, Polymarket V2 consists of four major components:

┌─────────────────────┐
│      Trader         │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│     CLOB API V2     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Matching Engine    │
│    Off-Chain        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Exchange Contract   │
│      Polygon        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Atomic Settlement   │
└─────────────────────┘
Enter fullscreen mode Exit fullscreen mode

This architecture separates trading performance from blockchain settlement.

The result is a trading experience that feels similar to a centralized exchange while maintaining non-custodial execution.

The First Important Concept: Orders Are Not Transactions

One of the biggest misconceptions among developers is:

"Submitting an order means sending a transaction."

In Polymarket V2, this is not how trading works.

When you create an order:

const order = await client.createOrder({
  tokenID,
  side: "BUY",
  price: 0.63,
  size: 100
});
Enter fullscreen mode Exit fullscreen mode

you are not creating a blockchain transaction.

Instead, you're generating a signed message.

The signed message contains information such as:

{
  "tokenID": "...",
  "side": "BUY",
  "price": "0.63",
  "size": "100",
  "timestamp": 1748530000
}
Enter fullscreen mode Exit fullscreen mode

The order is cryptographically signed using EIP-712 typed data.

This signature proves:

  • The order was authorized by the wallet owner
  • The order parameters haven't been modified
  • The order can later be validated on-chain

At this stage:

✅ Signed locally

✅ Verifiable

❌ Not on-chain

❌ No gas cost

❌ No blockchain transaction

This distinction is extremely important because it explains why placing orders is fast and inexpensive.

Authentication in CLOB V2

Before trading, developers must authenticate with the API.

Polymarket V2 uses a two-layer authentication system.

Layer 1 Authentication

The wallet itself acts as the root identity.

A wallet signs messages to prove ownership.

Wallet
   │
   ▼
EIP-712 Signature
Enter fullscreen mode Exit fullscreen mode

This layer is responsible for:

  • User identity
  • API key generation
  • Order authorization

Layer 2 Authentication

After wallet verification, developers generate API credentials.

apiKey
secret
passphrase
Enter fullscreen mode Exit fullscreen mode

These credentials are used for:

  • Order creation
  • Order cancellation
  • Portfolio endpoints
  • Trading operations

This design avoids requiring a wallet signature for every API request while maintaining strong security guarantees.

Creating and Posting an Order

Once authenticated, the workflow looks straightforward.

const order = await client.createOrder({
  tokenID,
  side: "BUY",
  price: 0.65,
  size: 100
});

await client.postOrder(order);
Enter fullscreen mode Exit fullscreen mode

After posting, the order enters the off-chain order book.

At this moment, the order becomes visible to other traders.

Example:

BIDS

0.65 → 100
0.64 → 250
0.63 → 500
Enter fullscreen mode Exit fullscreen mode

The order now exists inside the matching engine.

Importantly, Polygon still has no knowledge of this order.

Nothing has been settled yet.

Understanding the Matching Engine

The matching engine is the heart of Polymarket.

Its job is to continuously compare:

BUY ORDERS
vs
SELL ORDERS
Enter fullscreen mode Exit fullscreen mode

When compatible orders exist, a trade can be executed.

Consider the following example.

Existing Ask 

SELL YES
Price: 0.65
Size: 100
Enter fullscreen mode Exit fullscreen mode

New Bid 

BUY YES
Price: 0.65
Size: 100
Enter fullscreen mode Exit fullscreen mode

The prices match exactly.

The engine immediately creates a trade.

Trade:
100 shares @ 0.65
Enter fullscreen mode Exit fullscreen mode

The matching process happens entirely off-chain.

This is one of the biggest reasons Polymarket can support high-frequency trading activity without blockchain congestion.

If matching occurred directly on Polygon:

  • Every order would require gas
  • Latency would increase dramatically
  • Market makers would struggle to quote continuously
  • User experience would degrade

The off-chain matching engine solves these problems.

Price-Time Priority

Polymarket V2 follows standard exchange matching rules.

Rule 1: Best Price Wins

Example:

Bid A = 0.64
Bid B = 0.65
Enter fullscreen mode Exit fullscreen mode

Bid B receives priority.

Rule 2: Earlier Orders Win

Example:

09:00 BUY @ 0.65
09:01 BUY @ 0.65
Enter fullscreen mode Exit fullscreen mode

The 09:00 order executes first.

This is known as price-time priority.

It ensures fair execution across the marketplace.

Partial Fills

Not every order is filled completely.

Imagine:

BUY 500 YES @ 0.65
Enter fullscreen mode Exit fullscreen mode

Available liquidity:

SELL 100 @ 0.65
SELL 150 @ 0.65
Enter fullscreen mode Exit fullscreen mode

Only:

250 shares
Enter fullscreen mode Exit fullscreen mode

can execute immediately.

Result:

Filled: 250
Remaining: 250
Enter fullscreen mode Exit fullscreen mode

The remaining quantity stays on the order book.

Developers building trading bots should always account for partial fills.

Assuming an order is either completely filled or completely unfilled is a common mistake.

What Happens After a Match?

This is where blockchain finally enters the process.

After matching occurs:

Order A
   │
Order B
   │
   ▼
Match Created
Enter fullscreen mode Exit fullscreen mode

The matched trade is sent for settlement.

Match
  │
  ▼
Exchange Contract V2
  │
  ▼
Polygon
Enter fullscreen mode Exit fullscreen mode

Settlement verifies:

  • Order signatures
  • Wallet ownership
  • Available balances
  • Trade validity
  • Contract rules

If all checks pass, ownership changes atomically.

Atomic Settlement Explained

Atomic settlement means:

Everything succeeds
OR
Nothing succeeds
Enter fullscreen mode Exit fullscreen mode

There is no intermediate state.

Example:

Alice buys YES.

Bob sells YES.

Settlement either:

Alice receives YES
Bob receives pUSD
Enter fullscreen mode Exit fullscreen mode

or:

Trade fails
No balances change
Enter fullscreen mode Exit fullscreen mode

This protects both participants.

The Role of pUSD

One major change in V2 is the adoption of pUSD.

In previous versions, collateral management was different.

Now settlement generally occurs between:

pUSD
↔
Outcome Tokens
Enter fullscreen mode Exit fullscreen mode

This simplifies trading infrastructure and standardizes settlement mechanics.

For developers building portfolio systems, this means collateral tracking logic should be updated to reflect the V2 architecture.

Why Polymarket Doesn't Match Orders On-Chain

This question appears frequently.

Why not simply perform matching directly on Polygon?

The answer is performance.

Imagine a market maker updating quotes every second.

BUY @ 0.64
SELL @ 0.66
Enter fullscreen mode Exit fullscreen mode

Then:

BUY @ 0.65
SELL @ 0.67
Enter fullscreen mode Exit fullscreen mode

Then:

BUY @ 0.66
SELL @ 0.68
Enter fullscreen mode Exit fullscreen mode

If every update required a blockchain transaction:

  • Gas costs would explode
  • Throughput would collapse
  • Market depth would disappear

Modern exchanges require extremely fast order management.

The hybrid architecture allows:

Matching = Off-Chain
Settlement = On-Chain
Enter fullscreen mode Exit fullscreen mode

This provides the best balance between speed and security.

Building Trading Bots on CLOB V2

Most developers interact with Polymarket through automated systems.

Typical bot architecture:

Market Data Feed
        │
        ▼
 Strategy Engine
        │
        ▼
 Risk Checks
        │
        ▼
 Order Creation
        │
        ▼
 CLOB API
Enter fullscreen mode Exit fullscreen mode

Common bot types include:

Market Makers

Continuously quote:

BUY 0.64
SELL 0.66
Enter fullscreen mode Exit fullscreen mode

and earn spread.

Arbitrage Bots

Compare prices across:

  • Polymarket
  • Kalshi
  • Betting exchanges
  • External prediction markets

Statistical Traders

Use probability models to identify mispriced contracts.

Hedging Systems

Offset exposure across multiple correlated markets.

Understanding the execution pipeline is critical because latency, partial fills, and settlement timing directly affect profitability.

Common Developer Mistakes

Mistake #1: Treating Orders Like Transactions

Orders are signed messages.

Settlement is the transaction.

Mistake #2: Ignoring Partial Fills

Large orders frequently execute across multiple counterparties.

Always track remaining quantity.

Mistake #3: Using Old V1 SDKs

V2 introduced:

  • New contracts
  • New authentication
  • New signing logic
  • New collateral model

Use V2 tooling only.

Mistake #4: Assuming Immediate Finality

Matching may occur instantly.

Settlement still requires successful on-chain execution.

Your system should handle asynchronous updates.

FAQ

Are orders stored on-chain?

No.

Open orders remain inside the off-chain CLOB.

Only completed settlements reach Polygon.

Does placing an order cost gas?

No.

Order creation is off-chain.

Does settlement cost gas?

Settlement involves blockchain execution, but users generally interact through the exchange infrastructure rather than manually submitting transactions.

Is Polymarket custodial?

No.

Orders are signed by users and validated through smart contracts.

Can I build a high-frequency trading bot?

Yes.

The off-chain matching architecture is specifically designed to support low-latency trading.

Official Documentation

API Introduction

https://docs.polymarket.com/api-reference/introduction

Authentication

https://docs.polymarket.com/api-reference/authentication

CLOB Overview

https://docs.polymarket.com/developers/CLOB/trades/trades

V2 Migration Guide

https://docs.polymarket.com/v2-migration

Final Thoughts

Polymarket V2 is fundamentally different from traditional decentralized exchanges.

Rather than forcing every action onto the blockchain, it separates the trading lifecycle into two distinct phases:

Phase 1:
Order Creation + Matching
(Off-Chain)

Phase 2:
Settlement
(On-Chain)
Enter fullscreen mode Exit fullscreen mode

This architecture enables fast execution, deep liquidity, and a familiar trading experience while preserving the security guarantees of blockchain settlement.

For developers, understanding where an order lives at each stage—signed message, order book entry, matched trade, and settled position—is essential when building reliable trading systems on top of Polymarket.

Once you understand this lifecycle, the behavior of the entire platform becomes much easier to reason about, optimize, and automate.

🤝 Collaboration & Contact

If you’re interested in building trading bots, buy trading bots, collaborating, exploring strategy improvements, or discussing about this system, feel free to reach out.

I’m especially open to connecting with:

Quant traders
Engineers building trading infrastructure
Researchers in prediction markets
Investors interested in market inefficiencies

📌 GitHub Repository

This repo has some Polymarket several bots in this system.
You can explore the full implementation, strategy logic, and ongoing updates about 5 min crypto market here:

GitHub logo Benjamin-cup / Polymarket-trading-bot-python-V2

Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot Polymarket Trading Bot

Polymarket Trading Bot | Polymarket Arbitrage Bot

An open-source and Strong Strategy collection of Polymarket trading bot and arbitrage bot in Python for high-performance automated trading on polymarket crypto 5min markets.

Polymarket Trading Bot Dashboard

Features

  • Explosive growth of Polymarket with surging trading volume and new short-term markets

  • Increasing dominance of automated bots and AI in 5-minute crypto prediction markets

  • Higher profitability potential through advanced arbitrage and market-making strategies

  • Stronger edge for Python-based bots with real-time orderbook intelligence and low-latency execution

  • Continuous evolution of sniper, ladder, stair, momentum, and copy trading strategies

  • Scalable daily profits as prediction markets move toward hundreds of billions in annual volume

  • Full future-proof architecture for new features, contracts, and high-frequency trading environments

Included Trading Bots

Designed for arbitrage, directional strategies, and ultra-short-term markets (including 5-minute rounds), this bot framework provides a robust foundation for building and scaling automated trading strategies on Polymarket .

Demo Video

https://www.youtube.com/watch?v=Yp3gpNXF2RA

Contact

I have…


View on GitHub


This is my trading bot public accounts.

@maksim42 on Polymarket

Check out this profile on Polymarket.

favicon polymarket.com

@dava1414 on Polymarket

Check out this profile on Polymarket.

favicon polymarket.com

💬 Get in Touch

If you have ideas, questions, or would like to collaborate or want these trading bots, don’t hesitate to reach out directly.

Feedback on your repo (based on your description & strategy)

Contact Info

Telegram
https://t.me/BenjaminCup

Top comments (0)