Polymarket US API Guide (2026)

This guide covers the Polymarket US API exclusively. For the Polymarket Global (crypto-native) API on Polygon, see the Polymarket API Guide. For a side-by-side comparison, see Polymarket US vs. Global API.

Overview

Polymarket US is a CFTC-regulated prediction market platform, operated via QCX LLC (a designated contract market) and QC Clearing LLC. The platform launched invite-only on December 3, 2025, opened public API access on February 16, 2026, and removed the iOS waitlist in May 2026. It operates at api.polymarket.us with a unified REST + WebSocket architecture, Ed25519 authentication, and KYC-gated access for US developers and users.

The API surface is designed to be developer-friendly: a full REST surface spanning core trading resource groups (Markets, Orders, Events, Portfolio, Account) plus Series, Sports, Tags, Search, Combos, RFQs, and Incentives, 2 WebSocket endpoints for real-time data, slug-based market identification (no token IDs), and SDKs that handle cryptographic signing internally.

KYC Onboarding

API access requires full KYC verification. There is no sandbox, demo, or unauthenticated access mode.

Steps:

1. Download the Polymarket US iOS app
2. Complete identity verification: government-issued photo ID, Social Security Number, proof of address
3. Wait for approval (typically minutes to hours)
4. Navigate to polymarket.us/developer in your browser
5. Generate an Ed25519 API keypair
6. Store the private key immediately — it is shown exactly once and cannot be recovered

The developer portal is web-based, but the KYC flow is iOS-only as of September 2026. Android and web-based KYC are not yet available. Polymarket US launched invite-only on December 3, 2025 and removed the iOS waitlist in May 2026 — the iOS app is open to all US users with no invite code.

Agent operators: Each API keypair is tied to a KYC-verified identity. If you are running autonomous agents, the legal entity behind the KYC is responsible for all trading activity. See the Agent Wallet Legal Liability Guide for implications.

Authentication: Ed25519

Polymarket US uses Ed25519 keypair authentication — the same primitive used by Solana, SSH, and many modern APIs. The SDK signs every request automatically with your private key.

from polymarket_us import PolymarketUS
import os

client = PolymarketUS(
    key_id=os.getenv("POLYMARKET_US_KEY_ID"),       # UUID from developer portal
    secret_key=os.getenv("POLYMARKET_US_SECRET"),    # Base64-encoded Ed25519 private key
)

There is no two-level auth system (unlike the Global API’s L1/L2 EIP-712 + HMAC flow). The SDK constructs, signs, and submits requests in a single step.

Key management:

• Store credentials in environment variables, never in code
• The private key cannot be recovered — if lost, generate a new keypair
• Timestamps must be within 30 seconds of server time — keep your clock NTP-synced

Raw request headers. If you skip the SDK and sign requests yourself, every authenticated request carries three headers:

SDK Installation

Python

pip install polymarket-us

Requires Python 3.10+. Supports both sync (PolymarketUS) and async (AsyncPolymarketUS) clients.

TypeScript

npm install polymarket-us

Requires Node 18+. Same resource-oriented design as the Python SDK.

REST API Endpoints

The core trading endpoints fall into 5 resource groups, documented below. The full surface also covers Series, Sports (leagues, teams, events), Tags, Search, Combos, RFQs, and Incentives — see the official reference. All endpoints route through https://api.polymarket.us.

Markets (Public)

Markets are referenced by human-readable slugs (e.g., "btc-100k-2025") rather than token IDs.

markets = client.markets.list({"limit": 10, "active": True})
for market in markets.get("markets", []):
    print(f"{market['slug']}: YES={market.get('yesPrice')} NO={market.get('noPrice')}")

book = client.markets.orderbook("btc-100k-2025")

Events (Public)

Events group related markets. An event like “2026 World Cup Winner” contains individual markets for each team.

Orders (Authenticated)

Order placement:

order = client.orders.create({
    "marketSlug": "btc-100k-2025",
    "intent": "ORDER_INTENT_BUY_LONG",      # BUY YES
    "type": "ORDER_TYPE_LIMIT",
    "price": {"value": "0.55", "currency": "USD"},
    "quantity": 100,
    "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
})
print(order)

Intent mapping:

Time-in-force options: TIME_IN_FORCE_GOOD_TILL_CANCEL (GTC), TIME_IN_FORCE_FILL_OR_KILL (FOK)

Portfolio (Authenticated)

positions = client.portfolio.positions()
balance = client.portfolio.balance()

Account (Authenticated)

Combos and RFQs

Two newer resource groups matter for bot builders. Combos let you create and trade multi-leg combination instruments — creation is quota-limited to 1,000 combos per week per account, so treat combo creation as a scarce resource and reuse existing combos where one already matches your legs. RFQs (request-for-quote) provide a negotiated-fill flow for size that would move the book: submit a quote request, receive quotes, then accept and confirm the best one. Both groups sit behind the same Ed25519 auth and the same 20 req/sec limit; see the official reference for the full schemas.

Sports Endpoints

The Sports resource group exposes leagues, teams, and events-by-league (e.g., /v1/sports/leagues), which makes it the natural discovery layer for sports-market bots — resolve a league to its events, then events to markets, instead of filtering the global market list. If your agent spans sportsbooks and prediction markets, this is the bridge: pull Polymarket US sports markets here and compare pricing against sportsbook odds via the cross-market arbitrage guide.

WebSocket Endpoints (2)

WebSocket connections are essential for real-time strategies. Even at 20 requests/second, REST polling across many markets burns your rate-limit budget fast — stream instead.

Market WebSocket (Public)

Endpoint: wss://api.polymarket.us/v1/ws/markets

Streams real-time market data: price updates, order book changes, and trade notifications. Subscribe to up to 10 instruments per connection.

import asyncio
from polymarket_us import AsyncPolymarketUS

async def stream_markets():
    async with AsyncPolymarketUS(
        key_id="your-key-id",
        secret_key="your-secret-key",
    ) as client:
        events = await client.events.list({"limit": 5, "active": True})
        print(events)

asyncio.run(stream_markets())

Private WebSocket (Authenticated)

Endpoint: wss://api.polymarket.us/v1/ws/private

Streams your personal trading activity: order fills, cancellations, position changes. Requires Ed25519 authentication.

Rate Limits

The Retail API enforces a global rate limit of 20 requests per second per API key across all endpoints. Strategies:

• Use WebSocket for all real-time data — do not poll REST endpoints
• Batch order operations with POST /v1/orders/batch instead of individual order calls (up to 20 orders per batch)
• Cache market metadata locally and refresh on a timer (market slugs and event structure change infrequently)
• Use exponential backoff on 429 responses

The 5-second latency stopgap. During elevated latency, Polymarket US rejects any new order or cancel/replace not processed within 5 seconds of receipt, protecting you from fills at stale prices. These rejects carry the message Global Rate Limit Exceeded but are not rate limits — do not throttle in response. Pure cancels are never rejected by the stopgap, and you can cancel an order before receiving its acknowledgement.

For higher production rate limits, document your use case and email [email protected]. For direct market access, the Exchange Gateway provides REST, gRPC (including streaming market data, order, and drop-copy streams), and FIX, authenticated via Private Key JWT — onboarding runs through the official docs flow at docs.polymarket.us.

Trading Fees

Effective July 1, 2026, fees follow a symmetric formula that scales with price uncertainty:

Fee = Θ × C × p × (1 − p)

Fees peak at 50¢ and fall toward zero at the extremes — buying 100 contracts at $0.10 costs $0.54 in taker fees; at $0.50 it costs $1.50. Makers are paid, not charged. High-volume takers earn rebates on the prior calendar month’s taker volume: 10% at $250K+, 25% at $1M+, 50% at $10M+. Bots should price the taker fee into every edge calculation — a 1-cent edge at midpoint prices is roughly half fee.

Common Patterns for Agents

Market Scanner

from polymarket_us import PolymarketUS
import os

client = PolymarketUS(
    key_id=os.getenv("POLYMARKET_US_KEY_ID"),
    secret_key=os.getenv("POLYMARKET_US_SECRET"),
)

markets = client.markets.list({"limit": 50, "active": True})
for m in markets.get("markets", []):
    yes_price = float(m.get("yesPrice", 0.5))
    if yes_price < 0.10 or yes_price > 0.90:
        print(f"High-conviction market: {m['slug']} (YES={yes_price})")

Position Monitor

positions = client.portfolio.positions()
balance = client.portfolio.balance()

print(f"Balance: ${balance.get('available', 0)}")
for pos in positions:
    print(f"  {pos['marketSlug']}: {pos['quantity']} shares @ ${pos['avgPrice']}")

Key Differences from Polymarket Global

If you are coming from the Global API, these are the critical differences:

For a complete migration guide, code-level comparison, and dual-stack agent pattern, see Polymarket US vs. Global API.

Troubleshooting

“Private key displayed only once” — key lost: Generate a new keypair from the developer portal. There is no recovery mechanism.

Auth errors (401): Check that your server clock is NTP-synced. Ed25519 signatures include timestamps, and timestamps must be within 30 seconds of server time.

Rate limited (429): The 20 req/sec per-key limit is strict. Switch to WebSocket for real-time data. Use batch order endpoints for multiple order operations. Note that a Global Rate Limit Exceeded message on an order during elevated latency may be the 5-second stopgap (see Rate Limits above), not a true rate limit — do not throttle in response.

KYC not completing: The KYC flow is iOS-only as of September 2026. Ensure you use the same authentication method (Apple, Google, or email) on both the iOS app and the developer portal to avoid account mismatches.

Markets missing: Not all Global Polymarket markets exist on the US platform. The CFTC-regulated market set is more conservative — fewer markets, particularly around politically sensitive topics.

See Also

• Polymarket US vs. Global API — Migration & Dual-Stack Guide
• Polymarket US vs. Offshore API Comparison
• Polymarket API Guide (Global)
• Prediction Market API Reference
• Agent Wallet Legal Liability
• Agent Wallet Comparison
• Cross-Market Arbitrage Guide
• Polymarket US Changelog

This guide is maintained by AgentBets.ai. Found an error or API change we missed? Let us know on Twitter.

Not financial advice. Built for builders.