Skip to main content
The Polymarket US REST API provides programmatic access to trading, account management, market data, and funding operations.
This documentation is specific to Polymarket US. The international version can be found here.

​
Streaming First Architecture

Use gRPC Streaming for Real-Time DataFor production applications requiring continuous data updates, use the gRPC Streaming APIs instead of polling REST endpoints. Streaming provides:
  • Real-time updates as they happen
  • No rate limiting concerns
  • Lower latency than polling
  • Reduced infrastructure load
REST APIs are subject to rate limits and are best suited for one-time queries, historical data, and administrative operations.
Use CaseRecommended API
Real-time market datagRPC Market Data Stream
Real-time order/trade updatesgRPC Order Stream
Order entry/cancellationREST Trading API
Historical data queriesREST Report API
Account managementREST Accounts API
KYC and paymentsREST Partner APIs

​
Base URLs

EnvironmentBase URL
Developmenthttps://api.dev01.polymarketexchange.com
Pre-productionhttps://api.preprod.polymarketexchange.com
Productionhttps://api.prod.polymarketexchange.com
All endpoints use the /v1/ path prefix.

​
Authentication

All API requests require an access token in the Authorization header: 
curl -X GET "https://api.preprod.polymarketexchange.com/v1/accounts/whoami" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-participant-id: firms/YourFirm/users/your-user"
Access tokens expire every 3 minutes. Implement automatic token refresh in your application.
See the Authentication Setup Guide for complete authentication setup.

​
API Groups

​
Trading APIs

For direct trading operations. Used by all partners.
Endpoint GroupDescriptionStreaming Alternative
TradingInsert, cancel, and replace orders-
ReportSearch orders and trades, download historyOrder Stream
PositionsQuery account balances and positions-
Reference DataList instruments, symbols, and metadata-
Order BookGet order book depth and best bid/offerMarket Data Stream
Drop CopyExecution feed and trade captureOrder Stream

​
Partner APIs

For partners building retail trading platforms with end-user onboarding, KYC, and payments.

Partner Guide

Complete guide for partners including Accounts, KYC, and Payments APIs
Which APIs do I need?
  • Direct trading partners: Use the Trading APIs documented in this section
  • Retail partners: Use Trading APIs plus the Partner Guide APIs

​
Request Format

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer {access_token}
Content-TypeYesapplication/json
x-participant-idConditionalYour participant ID (required for trading, positions, and report endpoints)
When is x-participant-id required?
  • Required for all account-scoped endpoints: trading, positions, reports, and account operations
  • Not required for market data, order book, reference data, and instrument state endpoints
If you don’t know your participant ID, call GET /v1/accounts/whoami to see your firm identity, or GET /v1/accounts/users to list all users and their IDs. See Accounts & Identity for details.

​
Request Body

POST requests accept JSON bodies: 
{
  "symbol": "tec-nfl-sbw-2026-02-08-kc",
  "side": "SIDE_BUY",
  "order_qty": 100,
  "price": 550,
  "type": "ORDER_TYPE_LIMIT",
  "time_in_force": "TIME_IN_FORCE_GOOD_TILL_CANCEL"
}

​
Response Format

​
Success Response

{
  "order": {
    "id": "ord_abc123",
    "symbol": "tec-nfl-sbw-2026-02-08-kc",
    "state": "ORDER_STATE_NEW",
    "order_qty": 100,
    "leaves_qty": 100,
    "cum_qty": 0
  }
}

​
Error Response

{
  "code": 3,
  "message": "invalid order quantity",
  "details": []
}
HTTP StatusMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or expired token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limited
500Internal Server Error

​
Price Representation

All prices are represented as int64 values. Divide by the instrument’s price_scale to get the decimal price: 
# Get price_scale from instrument metadata
instrument = get_instrument("tec-nfl-sbw-2026-02-08-kc")
price_scale = instrument.price_scale  # e.g., 1000

# Convert API price to decimal
decimal_price = api_price / price_scale
# 550 / 1000 = 0.55 ($0.55)
Query price_scale from the Reference Data API and cache it for each instrument.

​
Rate Limits

Trading endpoints are rate-limited at 250 requests per second per firm, averaged over a 1-minute window (short bursts above this rate are allowed). Query endpoints have lower per-endpoint limits. Public (unauthenticated) endpoints are limited to 20 requests per second per IP. See Rate Limits for the full breakdown by endpoint and protocol.

​
Support

For REST API questions or issues, contact onboarding@qcex.com.

​
Next Steps

Quickstart Guide

Place your first order in 5 minutes

Authentication

Set up Private Key JWT authentication

gRPC Streaming

Real-time market data and order updates

Environments

API endpoints for dev, preprod, and prod