Order Management

Query your order history and cancel pending limit orders.

Order Endpoints Summary

PolySimulator offers two order placement endpoints. Use the one that fits your workflow:

Endpoint	Best For	Time-in-force Field	Supported Values
`POST /v1/orders`	New bots, full features	`time_in_force`	`GTC` (default for limit), `IOC` (default for market), `FAK` (normalised to `IOC`), `FOK`, `GTD` (limit only, requires `expiration`)
`POST /v1/clob/order`	Polymarket migration	`order_type`	`GTC` (default), `FOK`, `GTD` (requires `order.expiration`). `IOC`/`FAK` are not accepted here

Key difference: The native /v1/orders endpoint uses order_type for market/limit and time_in_force for GTC/FOK/IOC. It also accepts FAK (Polymarket’s term for IOC) and normalises it to IOC — so a listed order may show time_in_force: "IOC" even though you sent FAK. The CLOB-compatible endpoint uses order_type for the time-in-force policy (matching Polymarket’s schema). See CLOB Compatibility for the CLOB endpoint schema.

POST /v1/clob/order does not support every PM order type. order_type=IOC is rejected with 400 UNSUPPORTED_ORDER_TYPE (the engine only enforces FOK worst-price semantics; routing IOC through it would silently behave like FOK). Use GTC (rests on the book), GTD (rests until its expiration) or FOK (immediate-or-fail) here, or the native POST /v1/orders for IOC.

GTD and post-only are live on both endpoints (since 2026-06-16, see Placing Orders). order_type=GTD on /v1/clob/order (time_in_force=GTD on /v1/orders) is a true Good-Til-Date: the order carries a unix-seconds expiration, the matching engine skips and auto-cancels it once that timestamp passes (the cancelled row carries cancelled_reason: "gtd_expired"), and an expiration that is missing or already in the past is rejected at placement with 400 INVALID_ORDER_EXPIRATION. Polymarket’s postOnly (post_only on /v1/orders) makes a GTC/GTD limit reject-if-marketable: an order that would cross the book is refused with 400 INVALID_POST_ONLY_ORDER instead of filling.

List Orders

GET /v1/orders

Returns your full order stream — both kinds merged into one list:

Pending limit orders — unfilled GTC orders still resting on the book.
Filled / cancelled orders — executed or terminated trades.

Both types share the same OrderItem response shape. Supports offset and cursor-based pagination.

Tracking Order Fills and Cancellations: REST polling remains the authoritative source for order state and cancellations. WebSocket execution streams (WS /v1/ws/executions and WS /v1/ws/user) deliver low-latency fill notifications for fills from every matching process, including the background matcher. They are fill-only (no cancellation events) and at-least-once, so de-duplicate fills and reconcile through REST after a reconnect (see Execution Feed). To avoid 429 rate limit rejections, observe the Safe Order Polling Contract (authoritative REST polling at minimum 1–2s intervals with jitter, batch status endpoints, and honoring Retry-After).

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter: `PENDING`, `FILLED`, `CANCELLED`, `EXPIRED`
`market_id`	string	—	Filter by condition_id
`side`	string	—	Filter: `BUY`, `SELL`
`limit`	int	50	Max results (1–200)
`offset`	int	0	Pagination offset (ignored when `cursor` is set)
`cursor`	string	—	ISO-8601 timestamp for cursor pagination (preferred for bots)

Response Fields

Field	Type	Description
`order_id`	int	Order identifier. Orders and fill rows use separate id sequences, so the same number can exist in both; see Get a Single Order.
`market_id`	string	Market condition_id
`side`	string	`BUY` or `SELL`
`outcome`	string	Outcome label (e.g. `Yes`, `No`)
`order_type`	string	`market` or `limit`
`limit_price`	string \| null	Limit order price (null for market orders)
`quantity`	string	Order size in shares
`time_in_force`	string	`GTC`, `FOK`, or `IOC`. A `FAK` order is normalised server-side, so it surfaces here as `IOC`. With the PM-semantics rollout, `GTD` also appears here for date-expiring resting limits.
`status`	string	`PENDING`, `FILLED`, `CANCELLED`, or `EXPIRED` (PolySimulator-native enum). See the order-status table. PM-SDK ports read the `ORDER_STATUS_*` enum from `GET /v1/data/orders`.
`client_order_id`	string \| null	Your idempotency key
`created_at`	string	ISO-8601 creation timestamp
`filled_at`	string \| null	ISO-8601 fill timestamp (null if unfilled)
`fill_price`	string \| null	Execution price (null if unfilled)
`cancelled_at`	string \| null	ISO-8601 cancellation timestamp
`hold_reason`	string \| null	Why an open order is not being matched right now. `venue_outage` means Polymarket is down and matching is paused — the order keeps its place, and matching resumes when the venue recovers, with nothing to re-place. It is still an ordinary resting order in the meantime, so it can expire (GTD), be cancelled, or be swept if its market resolves before that happens. `null` whenever matching is running normally, which is the usual case. See `VENUE_UNAVAILABLE`.

Examples

curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/orders?status=PENDING&limit=20&offset=0"

# Use next_cursor from the previous response — it is urlsafe-base64
# (URL-safe by construction; no percent-encoding needed)
curl -H "X-API-Key: $API_KEY" \
  "https://api.polysimulator.com/v1/orders?limit=20&cursor=MjAyNi0wMi0wNlQxMjowMDowMCswMDowMA"

import requests

API_KEY = "ps_live_..."
BASE = "https://api.polysimulator.com/v1"
headers = {"X-API-Key": API_KEY}

all_orders = []
cursor = None

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get(f"{BASE}/orders", headers=headers, params=params)
    data = resp.json()
    all_orders.extend(data["orders"])
    if not data["has_more"]:
        break
    cursor = data["next_cursor"]

print(f"Fetched {len(all_orders)} orders")

Response

{
  "orders": [
    {
      "order_id": 15,
      "market_id": "0x1a2b3c...",
      "side": "BUY",
      "outcome": "Yes",
      "order_type": "limit",
      "limit_price": "0.60",
      "quantity": "10.0",
      "time_in_force": "GTC",
      "status": "PENDING",
      "client_order_id": "limit-001",
      "created_at": "2026-02-06T12:00:00+00:00",
      "filled_at": null,
      "fill_price": null,
      "cancelled_at": null
    }
  ],
  "next_cursor": "MjAyNi0wMi0wNlQxMTo1NTowMCswMDowMA",
  "has_more": true,
  "total_hint": 137
}

The envelope is {orders, has_more, next_cursor, total_hint}. total_hint is an approximate count of matching orders for progress display — treat it as a hint, not an exact total, and rely on has_more / next_cursor to iterate.

Use cursor-based pagination for bots. Treat the cursor as opaque (it is urlsafe-base64 wrapping the last item’s created_at — every character is URL-safe, so naive string interpolation round-trips correctly; a raw-ISO cursor is also accepted on the way in). Cursoring avoids page drift when new orders arrive between requests. Pass the next_cursor value from the previous response back as the cursor (or next_cursor) parameter.

Get a Single Order

GET /v1/orders/{order_id}

Returns one row in the same shape as GET /v1/orders.

order_id values come from two separate sequences: orders (the id POST /v1/orders returns) and fill rows, for example the fill of a partially filled IOC order, whose client_order_id ends in :p<parent order id>_.... The same number can exist in both. By default the lookup tries orders first and falls back to fills, so a bare lookup can return an unrelated row. source names the table the id came from: ?source=pending for an order, ?source=filled for a fill row. Most ids POST /v1/orders returns are orders; a market order with time_in_force: "FOK" returns its fill row’s id instead, so look that one up with ?source=filled. Confirm the row by its client_order_id, and do not use order_type to tell orders from fills: immediate market orders are stored as orders with order_type: "market" too.

Cancel Order

DELETE /v1/orders/{order_id}

Cancel a pending limit order. Only PENDING orders can be cancelled.

curl -X DELETE -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/orders/42

Response

{
  "order_id": 42,
  "status": "CANCELLED",
  "order_type": "limit",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0.60",
  "quantity": "10.0",
  "notional": "6.00",
  "fee": "0"
}

Cancellation returns reserved funds:

BUY orders: Reserved cash is returned to your balance
SELL orders: Reserved shares are returned to your position

Cancel All Orders

POST   /v1/cancel-all
DELETE /v1/cancel-all   (deprecated alias)

Cancel every pending limit order for your account in one call. POST is the canonical verb; DELETE is a back-compat alias kept live for SDKs that adopted the earlier shape (it returns X-Deprecation / Sunset headers).

Confirmation is required to prevent accidental wipeouts. Pass either ?confirm=true (query parameter) or the X-Confirm-Cancel-All: true header. Without one, the call is rejected with 400 CONFIRMATION_REQUIRED and no orders are touched. To cancel a single order use DELETE /v1/orders/{order_id}; to cancel by market use DELETE /v1/cancel-market-orders.

curl -X POST "https://api.polysimulator.com/v1/cancel-all?confirm=true" \
  -H "X-API-Key: $API_KEY"

The response matches Polymarket’s cancel shape — canceled is a list of order-id strings, not_canceled maps each skipped order-id to the reason:

{
  "canceled": ["42", "43", "44"],
  "not_canceled": {}
}

This is the same cancel-all logic the heartbeat dead-man’s-switch delegates to when a bot stops sending heartbeats.

Next Steps

Batch Orders — Place multiple orders at once
Trade History — View filled orders

Getting Started

Core Concepts

Trading Guide

Market Data

Simulation

Account & Portfolio

WebSocket Feeds

Webhooks

Bot Development

Porting to Polymarket

Order Management

Order Management

Order Endpoints Summary

List Orders

Query Parameters

Response Fields

Examples

Response

Get a Single Order

Cancel Order

Response

Cancel All Orders

Next Steps

​Order Management

​Order Endpoints Summary

​List Orders

​Query Parameters

​Response Fields

​Examples

​Response

​Get a Single Order

​Cancel Order

​Response

​Cancel All Orders

​Next Steps

Order Management

Order Endpoints Summary

List Orders

Query Parameters

Response Fields

Examples

Response

Get a Single Order

Cancel Order

Response

Cancel All Orders

Next Steps