Polymarket has become one of the most important on-chain prediction markets, enabling users to trade event outcomes with real liquidity. Under the hood, its trading system is powered by a Central Limit Order Book (CLOB) architecture, which allows algorithmic trading, market making, and automated strategies.
This article provides a deep technical breakdown of Polymarket API authentication, order execution, and bot architecture design, with real-world examples and production-ready insights.
We will also explore:
- How authentication really works (L1 + L2 model)
- How orders are signed and executed
- How trading bots interact with the CLOB
- Common pitfalls in production systems
- Strategy insights from real trading bots
Official docs:
👉 https://docs.polymarket.com ([Polymarket Documentation][1])
🧠 1. Understanding Polymarket Architecture
Polymarket is not a simple REST API exchange. It consists of three distinct layers:
┌──────────────────────────────┐
│ Gamma API │
│ Market Data / Metadata │
└─────────────┬────────────────┘
│
▼
┌──────────────────────────────┐
│ Data API │
│ Positions / Trades / PnL │
└─────────────┬────────────────┘
│
▼
┌──────────────────────────────┐
│ CLOB API │
│ Order Book + Trading Engine │
└──────────────────────────────┘
Key insight:
Only the CLOB API is used for trading execution. Everything else is informational.
📌 Source: Polymarket API overview (https://docs.polymarket.com/api-reference)
🔐 2. Polymarket Authentication Model (CRITICAL)
Polymarket uses a two-layer authentication system:
🔹 Layer 1 (L1): Wallet Signature Authentication
L1 is based on:
- Your Ethereum/Polygon wallet
- EIP-712 signed messages
Used for:
- Creating API keys
- Verifying ownership of wallet
- Bootstrapping trading credentials
👉 Think of it as:
“Proving you own the wallet”
🔹 Layer 2 (L2): API Key Authentication
Once L1 is completed, you receive:
{
"apiKey": "uuid",
"secret": "base64_secret",
"passphrase": "random_string"
}
These are used for fast trading requests.
Used for:
- Placing orders
- Cancelling orders
- Fetching account state
🔐 L2 Required Headers
Every trading request must include:
POLY_ADDRESS
POLY_API_KEY
POLY_PASSPHRASE
POLY_SIGNATURE
POLY_TIMESTAMP
Signature = HMAC-SHA256(secret, request_payload)
⚙️ 3. Authentication Flow (Step-by-Step)
Wallet (Private Key)
│
▼
L1 Signature (EIP-712)
│
▼
POST /auth/api-key
│
▼
Receive API credentials
│
▼
L2 HMAC signing
│
▼
Trading via CLOB API
🧪 4. Python Example: Authentication + Client Setup
Using official SDK:
from py_clob_client_v2 import ClobClient
import os
client = ClobClient(
host="https://clob.polymarket.com",
chain_id=137,
key=os.getenv("PRIVATE_KEY")
)
credentials = client.create_or_derive_api_key()
print(credentials)
📊 5. Order Execution Lifecycle (VERY IMPORTANT)
A Polymarket order is NOT a simple API call.
It goes through:
1. Build order intent
2. Sign order locally (wallet)
3. Attach API headers (L2)
4. Submit to CLOB engine
5. Match against order book
6. Settlement recorded on-chain
🧾 Order Flow Diagram
Trader Bot
│
▼
Create Order (token_id, price, size)
│
▼
Sign with wallet (EIP-712)
│
▼
Attach L2 headers
│
▼
POST /order
│
▼
CLOB Matching Engine
│
▼
Matched / Partial Fill / Open Order
│
▼
On-chain settlement (Polygon)
💻 6. Example: Placing an Order (Python)
from py_clob_client_v2 import OrderArgs, BUY
order = client.create_and_post_order(
OrderArgs(
token_id="123456",
price=0.65,
size=100,
side=BUY
),
options={
"tick_size": "0.01",
"neg_risk": False
}
)
print(order)
⚡ 7. Node.js Example (Trading Bot Style)
import { ClobClient, Side } from "@polymarket/clob-client-v2";
import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const signer = createWalletClient({
account,
transport: http()
});
const client = new ClobClient({
host: "https://clob.polymarket.com",
chain: 137,
signer
});
const order = await client.createAndPostOrder({
token_id: "123456",
price: 0.70,
size: 50,
side: "BUY"
});
console.log(order);
🧠 8. Trading Bot Architecture (Production Design)
A serious Polymarket bot is structured like:
┌────────────────────┐
│ Market Data Feed │
│ (Gamma API) │
└─────────┬──────────┘
▼
┌────────────────────┐
│ Strategy Engine │
│ - signals │
│ - pricing models │
└─────────┬──────────┘
▼
┌────────────────────┐
│ Risk Manager │
│ - exposure limits │
└─────────┬──────────┘
▼
┌────────────────────┐
│ Execution Engine │
│ (CLOB API) │
└─────────┬──────────┘
▼
┌────────────────────┐
│ PnL Tracker │
└────────────────────┘
📌 9. Common Issues in Production Bots
❌ 1. Signature mismatch
- Wrong wallet used
- API key tied to different address
❌ 2. Order signer mismatch error
“order signer address has to be API key address”
This is common in fresh accounts.
❌ 3. Missing deposit wallet alignment
Some accounts require:
- deposit wallet ≠ EOA wallet mismatch handling
❌ 4. No historical orderbook data
Important limitation:
Polymarket does NOT provide full historical orderbook state.
Only fills are stored on-chain.
📈 10. Strategy Insights from Real Trading Bots
From open-source bot implementations like:
👉 https://github.com/mateosoul/Polymarket-Trading-Bot-Python
And live trading profiles:
👉 https://polymarket.com/@mateosoul
We can extract real-world strategies:
🟢 1. Market making
- Place both bid/ask
- Profit from spread
🟡 2. Momentum trading
- Follow probability spikes
🔵 3. Event arbitrage
- Cross-market inefficiencies
🔴 4. Resolution betting
- High confidence near event expiry
📊 11. Performance Tracking (PnL System)
Typical bot PnL structure:
PnL = realized gains + unrealized position value - fees
Tracked via:
- Data API positions endpoint
- On-chain fills
- Local ledger system
🧾 12. Security Best Practices
- Never hardcode private keys
- Use
.envor vault systems - Rotate API keys regularly
- Limit bot permissions
❓ FAQ (SEO BOOST SECTION)
❓ What is Polymarket API used for?
It is used for:
- Trading prediction markets
- Fetching market data
- Building automated trading bots
❓ Is Polymarket API free?
Yes, but trading requires authenticated credentials.
❓ Can I build a trading bot with Polymarket API?
Yes. The CLOB API is designed specifically for algorithmic trading.
❓ Why is authentication complex?
Because it uses:
- Wallet-based L1 security
- API-key-based L2 speed layer
❓ Can I get historical orderbook data?
No. Only trade fills are stored on-chain.
🔗 Official Resources
- Docs: https://docs.polymarket.com
- GitHub Bot: https://github.com/mateosoul/Polymarket-Trading-Bot-Python
- Bot Trading Profile: https://polymarket.com/@mateosoul
- Contact info: https://polymarket.com/@mateosoul
🧠 Final Thoughts
Polymarket’s API is not just a trading interface—it is a hybrid decentralized execution system combining off-chain matching with on-chain settlement.
Understanding:
- L1 authentication (wallet trust)
- L2 authentication (execution speed)
- CLOB matching engine (execution layer)
…is essential for building serious trading bots and quantitative strategies.
Top comments (0)