A trader managing positions across multiple Polymarket prediction markets faces a fundamental constraint: the web interface cannot simultaneously monitor dozens of events, execute orders at precise probabilities, or calculate expected value across correlated outcomes. This gap between manual trading and algorithmic execution is where the Polymarket API becomes essential. The platform exposes endpoints for market discovery, order placement, event monitoring, and balance queries—resources that enable custom bots to monitor conditions, execute trades based on user-defined rules, and integrate Polymarket trading into broader portfolio management systems.
Building on Polygon’s layer-2 infrastructure and backed by pUSD (USDC-denominated stablecoins), Polymarket offers both international markets and a CFTC-regulated US version, creating two distinct API surfaces with different authentication, geographic constraints, and settlement mechanics. Understanding which endpoints serve which instance, how rate limits apply, and what transaction finality guarantees the blockchain provides separates functional bots from ones that lose money in production. The technical foundation also matters: whether you are fetching live odds, calculating arbitrage, sizing positions, or monitoring order status, the API response format and latency characteristics determine whether your strategy can execute reliably.
Understanding Polymarket’s API architecture and two trading instances
Polymarket operates two separate trading environments with different regulatory and technical characteristics. The international Polymarket instance uses pUSD as its native currency and does not require KYC for certain jurisdictions outside the 40+ restricted countries including the UK, France, Germany, Australia, and Netherlands. A separate Polymarket US instance is explicitly CFTC-regulated, requires full KYC onboarding, and follows US commodity derivatives rules. Both instances operate on Polygon, but their API endpoints, authentication schemas, and order settlement rules differ materially.
The core API architecture uses REST endpoints for market queries, event history, and account information, with WebSocket support for real-time order book updates and trade feeds. Authentication on the international Polymarket typically uses an API key and secret pair, which you send as headers or include in request signatures, while Polymarket US uses a similar model but with additional CFTC-compliance checkpoints. Rate limits vary by endpoint and account tier: public endpoints often allow 100–300 requests per minute, while authenticated order placement may be throttled to prevent market manipulation or excessive computational load on the backend.
The distinction between these two instances matters because migration, arbitrage, or unified bots that straddle both could trigger regulatory or operational complications. A bot designed for international Polymarket should not assume it can reuse credentials for US trading. Similarly, market IDs and contract addresses differ between instances; a market on international Polymarket may not have a direct counterpart on Polymarket US, or if it does, it uses a different smart contract address on Polygon.
Developers integrating Polymarket should also account for the role of UMA’s Optimistic Oracle in market resolution. When a binary outcome event resolves, Polymarket submits the outcome claim to UMA, which allows a dispute period (typically 2 hours) for token holders to contest the result. If no one disputes within that window, the claim is deemed correct and settlement occurs on-chain. If a dispute is filed, UMA initiates its escalation game, which involves voting and final adjudication. This process can take days, meaning that even after an event’s real-world outcome is certain, positions may be marked unresolved on-chain until UMA’s process concludes. Bots should poll the market status endpoint regularly rather than assuming instant settlement.
Public endpoints for market discovery and real-time monitoring
The most frequently used Polymarket public endpoints retrieve market metadata, current prices, and order book snapshots without authentication. These endpoints are rate-limited but accessible to anyone, making them suitable for research, backtesting, or building public dashboards. The markets endpoint returns a paginated list of all active and resolved markets, including market IDs, descriptions, creator addresses, outcome tokens, creation times, and settlement sources. By default, this endpoint may return 100 markets per page; you control pagination using limit and offset parameters.
The orderbook endpoint returns the current bid and ask prices for a specific market, typically quoted as a price between $0.00 and $1.00 per share. Each side of the book includes a list of orders with their sizes and prices, allowing you to calculate liquidity, estimate slippage for various order sizes, and detect price anomalies across Polymarket markets or between Polymarket and other prediction platforms. The trades endpoint shows the most recent executed trades for a market, useful for reconstructing price history and identifying momentum or capitulation events.
Market odds can also be fetched via dedicated endpoints that return implied probabilities based on current prices. For example, if YES shares trade at $0.65 and NO shares at $0.35, the market is pricing a 65% probability for YES and 35% for NO (ignoring fees). These endpoints typically return data in milliseconds, making them suitable for real-time display or as input to probability-weighting algorithms. Traders often combine multiple Polymarket market prices with external data sources—political polling, sports statistics, economic forecasts—to identify mispriced outcomes and execute contrarian trades.
Rate limits on public endpoints generally allow 300 requests per minute per IP address or API key. Exceeding these limits results in HTTP 429 (Too Many Requests) responses. Best practice is to implement exponential backoff: if a request returns 429, wait 1 second, then 2 seconds, then 4 seconds, before retrying. This approach prevents thundering-herd scenarios where dozens of bots all spike requests at once, creating cascading failures.
Authenticated endpoints: Order placement, balance queries, and position management
Authenticated endpoints require API credentials and allow you to place orders, cancel orders, check your balance, and view your positions. To authenticate, your bot must generate an HMAC-SHA256 signature of the request payload and include it as a header. The signature usually encompasses the HTTP method, endpoint path, request body (if any), and a nonce or timestamp to prevent replay attacks. Polymarket’s API documentation specifies the exact signature format; deviating from it (for example, by signing only the URL or forgetting to include the request body) is a common source of authentication failures in production bots.
The orders endpoint allows POST requests to create a limit or market order. A typical order request includes the market ID, outcome (YES or NO), order type (LIMIT or MARKET), size in number of shares, and for limit orders, the price. The response includes an order ID, status (PENDING, ACCEPTED, FILLED, CANCELED), and the initial amount of pUSD you needed to send. Market orders execute immediately at the best available price; limit orders sit in the order book until a counterparty matches them or you cancel them. Polymarket’s pricing model means that placing a 100-share YES order at $0.60 requires you to send approximately 60 pUSD upfront, not 100 pUSD. The fee structure varies: international Polymarket charges taker fees of $1.00–$1.75 per 100 shares depending on market, with no maker fees, while Polymarket US may use a different fee structure under CFTC rules.
The positions endpoint returns your current holdings across all markets: how many YES shares, how many NO shares, at what average entry price, and current value. This data is critical for risk management. Before placing a new order, you should check your current positions to avoid accidental over-leverage or concentration in correlated events. For example, if you already hold 1,000 NO shares in a market at $0.40 average entry, and the market is now priced at $0.55, your position is underwater; adding more NO shares would increase your loss if the market continues upward. Position endpoints typically return data within a few hundred milliseconds, making them suitable for synchronous bot checks before each order.
The balance endpoint shows your available pUSD collateral, which directly limits your order-placing ability. If your balance is 500 pUSD and you want to buy 1,000 YES shares at $0.50, you need 500 pUSD—which means you can execute the order but would have zero balance remaining. Most robust bots maintain a safety buffer, refusing to place orders if remaining balance would fall below 10–20% of the order cost, reducing the risk of cascading failures if orders execute unfavorably or fees are higher than expected.
For higher-volume traders, polymarket provides WebSocket connections that stream order updates, fills, and position changes in real time rather than requiring polling. This reduces latency and server load compared to repeatedly calling REST endpoints. However, WebSocket connections are stateful and can be disrupted by network glitches, requiring you to implement reconnection logic and a state reconciliation process that periodically queries REST endpoints to verify that you have not missed events during a disconnection.
Building a market monitoring and arbitrage detection bot
A practical first bot integrates Polymarket’s public endpoints to monitor prices and detect arbitrage opportunities. The structure typically involves fetching the market list, then for each market, querying the orderbook endpoint to retrieve current bid-ask spreads. An arbitrage opportunity arises when prices across different markets for related outcomes diverge. For example, if Market A prices the US election outcome at 70% for Candidate X and Market B prices it at 65%, and assuming these markets should be perfectly correlated, you might place contrarian orders to exploit the difference.
More sophisticated arbitrage detection compares Polymarket’s prices against external prediction markets such as Manifest or other platforms, or against real-world odds quoted by sports books or financial institutions. If Polymarket prices an election outcome at 60% while mainstream betting markets price it at 55%, you might view this as a Polymarket overvaluation and short YES shares. This strategy requires integrating multiple data sources and handling timezone differences, API rate limits, and timing skew—the fact that prices across platforms may not update simultaneously.
Implementing this bot requires a few key components. First, a data-fetching layer that queries Polymarket’s markets and orderbook endpoints on a timer—perhaps every 5–10 seconds—and stores the results in a local cache. Second, a pricing-comparison layer that scores each market for arbitrage potential based on your criteria. Third, an order-execution layer that, upon detecting a candidate trade, places orders on Polymarket via the authenticated endpoints, checks fills, and manages positions. Fourth, a logging and monitoring layer that records all decisions and results for post-trade analysis.
A critical implementation detail is handling Polygon blockchain latency and finality. When you place an order via Polymarket’s API, the order is submitted to the blockchain as a smart contract transaction. Polygon typically produces blocks every 2 seconds, but network congestion or gas price spikes can cause delays. Your bot should not assume that an order is live immediately after the API returns a success response; instead, query the order status endpoint periodically to confirm that the order has been mined and is visible in the order book. If the order is not visible after 30 seconds, check gas prices and consider whether a higher fee might accelerate it.
Real-time order book streaming and latency optimization
For traders seeking microsecond-scale advantages, the WebSocket-based order book stream is more efficient than polling REST endpoints. Polymarket’s WebSocket API broadcasts live updates for bid-ask spreads, recent trades, and market status changes. A trader monitoring 20 markets via REST polling might make 20 requests every 5 seconds, consuming 240 requests per minute. The same trader using WebSocket receives all updates as they occur, with zero polling overhead and potentially 100–500 milliseconds lower latency.
Implementing WebSocket connections requires handling several edge cases. Network disruptions can cause a WebSocket to close without notice; your bot should attempt reconnection with exponential backoff (1 second, 2 seconds, 4 seconds, etc.) up to a maximum interval. During a reconnection, you miss updates; after reconnecting, you should immediately query the REST orderbook endpoint for each market to ensure your local state is synchronized. Some traders implement a hybrid model: use WebSocket for real-time updates during normal operation, but periodically (every 30–60 seconds) query REST endpoints as a sanity check.
Message filtering also improves efficiency. If you are only interested in markets with bid-ask spreads wider than 2%, you can filter updates client-side rather than processing every stream message. Conversely, if you are building a public dashboard, you might want to aggregate updates and republish them at a fixed interval (e.g., every 1 second) to reduce frontend churn and improve user experience.
Fee calculation, expected value analysis, and position sizing
Polymarket’s fee structure is not transparent at the point of order placement; traders must calculate fees manually or use the platform’s fee-calculation tools. On international Polymarket, taker fees range from $1.00 to $1.75 per 100 shares, meaning that if you buy 1,000 YES shares, you pay the market price for those shares (e.g., 600 pUSD for 1,000 shares at $0.60 each) plus approximately $10–$17.50 in fees. Maker fees are waived. The fee structure incentivizes limit-order placement: if you post a YES order at $0.59 when the market is trading at $0.60, you earn the spread without paying taker fees when someone matches your order.
Expected value (EV) analysis requires comparing the price you pay against the probability-adjusted payoff. If you believe an event has a 70% true probability but Polymarket prices it at $0.60 (implying 60% probability), the EV of a YES order is positive: you pay 0.60 pUSD for an expected 0.70 pUSD return, a 16.7% expected gain before fees. After subtracting the 1.75 pUSD taker fee per 100 shares (1.75%), your net expected return drops to approximately 15%, assuming you hold to resolution. Bots can automate this calculation by fetching market prices, combining them with a probability estimate from an external model, and only placing orders when EV exceeds a threshold (e.g., 10% minimum EV after fees).
Position sizing determines how much capital to allocate to each trade. A common approach is the Kelly Criterion, which dictates that you should allocate a fraction of your bankroll proportional to the edge and the odds. For a trade with 15% edge on a 70% probability outcome, the Kelly Criterion suggests risking approximately 15% / (70% / 30%) ≈ 6.4% of your bankroll. This sizing prevents over-leveraging on high-confidence trades while still allowing meaningful capital deployment. A bot implementing Kelly sizing would query the balance endpoint, calculate the dollar size for the recommended position, and place the corresponding market order.
Many traders implement a fractional Kelly approach (e.g., 25% Kelly) to reduce variance and account for model error. This is prudent given that Polymarket prices are influenced by crowd sentiment, media narratives, and liquidity conditions rather than purely by the objective truth. A bot that sizes positions too aggressively based on a model that is only 70% accurate can suffer large drawdowns during periods of model misjudgment.
Handling market resolution, oracle disputes, and settlement mechanics
When an event concludes, Polymarket’s market undergoes a resolution process managed by UMA’s Optimistic Oracle. The market creator (or a designated resolver) submits the outcome (YES or NO) on-chain. UMA’s protocol then allows a challenge period—typically 2 hours—during which anyone holding UMA tokens can dispute the resolution if they believe it is incorrect. If a dispute is filed, UMA’s vote-based escalation process begins, which can extend the timeline to days. Bots should not assume that a market resolves instantly; instead, they should poll the market status endpoint until the market transitions to a RESOLVED state with a final outcome.
A bot holding positions in a market during the resolution window faces uncertainty about timing. If your bot holds 1,000 YES shares and the market is under dispute, you cannot exit the position until UMA finalizes the outcome. This creates a timing risk: if the market ultimately resolves to NO, your position becomes worthless regardless of when you would have wanted to exit. To mitigate this, traders sometimes close positions before the event resolves, accepting a loss on the YES side in exchange for certainty. The trade-off depends on the probability you assign to each outcome and the value you place on avoiding extended lockup.
The settlement process involves converting resolved outcome tokens back to pUSD collateral. On Polygon, this occurs via a smart contract that burns your winning outcome tokens (e.g., YES shares if the market resolves to YES) and credits your account with the equivalent value in pUSD. The entire process—claim submission, dispute period, voting (if needed), and final settlement—can take 24–72 hours. Bots should not reinvest resolved proceeds immediately; instead, wait for the settlement to be confirmed on-chain before using those funds in new positions.
Risk management, error handling, and production deployment
A bot deployed in production must handle failures gracefully. Network timeouts, API rate-limit responses, blockchain reorgs, and order rejections are inevitable. Best practices include implementing retry logic with exponential backoff for transient errors, alerting mechanisms that notify you immediately if the bot enters an error state, and a kill switch that stops all trading if a critical error is detected. For example, if your balance query fails repeatedly, the bot should assume it cannot reliably manage risk and should pause order placement until the balance endpoint is responsive again.
State management is another critical consideration. A bot that crashes must be able to restart and reconstruct its position state from the blockchain and Polymarket’s API rather than relying on local files. This is because the blockchain is the source of truth; if your bot’s local state disagrees with on-chain state, the blockchain is correct. On restart, query the positions endpoint, compare it against your internal state, and reconcile any differences. If your local state recorded a 1,000-share YES position but the API shows 800 shares, you should log the discrepancy and update your internal state to match the API.
Fee and slippage handling deserves attention. When you place a market order for 1,000 shares at an average price of $0.60, the actual average execution price may be $0.62 due to market impact and fees. Your bot should estimate this slippage when sizing positions and track actual vs. estimated slippage over time to identify whether your models are accurate or systematically over-optimistic. If actual slippage is consistently 50% higher than estimated, your expected-value calculations are too bullish, and you may want to tighten entry requirements or reduce position sizes.
Testing before deployment is non-negotiable. Many traders begin with a testnet environment using dummy pUSD or start with paper trading—running the bot against live data but not actually placing orders. This allows you to identify logic errors, API integration problems, and edge cases without risking real capital. After paper trading for 100+ simulated trades, move to live trading with a small capital allocation (e.g., $100–$500) and increase size only after the bot has demonstrated consistent profitability over weeks or months.
Advanced strategies: Leverage, arbitrage across correlated markets, and perpetual futures
For traders seeking higher returns, Polymarket Perps offers leveraged perpetual futures contracts with up to 20x leverage. These are not available for all markets, but they enable traders to take directional positions on prediction outcomes without committing large amounts of collateral upfront. A 20x leveraged long position on an outcome means you control 20 times your margin, but a 5% adverse move wipes out your entire margin deposit. Bots trading Polymarket Perps require sophisticated risk management: position sizing must be significantly more conservative, liquidation monitoring is critical, and margin requirements must be checked before every order.
Arbitrage across correlated markets offers another opportunity. If a prediction market for “US GDP growth exceeds 3% in 2025” shows YES at $0.70, and another market for “US unemployment falls below 4% in 2025” shows YES at $0.65, a bot might construct a correlation trade by buying NO shares in the unemployment market and YES shares in the GDP market. If economic outcomes are positively correlated (strong growth typically lowers unemployment), this position profits if one market is repriced upward relative to the other. Implementing such strategies requires identifying correlated markets, calculating correlation coefficients, and managing multi-market positions simultaneously.
The challenge with these advanced strategies is increased complexity and correspondingly higher risk. A bug in your leverage calculation or a logic error in multi-market positioning can lead to catastrophic losses. Many professional traders use specialized frameworks or libraries (such as Arbitrage bots written in Python using libraries like ccxt or QuickFix) to standardize order placement, position tracking, and risk checks. For Polymarket specifically, custom integration is usually necessary given the uniqueness of prediction market mechanics.
Frequently asked questions
What is the difference between the international Polymarket API and the Polymarket US API?
The international Polymarket API serves users outside restricted jurisdictions (40+ countries including UK, France, Germany, Australia, Netherlands) and does not require KYC. The Polymarket US API is CFTC-regulated, requires KYC verification, and enforces US regulatory rules. Both operate on Polygon but use different endpoints, authentication schemas, and fee structures. Bots cannot reuse credentials across both instances; you must configure separate API keys for each.
How long does it take for a Polymarket market to resolve and settle after an event concludes?
After the real-world event concludes, the market creator submits a resolution claim to UMA’s Optimistic Oracle. There is typically a 2-hour challenge period; if no one disputes, the outcome is finalized and settlement occurs within 24 hours. If a dispute is filed, UMA’s voting and escalation process can extend the timeline to 3–7 days. Bots should poll the market status endpoint repeatedly rather than assuming instant settlement.
What fees does Polymarket charge, and how do they affect trading profitability?
International Polymarket charges taker fees of $1.00–$1.75 per 100 shares (approximately 1.0–1.75% per trade), with no maker fees. Polymarket US may use different fee structures under CFTC rules. These fees significantly impact bot profitability; a bot executing 10 trades per day with average 1.5% fees loses 15% of capital to fees alone over 100 days if P&L is flat. Bots should calculate expected value after fees and only place orders when edge exceeds 2–3 times the applicable fee rate.
Can I use the same bot code for prediction markets and Polymarket Perps?
No. Polymarket Perps (leveraged futures up to 20x) use different order types, margin mechanics, and liquidation rules compared to the standard binary outcome markets. Position sizing must be much more conservative for leveraged products, and bots must monitor margin levels continuously. It is recommended to build separate trading systems for standard prediction markets and leveraged perpetual futures until you have deep experience with both.