Batch Orders

POST /v1/orders/batch

Place multiple orders in a single request, up to your tier’s max batch size (see the table below). Each order is processed independently — partial failures are reported per-order.

Batch Size Limits

Tier	Max Batch Size
`free`	1
`pro`	5
`pro_plus`	10
`enterprise`	25

Authoritative on the wire via GET /v1/keys/tiers — max_batch_size field. See Rate Limits for the full per-tier matrix.

Request

curl -X POST https://api.polysimulator.com/v1/orders/batch \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "market_id": "0xabc...",
        "side": "BUY",
        "outcome": "Yes",
        "quantity": "5",
        "order_type": "market",
        "price": "0.99"
      },
      {
        "market_id": "0xdef...",
        "side": "BUY",
        "outcome": "No",
        "quantity": "3",
        "order_type": "market",
        "price": "0.99"
      },
      {
        "market_id": "0xghi...",
        "side": "BUY",
        "outcome": "Yes",
        "quantity": "10",
        "order_type": "limit",
        "price": "0.45",
        "time_in_force": "GTC"
      }
    ]
  }'

Each order in the array follows the same schema as POST /v1/orders.

Market orders inside a batch still require price — it’s the worst-price slippage cap (Polymarket-faithful). Without it the entry is rejected with Market orders require a 'price' field. For BUY, set the maximum you’ll pay; for SELL, the minimum you’ll accept. See Placing Orders for the full slippage-cap rationale.

Response

{
  "results": [
    {
      "order_id": 42,
      "status": "FILLED",
      "price": "0.65",
      "quantity": "5",
      "notional": "3.25"
    },
    {
      "order_id": 43,
      "status": "FILLED",
      "price": "0.40",
      "quantity": "3",
      "notional": "1.20"
    },
    {
      "order_id": 0,
      "status": "REJECTED",
      "error": "INSUFFICIENT_BALANCE",
      "error_message": "Insufficient balance for BUY order"
    }
  ],
  "succeeded": 2,
  "failed": 1
}

Partial failures don’t roll back successful orders. Each order is independent — some may succeed while others fail. Always check the succeeded and failed counts.

Error Response Format

Every entry in results is a full OrderResponse. A failed entry has status="REJECTED" (a per-entry validation/business rejection) or status="ERROR" (an internal error processing that entry), with two clean machine-readable fields:

error — the stable machine code (e.g. INSUFFICIENT_BALANCE, MARKET_CLOSED, INVALID_QUANTITY), matching the single-order error envelope byte-for-byte. See the canonical trading error-code table.
error_message — the human-readable prose for that failure.

Each failed entry in results has this shape:

{
  "order_id": 0,
  "status": "REJECTED",
  "order_type": "market",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0",
  "quantity": "1",
  "notional": "0",
  "fee": "0",
  "client_order_id": "bot-123",
  "error": "INSUFFICIENT_BALANCE",
  "error_message": "Insufficient balance for BUY order"
}

Branch on the error code; show error_message to humans. (Earlier drafts showed error as a stringified Python-repr of the detail dict — that behaviour was removed; error is now a clean code and error_message carries the prose.)

A batch request itself returns HTTP 200 even when individual orders fail — iterate results to check per-order status. Request-level failures still use HTTP status codes: auth, rate limit, malformed JSON, and an oversize batch (see below).

Oversize batch → request-level 400

If orders exceeds your tier’s max batch size, the whole request is rejected with 400 BATCH_LIMIT_EXCEEDED — no results array, no per-entry processing. Check GET /v1/keys/tiers (max_batch_size) and split large batches client-side.

// 400 BATCH_LIMIT_EXCEEDED
{"error": "BATCH_LIMIT_EXCEEDED", "message": "Batch size 12 exceeds tier limit (10)"}

Note the key difference between the two failure shapes: a request-level rejection (like this oversize-batch 400) uses the standard {error, message} envelope, while a per-entry rejection inside a 200 results array uses {error, error_message} (shown above). Branch on error in both cases.

Use Cases

Portfolio Rebalancing

Buy underweight positions and sell overweight positions in a single request.

Grid Trading

Place a ladder of limit orders at multiple price levels simultaneously.

Market Scanning

Buy small positions across multiple undervalued markets at once.

Rate Limit Optimization

1 batch request counts as 1 API call vs N individual calls.

Next Steps

Slippage Protection — Control fill quality
Placing Orders — Single order reference

Getting Started

Core Concepts

Trading Guide

Market Data

Account & Portfolio

WebSocket Feeds

Bot Development

Going Live

Batch Orders

Batch Orders

Batch Size Limits

Request

Response

Error Response Format

Oversize batch → request-level 400

Use Cases

Portfolio Rebalancing

Grid Trading

Market Scanning

Rate Limit Optimization

Next Steps

​Batch Orders

​Batch Size Limits

​Request

​Response

​Error Response Format

​Oversize batch → request-level 400

​Use Cases

Portfolio Rebalancing

Grid Trading

Market Scanning

Rate Limit Optimization

​Next Steps

Batch Orders

Batch Size Limits

Request

Response

Error Response Format

Oversize batch → request-level 400

Use Cases

Next Steps