Polymarket US API Guide: Endpoints, Auth, Rate Limits & Python SDK (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 that launched public API access on February 16, 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: 23 REST endpoints organized into 5 resource groups, 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 March 2026. Android and web-based KYC are not yet available.

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
• Ed25519 signatures include timestamps; keep your server clock NTP-synced to prevent auth failures

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 (23)

The Polymarket US API organizes its 23 endpoints into 5 resource groups. 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)

WebSocket Endpoints (2)

WebSocket connections are essential for real-time strategies. The 60 req/min REST limit makes polling impractical.

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 60 req/min limit applies across all REST endpoints for a given API key. 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
• Cache market metadata locally and refresh on a timer (market slugs and event structure change infrequently)
• Use exponential backoff on 429 responses

For higher throughput requirements, the Exchange Gateway provides FIX 4.4 protocol access with institutional-grade rate limits. Contact [email protected] for access.

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; even a few seconds of drift causes rejection.

Rate limited (429): The 60 req/min limit is strict. Switch to WebSocket for real-time data. Use batch order endpoints for multiple order operations.

KYC not completing: The KYC flow is iOS-only as of March 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 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.