REST API Overview

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 Case	Recommended API
Real-time market data	gRPC Market Data Stream
Real-time order/trade updates	gRPC Order Stream
Order entry/cancellation	REST Trading API
Historical data queries	REST Report API
Account management	REST Accounts API
KYC and payments	REST Partner APIs

Base URLs

Environment	Base URL
Development	`https://api.dev01.polymarketexchange.com`
Pre-production	`https://api.preprod.polymarketexchange.com`
Production	`https://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/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 Group	Description	Streaming Alternative
Trading	Insert, cancel, and replace orders	-
Combos	Create and retrieve combo instruments (upcoming beta)	-
RFQs	Create, quote, accept, and confirm combo RFQs (upcoming beta)	RFQ Events Stream
Report	Search orders and trades, download history	Order Stream
Positions	Query account balances and positions	-
Reference Data	List instruments, symbols, and metadata	-
Order Book	Get order book depth and best bid/offer	Market Data Stream
Drop Copy	Execution feed and trade capture	Order Stream

Combos and RFQ APIs

Upcoming - beta access required. Combos and RFQ API endpoints are not generally available yet. Reach out to institutional@polymarket.us to join the beta test.

Use the Combos API to create and retrieve combo instruments. Use the RFQ API to create RFQs, quote RFQs, delete quotes, accept quotes, and confirm accepted quotes during last look. Use the RFQ Events Stream for real-time RFQ and quote lifecycle events instead of polling GetRFQs and GetQuotes.

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

Header	Required	Description
`Authorization`	Yes	`Bearer {access_token}`
`Content-Type`	Yes	`application/json`
`x-participant-id`	Conditional	Your 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/whoami to see your firm identity, or GET /v1/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 Status	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or expired token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limited
`500`	Internal 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 100 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

Overview

Health

Trading

Combos

RFQs

Report

Positions

Funding

Order Book

Reference Data

Accounts

Payments

Incentives

Streaming First Architecture

Base URLs

Authentication

API Groups

Trading APIs

Combos and RFQ APIs

Partner APIs

Partner Guide

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Price Representation

Rate Limits

Support

Next Steps

Quickstart Guide

Authentication

gRPC Streaming

Environments

​Streaming First Architecture

​Base URLs

​Authentication

​API Groups

​Trading APIs

​Combos and RFQ APIs

​Partner APIs

Partner Guide

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​Error Response

​Price Representation

​Rate Limits

​Support

​Next Steps

Quickstart Guide

Authentication

gRPC Streaming

Environments

Streaming First Architecture

Base URLs

Authentication

API Groups

Trading APIs

Combos and RFQ APIs

Partner APIs

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Price Representation

Rate Limits

Support

Next Steps