Orders API

The Orders API provides order entry and management capabilities for trading on markets.

Authentication RequiredAll Orders API endpoints require API key authentication. See the Authentication guide for details on signing requests.

Base URL

https://api.polymarket.us

Endpoints

Order Entry

Method	Endpoint	Description
`POST`	`/v1/orders`	Create a new order
`POST`	`/v1/order/preview`	Preview order before submission
`POST`	`/v1/order/close-position`	Close an existing position

Order Query

Method	Endpoint	Description
`GET`	`/v1/orders/open`	Get all open orders
`GET`	`/v1/order/{orderId}`	Get a specific order by ID

Order Management

Method	Endpoint	Description
`POST`	`/v1/order/{orderId}/modify`	Modify an existing order
`POST`	`/v1/order/{orderId}/cancel`	Cancel a specific order
`POST`	`/v1/orders/open/cancel`	Cancel all open orders

Batched Operations

Up to 20 orders per call.

Method	Endpoint	Description
`POST`	`/v1/orders/batched`	Create up to 20 orders in a single request
`POST`	`/v1/orders/batched/cancel`	Cancel up to 20 specific orders by ID
`POST`	`/v1/orders/batched/modify`	Modify up to 20 existing orders (each forwarded to the exchange as a cancel-replace)

Note: /v1/orders/open/cancel cancels all of your open orders (optionally filtered by market). Use /v1/orders/batched/cancel when you want to cancel a specific list of order IDs.

Batched responses do not confirm per-entry success.

Gateway validation is atomic: if any entry fails request-shape checks (missing orderId, batch > 20, etc.), the whole batch is rejected with 400.
The exchange processes entries independently. An unknown orderId in a batched cancel or modify is silently ignored.
canceledOrderIds and modifiedOrderIds echo the request; they do not certify that each ID was acted on. For real outcomes, subscribe to the Private WebSocket order stream and watch for EXECUTION_TYPE_REPLACE, EXECUTION_TYPE_CANCELED, and EXECUTION_TYPE_REJECTED.
createdOrderIds from /v1/orders/batched are real exchange-assigned IDs, but per-order accept/fill/reject events still come via the order stream.

Order Types

All enum values are passed as strings in the request body:

Value	Description
`ORDER_TYPE_LIMIT`	Limit order at specified price
`ORDER_TYPE_MARKET`	Market order executed at best available price

Example:

{
  "type": "ORDER_TYPE_LIMIT"
}

Order Intent

Orders require an intent indicating position direction. Pass these as string values:

Value	Description
`ORDER_INTENT_BUY_LONG`	Buy YES contracts (go long on Yes outcome)
`ORDER_INTENT_SELL_LONG`	Sell YES contracts (close long Yes position)
`ORDER_INTENT_BUY_SHORT`	Buy NO contracts (go long on No outcome)
`ORDER_INTENT_SELL_SHORT`	Sell NO contracts (close long No position)

Example - Buy NO contracts:

{
  "marketSlug": "your-market-slug",
  "type": "ORDER_TYPE_LIMIT",
  "price": { "value": "0.45", "currency": "USD" },
  "quantity": 10,
  "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
  "intent": "ORDER_INTENT_BUY_SHORT"
}

Alternative: Outcome Side + Action

Instead of intent, you can specify the equivalent outcomeSide + action pair. Both forms are accepted on CreateOrder and the batched variants. If both are sent, outcomeSide+action wins.

`outcomeSide`	`action`	Equivalent `intent`
`OUTCOME_SIDE_YES`	`ORDER_ACTION_BUY`	`ORDER_INTENT_BUY_LONG`
`OUTCOME_SIDE_YES`	`ORDER_ACTION_SELL`	`ORDER_INTENT_SELL_LONG`
`OUTCOME_SIDE_NO`	`ORDER_ACTION_BUY`	`ORDER_INTENT_BUY_SHORT`
`OUTCOME_SIDE_NO`	`ORDER_ACTION_SELL`	`ORDER_INTENT_SELL_SHORT`

Example: same “buy NO contracts” order, expressed with outcomeSide + action:

{
  "marketSlug": "your-market-slug",
  "type": "ORDER_TYPE_LIMIT",
  "price": { "value": "0.45", "currency": "USD" },
  "quantity": 10,
  "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
  "outcomeSide": "OUTCOME_SIDE_NO",
  "action": "ORDER_ACTION_BUY"
}

The Order returned by GET /v1/order/{orderId} and GET /v1/orders/open includes both intent and outcomeSide+action, so you can read whichever you prefer. The price-vs-side rules below apply to both forms.

Understanding Price with Order Intent

Only the long side (YES) is directly tradable. The short side (NO) is synthetic exposure created through positions in the long side. The price.value field always represents the long side’s price, regardless of which order intent you use. In the market slug, the first team is always the long/YES side and the second team is the short/NO side. A common mistake is attempting to buy both YES at 0.60 and NO at 0.40, which causes a self-match error. Since YES and NO prices must sum to $1.00, buying NO at 0.40 is equivalent to buying YES at 0.60 - you’re placing two buy orders at the same price level on the same instrument. If you want exposure to both sides, use different price levels (e.g., buy YES at 0.55 and buy NO at 0.50). Example: For market aec-cbb-usc-iowa-2026-01-28:

YES (long side) = USC
NO (short side) = Iowa
price.value always refers to USC’s price

How This Affects Your Orders:

You Want To	Order Intent	price.value
Buy USC at 0.83	ORDER_INTENT_BUY_LONG	0.83
Sell USC at 0.83	ORDER_INTENT_SELL_LONG	0.83
Buy Iowa at 0.83	ORDER_INTENT_BUY_SHORT	0.17
Sell Iowa at 0.83	ORDER_INTENT_SELL_SHORT	0.17

In binary markets, YES and NO are inverses: buying NO at 0.83 is equivalent to buying YES at 0.17 (1.00 - 0.83). Since price.value always represents the YES side, you must set it to 0.17 when trading Iowa (NO) at 0.83. To trade the NO side at any price X, set price.value = 1.00 - X.

Price Validation

Orders must have price.value between 0.01 and 0.99 (the exchange’s absolute price limits). Invalid prices (below 0.01 or above 0.99) are restricted at the exchange level. Since the order is sent to the exchange, you will still receive an orderID, but the order will never fill because it gets rejected during validation. Example:

{
  "price": {"value": "45", "currency": "USD"}  // Invalid - will receive orderID but order rejected
}

Always validate price bounds client-side before submission to avoid unnecessary orderIDs for rejected orders.

Quantity and Tick Size by Market

Markets can differ in both minimum order quantity and minimum price increment. Read these fields from the market response before submitting or modifying an order:

Market field	Use
`minimumTradeQty`	Smallest valid `quantity`, expressed in contracts. A value of `0.01` means 1% of a contract.
`orderPriceMinTickSize`	Smallest valid `price.value` increment. A value of `0.005` means half-cent ticks.

The quantity field on order requests and order responses is a number and can contain decimals for partial-contract markets. Submit quantity and price.value already aligned to the market’s minimumTradeQty and orderPriceMinTickSize. Extra precision is not part of the public contract and can be normalized to the market precision; for example, on a market with minimumTradeQty: 0.01 and orderPriceMinTickSize: 0.01, quantity: 0.015 can be accepted and returned as 0.01, and price.value: "0.515" can be returned as "0.51".

Order Side

The order side indicates buy or sell direction:

Value	Description
`ORDER_SIDE_BUY`	Buy order
`ORDER_SIDE_SELL`	Sell order

Order States

Orders progress through these states:

PENDING_NEW → PARTIALLY_FILLED → FILLED
                    ↓
                CANCELED / REJECTED / EXPIRED

Value	Description
`ORDER_STATE_PENDING_NEW`	Order received, not yet processed by matching engine
`ORDER_STATE_NEW`	Order accepted by matching engine and resting on the book
`ORDER_STATE_PENDING_REPLACE`	Modify request received, not yet processed
`ORDER_STATE_PENDING_CANCEL`	Cancel request received, not yet processed
`ORDER_STATE_PENDING_RISK`	Order pending risk approval
`ORDER_STATE_PARTIALLY_FILLED`	Order partially executed
`ORDER_STATE_FILLED`	Order fully executed
`ORDER_STATE_CANCELED`	Order canceled
`ORDER_STATE_REPLACED`	Order replaced via modify (cancel-replace)
`ORDER_STATE_REJECTED`	Order rejected by exchange
`ORDER_STATE_EXPIRED`	Order expired (GTD orders)

Time in Force

Value	Description
`TIME_IN_FORCE_DAY`	DAY - Expires at the end of the trading day
`TIME_IN_FORCE_GOOD_TILL_CANCEL`	GTC - Remains active until filled or canceled
`TIME_IN_FORCE_GOOD_TILL_DATE`	GTD - Expires at specified `goodTillTime`
`TIME_IN_FORCE_IMMEDIATE_OR_CANCEL`	IOC - Fills immediately available quantity, cancels rest
`TIME_IN_FORCE_FILL_OR_KILL`	FOK - Must fill entirely or cancel completely

Manual Order Indicator

Required to indicate whether the order is placed by a human or automated system:

Value	Description
`MANUAL_ORDER_INDICATOR_MANUAL`	Order placed manually by a user
`MANUAL_ORDER_INDICATOR_AUTOMATIC`	Order placed by an automated trading system

Execution Types

Execution events returned in synchronous order responses:

Value	Description
`EXECUTION_TYPE_NEW`	Order accepted (new working order confirmation)
`EXECUTION_TYPE_PARTIAL_FILL`	Order partially filled
`EXECUTION_TYPE_FILL`	Order fully filled
`EXECUTION_TYPE_CANCELED`	Order canceled
`EXECUTION_TYPE_REPLACE`	Order replaced/modified
`EXECUTION_TYPE_REJECTED`	Order rejected
`EXECUTION_TYPE_EXPIRED`	Order expired
`EXECUTION_TYPE_DONE_FOR_DAY`	Order done for the trading day

Order Reject Reasons

If an order is rejected, the reason will be one of:

Value	Description
`ORD_REJECT_REASON_EXCHANGE_OPTION`	Generic exchange-defined reason (used when no more specific code applies)
`ORD_REJECT_REASON_UNKNOWN_MARKET`	Unknown or invalid market
`ORD_REJECT_REASON_EXCHANGE_CLOSED`	Exchange/market is closed
`ORD_REJECT_REASON_INCORRECT_QUANTITY`	Invalid quantity
`ORD_REJECT_REASON_INVALID_PRICE_INCREMENT`	Price not on valid increment
`ORD_REJECT_REASON_INCORRECT_ORDER_TYPE`	Invalid order type for market
`ORD_REJECT_REASON_PRICE_OUT_OF_BOUNDS`	Price outside valid range
`ORD_REJECT_REASON_NO_LIQUIDITY`	No liquidity for market order

Slippage Tolerance

For market orders or close position orders, you can specify slippage tolerance:

{
  "slippageTolerance": {
    "currentPrice": { "value": "0.50", "currency": "USD" },
    "ticks": 5
  }
}

Field	Type	Description
`currentPrice`	Amount	Reference price for slippage calculation
`bips`	integer	Slippage tolerance in basis points (1 bip = 0.01%)
`ticks`	integer	Slippage tolerance in price ticks (takes priority over bips)

Default Values

slippageTolerance is optional and defaults to:

Market orders: Unlimited (no slippage protection by default)
Limit orders: Not applicable (price is fixed)

Slippage tolerance defines the maximum price movement you’ll accept. For example, if you submit a market order to buy at current price 0.50 with ticks: 5, the order will reject if the best ask moves above 0.55 before execution.

Real-Time Order UpdatesAfter submitting orders via REST, use the WebSocket Private Stream to receive real-time updates on order status, fills, and cancellations.

Complete Create Order Example

{
  "marketSlug": "your-market-slug",
  "type": "ORDER_TYPE_LIMIT",
  "price": {
    "value": "0.555",
    "currency": "USD"
  },
  "quantity": 0.5,
  "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
  "intent": "ORDER_INTENT_BUY_LONG",
  "manualOrderIndicator": "MANUAL_ORDER_INDICATOR_MANUAL",
  "participateDontInitiate": false
}

Rate Limits

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

Rate Limit ExceededWhen rate limits are exceeded, the API returns HTTP status 429 Too Many Requests.

Notes:

Rate limits are enforced at the edge (Cloudflare) before requests reach the API
Limits are applied per API key
Implement exponential backoff and request throttling in your application

Best Practices

Use string enum values - All enums are passed as strings (e.g., "ORDER_TYPE_LIMIT", not 1)
Use WebSocket for updates - Subscribe to order updates instead of polling
Preview before submit - Use the preview endpoint for order validation
Handle rejects - Implement proper error handling for rejected orders
Use asynchronous execution for limit orders - For market-making and resting limit orders, avoid synchronousExecution: true as it waits up to 10 seconds for final order state. Instead, submit orders asynchronously (the default) and poll with GET /v1/order/{orderId} to check status (~100ms). Only use synchronousExecution: true for immediately-fillable orders where you need to wait for fill confirmation.
Specify manual order indicator - Required for regulatory compliance
Respect rate limits - Implement request throttling to stay within rate limits and avoid 429 errors

Getting Started

Orders

Portfolio

Events

Markets

Series

Sports

Sports (Legacy)

Tags

Search

Incentives

Orders API Overview

Orders API

Base URL

Endpoints

Order Entry

Order Query

Order Management

Batched Operations

Order Types

Order Intent

Alternative: Outcome Side + Action

Understanding Price with Order Intent

Price Validation

Quantity and Tick Size by Market

Order Side

Order States

Time in Force

Manual Order Indicator

Execution Types

Order Reject Reasons

Slippage Tolerance

Default Values

Complete Create Order Example

Rate Limits

Best Practices

​Orders API

​Base URL

​Endpoints

​Order Entry

​Order Query

​Order Management

​Batched Operations

​Order Types

​Order Intent

​Alternative: Outcome Side + Action

​Understanding Price with Order Intent

​Price Validation

​Quantity and Tick Size by Market

​Order Side

​Order States

​Time in Force

​Manual Order Indicator

​Execution Types

​Order Reject Reasons

​Slippage Tolerance

​Default Values

​Complete Create Order Example

​Rate Limits

​Best Practices

Orders API

Base URL

Endpoints

Order Entry

Order Query

Order Management

Batched Operations

Order Types

Order Intent

Alternative: Outcome Side + Action

Understanding Price with Order Intent

Price Validation

Quantity and Tick Size by Market

Order Side

Order States

Time in Force

Manual Order Indicator

Execution Types

Order Reject Reasons

Slippage Tolerance

Default Values

Complete Create Order Example

Rate Limits

Best Practices