If you want to build a trading bot for Polymarket, you do not need one giant API that does everything.
Polymarket exposes several developer interfaces, and each one has a different responsibility. The Gamma API is used to discover markets and retrieve market metadata. The CLOB API handles prices, order books, and trading. The Data API provides information about positions and activity. WebSocket connections provide real-time updates.
Understanding that separation is one of the first things a developer should get right before building a trading bot.
What APIs does Polymarket provide?
Polymarket's current developer documentation describes several integration surfaces:
- Gamma API for discovering events and markets
- CLOB API for prices, order books, and orders
- Data API for positions, activity, and market participation
- CLOB Market WebSocket for real-time market updates
- CLOB User WebSocket for authenticated order and trade updates
- RTDS for real-time reference prices, comments, and trade activity
Polymarket also provides official SDKs for supported environments. The documentation recommends using the SDKs when possible because they provide a unified interface and handle common concerns such as pagination, errors, and wallet setup.
The important part is knowing which interface belongs in which part of your application.
Gamma API: finding the market you want
Before a bot can trade a market, it needs to know what market exists.
That is where the Gamma API comes in.
The current Gamma API endpoint is:
https://gamma-api.polymarket.com
It provides access to market and event metadata.
For example, a simple request can retrieve active markets:
curl -G "https://gamma-api.polymarket.com/markets" \
--data-urlencode "closed=false" \
--data-urlencode "limit=5"
This is useful for applications that need to discover markets dynamically instead of hard-coding market IDs.
A market-discovery service might use this information to build an internal object such as:
market = {
"id": "...",
"question": "...",
"active": True,
"token_ids": [...]
}
Your trading logic can then work with this normalized representation instead of repeatedly parsing raw API responses.
CLOB API: where trading actually happens
The CLOB API is the most important interface for a trading bot.
CLOB stands for Central Limit Order Book.
The current endpoint is:
Polymarket documents the CLOB API as the interface for reading prices and order books and for placing and managing orders.
This means a trading bot will generally interact with the CLOB when it needs to answer questions such as:
What is the current price?
What does the order book look like?
What orders do I currently have?
Can I place an order?
What happened to my order?
That makes the CLOB the core execution interface.
Why the order book matters
A bot should not treat the displayed market price as the price it will automatically receive.
An order book contains available bids and asks at different prices and sizes.
For example:
ASKS
0.51 120 shares
0.52 350 shares
0.54 900 shares
BIDS
0.49 200 shares
0.48 500 shares
0.46 800 shares
Suppose your bot wants to buy 500 shares.
There may only be 120 shares available at 0.51.
The remaining quantity may need to execute at higher prices.
That means the bot needs to think about execution price, not simply the latest displayed price.
For copy trading, this becomes even more important because the target trader may have entered before your bot detected the trade.
Data API: understanding wallet activity
The Data API serves a different purpose.
The current endpoint is:
https://data-api.polymarket.com
Polymarket documents it as an interface for analyzing positions, activity, and market participation.
This becomes useful when building applications around trader behavior.
For example, a wallet-monitoring application could use data from the Data API to examine:
wallet = {
"address": "0x...",
"positions": [...],
"activity": [...]
}
From there, an application could calculate metrics such as:
- Recent trading activity
- Markets traded
- Position exposure
- Historical behavior
- Trading frequency
This is particularly useful when evaluating wallets for copy trading.
A wallet with a large historical profit is not automatically a good copy target. You also need to understand what produced that performance and whether the behavior can realistically be reproduced.
WebSockets: when polling is not enough
REST APIs are useful when you need to request information.
But trading systems often need to know when something changes.
That is where WebSockets become useful.
Polymarket currently provides a public market WebSocket:
wss://ws-subscriptions-clob.polymarket.com/ws/market
and an authenticated user WebSocket:
wss://ws-subscriptions-clob.polymarket.com/ws/user
The market stream can provide updates involving order books, price changes, last trade prices, tick-size changes, and other market events.
A simplified Python structure could look like:
async def monitor_market(client, token_id):
stream = await client.subscribe([
{
"topic": "market",
"tokenIds": [token_id]
}
])
async for event in stream:
print(event)
The exact implementation depends on the current SDK you choose, but the architectural idea is simple:
REST is useful for retrieving state.
WebSockets are useful for reacting to changes in state.
That distinction becomes important when building bots that need timely information.
What can a market WebSocket actually tell you?
Polymarket's current market stream includes several event types.
A book event can contain bids and asks:
{
"type": "book",
"payload": {
"tokenId": "...",
"bids": [
{
"price": "0.08",
"size": "33343.4"
}
],
"asks": [
{
"price": "0.09",
"size": "163939.58"
}
]
}
}
Price-change events can include the updated price, size, side, best bid, and best ask.
The stream can also provide last-trade-price events and best-bid/ask information.
This means a bot can maintain a local view of the market instead of constantly asking the API:
"What is the price now?"
"What is the price now?"
"What is the price now?"
That approach can become inefficient when monitoring many markets.
Authentication is different from public market data
One of the most important concepts for new developers is that reading public market information and submitting trades are not the same thing.
Polymarket's current CLOB authentication uses two layers.
The first layer involves a wallet signature using EIP-712 typed data.
The second layer uses API credentials and HMAC-SHA256 signatures for private CLOB requests.
The documentation describes the authentication flow as establishing wallet control first and then using API credentials for authenticated requests.
That distinction matters because a bot that only reads public prices does not need the same credentials as a bot that places orders.
Never put private keys directly into your code
This sounds obvious, but it is one of the easiest mistakes to make when experimenting with trading bots.
Do not write:
PRIVATE_KEY = "your-real-private-key"
inside a Git repository.
Use environment variables or another secure secret-management mechanism instead.
For example:
import os
private_key = os.environ["POLYMARKET_PRIVATE_KEY"]
Then keep the actual value outside your source code.
The same principle applies to API credentials.
A trading bot has a much higher security requirement than a normal data-analysis script because compromised credentials can have financial consequences.
How the APIs fit together in a trading bot
Consider a bot that monitors a Polymarket wallet and copies its trades.
Different parts of the application can use different interfaces.
Market discovery
Use the Gamma API to find the relevant market and retrieve its metadata.
Wallet analysis
Use the Data API and other appropriate public data sources to understand activity and positions.
Market monitoring
Use the CLOB market WebSocket to keep current market information available.
Execution
Use the CLOB API when the strategy decides that an order should be submitted.
Account monitoring
Use authenticated order and trade updates to track what happened after an order was submitted.
This separation makes the application easier to maintain.
Instead of building one enormous trading function, you can create independent components:
market_data.py
wallet_data.py
strategy.py
risk.py
execution.py
portfolio.py
Each component has a defined responsibility.
REST polling vs WebSockets
The choice between REST and WebSockets depends on what your application needs.
REST is useful when:
- You need an initial snapshot
- You are loading historical information
- You are requesting specific market data
- You are checking account state
- You do not need continuous updates
WebSockets are useful when:
- You need continuous market updates
- You are monitoring order books
- You need to react to price changes
- You are building real-time execution logic
- You are monitoring multiple active markets
In practice, a serious bot often uses both.
For example, the application can retrieve an initial market snapshot through an API and then keep its state updated through a WebSocket stream.
A simple architecture for a Python bot
A practical project could start with something like:
polymarket_bot/
│
├── main.py
├── config.py
├── market_data.py
├── wallet.py
├── strategy.py
├── risk.py
├── execution.py
├── portfolio.py
└── tests/
The responsibilities can remain straightforward.
"market_data.py" handles market information.
"wallet.py" handles trader or account data.
"strategy.py" determines whether an opportunity meets your rules.
"risk.py" decides whether the proposed trade is allowed.
"execution.py" communicates with the trading interface.
"portfolio.py" tracks positions and exposure.
This structure is much easier to expand than putting everything into "main.py".
What should you build first?
Do not start with live order execution.
Start with market discovery.
Then build a small program that retrieves market data.
After that, add order-book monitoring.
Then build your strategy logic.
Then add simulated execution.
Only after those components behave correctly should you consider connecting live trading.
This development sequence makes debugging considerably easier because you can determine whether a problem comes from your data, strategy, risk logic, or execution layer.
How Dexoryn uses these concepts
Dexoryn Labs currently maintains public Polymarket trading and copy-trading repositories.
Its Python trading-bot repository uses real-time wallet/trade monitoring, configurable sizing, dry-run mode, persistent state, slippage controls, and position limits.
The newer copy-trading repository also exposes a broader application structure with multiple target wallets, a dashboard, WebSocket detection, dry-run execution, and persistent state.
The interesting part from a developer perspective is not simply the existence of a bot.
It is how these individual API capabilities become application features.
Real-time feeds become trade detection.
Market data becomes execution context.
Authentication becomes secure order submission.
Position data becomes portfolio management.
Risk controls sit between the strategy and execution layer.
That is where an API becomes a trading system.
Common mistakes when working with Polymarket APIs
Treating every API as interchangeable
They are not.
Gamma, CLOB, Data API, and WebSockets solve different problems.
Building around outdated tutorials
Polymarket's developer stack evolves.
The current documentation includes migration guidance for older Data API versions and older SDKs.
Always check the current documentation before copying an old code example into a new project.
Polling everything
Constantly requesting the same information through REST can be wasteful when a real-time stream is available.
Ignoring the order book
A market price is not enough to understand execution quality.
Liquidity, spread, available size, and price movement all matter.
Going live too early
A bot that works perfectly in a dry run can behave very differently when real orders, partial fills, price movement, network failures, and authentication errors enter the picture.
Final thoughts
Polymarket's API ecosystem is easier to understand once you stop thinking of it as one API.
The Gamma API helps you discover markets.
The CLOB API gives your application access to prices, order books, and trading.
The Data API provides wallet and position information.
WebSockets keep applications informed about real-time changes.
Together, these interfaces provide the building blocks for everything from market dashboards and analytics tools to automated trading systems.
But the API is only the infrastructure.
The difficult engineering work is deciding what information matters, turning that information into a strategy, controlling risk, and making sure the system behaves correctly when the market does something unexpected.
That is where a Polymarket bot stops being an API script and starts becoming a real software system.
Top comments (0)