Placing orders

POST /api/orders/place
X-Api-Key: ps_live_<keyId>_<secret>   # needs `orders:write` scope
Content-Type: application/json

See API keys for format, scope taxonomy, associatedWallet requirement, and rate-limit buckets.

Request body

interface PlaceOrderReq {
  marketId: string;          // app-level symbol, e.g. "NC26-BIN-83479265"
  side: 'buy' | 'sell';      // lowercase
  outcome: string;           // "0" = YES (first), "1" = NO (second)
  price: string;             // decimal USDC, e.g. "0.42"
  quantity: string;          // decimal outcome qty, e.g. "2"
  nonce: string;             // decimal-string of the salt used in the EIP-712 struct
  expiry: number;            // unix seconds (= Order.expiration); use 0 for no on-chain expiry
  maker: string;             // your VAULT (= VaultFactory.vaultOf(signer)) or your wallet; see below
  signature: string;         // 0x-prefixed EIP-712 signature
  clientOrderId?: string;    // idempotency key (optional, scoped per associatedWallet)
  type?: 'limit' | 'market'; // default 'limit'
  timeInForce?: 'gtc' | 'ioc' | 'fok'; // default 'gtc'; MARKET orders must send 'ioc' or 'fok'
  feeRateBps?: number;       // JSON integer: the feeRateBps you signed (= market.feeTakerBps); recommended, see below
  postOnly?: boolean;        // LIMIT + gtc only; see Post-only orders below
}

The request body is whitelisted (forbidNonWhitelisted). Any extra field returns 400 invalid_request, and error.details.fields[] names the offending property, for example: { "field": "foo", "constraint": "whitelistValidation", "message": "property foo should not exist" }. Send feeRateBps with the value you signed. If the market fee changed after you fetched it, the order is rejected with status: REJECTED, code: stale_fee_quote and a message giving the current rate. Re-fetch feeTakerBps, then re-sign. If you omit the field, the signature is still checked against the current fee, and a stale fee comes back as bad_signature. The platform never receives the struct you signed. It rebuilds the on-chain Order from your request fields and recovers your signature against that rebuild. So the struct you sign must always contain:

signer = the wallet you authenticate as (your key’s associatedWallet, or the X-User-Wallet for a multi_wallet key)
maker = that wallet’s vault (VaultFactory.vaultOf(signer)), never the EOA
signatureType = 1 (VAULT). 0 (EOA) is deprecated. The platform and the exchange contract both reject it, even when maker == signer.
salt = the body nonce, expiration = expiry, feeRateBps = the market’s feeTakerBps, taker = 0x0, tokenId = the token for outcome, side = 0 BUY / 1 SELL
makerAmount / takerAmount derived from price / quantity (CEIL on BUY notional, FLOOR on SELL)
the EIP-712 domain of the binary or the neg-risk exchange, according to the market’s negRiskEligible

See EIP-712 signing for the typed-data definition. The body maker field is only an ownership check. It must be your wallet or its vault (anything else is rejected with maker_mismatch, an HTTP 401 on /place), and the platform verifies against your vault in both cases. If the signature does not recover to your wallet, or a non-zero expiry has already passed, the order comes back as status: REJECTED, code: bad_signature, not as an HTTP 400. Its details show the exact struct the platform verified and the address it expected to recover; see Response shape.

Validation rules

Except where a row shows an HTTP status, every rule in this table is checked as a business rule. A failure comes back as a REJECTED envelope, not an HTTP error: an HTTP 201 body { status: "REJECTED", code, message } on /place, or an entry with success: false on /place-batch. Branch on status / code, not on the HTTP status. (Shape errors, such as a non-numeric price or an unknown field, fail request validation first with 400 invalid_request.)

Field	Rule	Failure
`price`	`0 < p < 1` (strict — `p >= 1` is rejected to block the `fee = k × P × (1−P)` sign flip at `P > 1`). Tick size is `0.01` — at most 2 decimal places (integer cents, 99 distinct levels). `0.505` returns `invalid_amounts` with “price tick size is 0.01”. While a match is in-play, a market whose `liveTick` is set (see `GET /api/markets/{symbol}`) accepts only multiples of that wider tick (for example `0.05`).	`code: invalid_amounts`. An off-grid in-play price is HTTP `400`, `code: in_play_tick_violation` on `/place`, and a per-entry `REJECTED` with the same code on `/place-batch`
`quantity`	`> 0`, at most 6 decimal places (USDC scale).	`code: invalid_amounts`
Minimum size	`price × quantity` ≥ the platform minimum (default 1 USDC). A `MARKET` `SELL`, or a `SELL` with `ioc` / `fok`, is measured by `quantity` instead.	`code: order_too_small`
`type` + `timeInForce`	MARKET orders require `ioc` or `fok`; MARKET+GTC is rejected	`code: invalid_tif`
`signature`	Must recover to the wallet you authenticate as, against the `Order` the platform rebuilds from your request (see Request body). A struct signed with `signatureType` `0` or with `maker` = EOA never verifies.	`code: bad_signature`. `details` carries `recovered`, `expected_signer` and `platform_canonical_struct`; diff that struct against the one you signed.
`maker` (body)	Your wallet or its vault. The vault is always used in the signed struct.	HTTP `401`, `code: maker_mismatch` on `/place`; a `success: false` entry with the same code on `/place-batch`
`expiry`	`0` (no expiry, recommended) or unix seconds in the future. There is no minimum TTL. It is signed as `Order.expiration`, so it must equal the value in your signed struct.	A non-zero `expiry` at or before the server’s current time fails signature verification: `code: bad_signature`. There is no separate `expired` code. If every other field is right, `details.recovered` equals `details.expected_signer`, which is how you spot a stale expiry.
`outcome`	A valid outcome index for the market (`"0"` = YES, `"1"` = NO on binary markets). The platform maps it to the on-chain `tokenId`.	`code: invalid_outcome` (not a non-negative integer) / `code: market_outcomes_not_seeded` (no such outcome on this market)
Balance	`available >= price × quantity` (BUY)	`code: insufficient_funds`
Position	Available position `>= quantity` (SELL), where available = your vault’s ERC-1155 balance of `tokenId` minus the quantity your other open SELL orders on that token already reserve	`code: insufficient_position`
Market	The close cut-off has not passed, and `status` is `OPEN` (or `PRE_MARKET` for a resting LIMIT GTC order that does not cross the book)	`code: market_not_open` / `code: pre_market_post_only` / `code: pre_market_crossing_order`
Self-trade	A `limit` order’s `price` must not reach one of your own resting orders on the other side of the book	`code: self_cross_blocked`; see Self-trade prevention

Worked example — BUY 10 YES at 0.42

import { Wallet, randomBytes, hexlify, parseUnits } from 'ethers';

// 1. Resolve vault, outcome tokenId, AND the per-market taker fee
const vault    = await vaultFactory.vaultOf(wallet.address);
const market   = await fetch(`${BASE}/api/markets/NC26-BIN-83479265`).then(r => r.json());
const tokenId  = market.yesTokenId;       // outcome '0'
const feeBps   = BigInt(market.feeTakerBps);  // CRITICAL — see the feeRateBps note under Request body

// 2. Build + sign EIP-712 (see /concepts/trading/eip712-signing)
const salt     = BigInt(hexlify(randomBytes(32)));   // send salt.toString() as `nonce`
const priceWei = parseUnits('0.42', 6);
const qtyWei   = parseUnits('10',   6);   // notional 4.20 USDC, above the 1 USDC minimum
// CEIL on BUY notional. FLOOR-signed BUY orders are rejected at
// placement (code: order_signed_with_floor_notional) because they
// overflow the matcher's per-fill CEIL math on the closing tail
// fill. See /concepts/trading/eip712-signing#rounding-rule-ceil-on-buy-floor-on-sell-notional
const notionalWei = (priceWei * qtyWei + 999_999n) / 1_000_000n;

const orderStruct = {
  salt, maker: vault, signer: wallet.address,
  taker: '0x0000000000000000000000000000000000000000',
  tokenId: BigInt(tokenId),
  makerAmount: notionalWei,        // BUY → USDC notional
  takerAmount: qtyWei,             // BUY → outcome qty
  expiration: 0n,
  feeRateBps: feeBps,              // MUST equal market.feeTakerBps
  side: 0, signatureType: 1,       // BUY, VAULT
};
const signature = await wallet.signTypedData(domain, types, orderStruct);

// 3. POST
const resp = await fetch(`${BASE}/api/orders/place`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.PS_API_KEY! },
  body: JSON.stringify({
    marketId:      'NC26-BIN-83479265',
    side:          'buy',
    outcome:       '0',
    price:         '0.42',
    quantity:      '10',
    nonce:         salt.toString(),
    expiry:        0,
    maker:         vault,
    signature,
    clientOrderId: `mm-bot-${Date.now()}`,
    type:          'limit',
    timeInForce:   'gtc',
    feeRateBps:    Number(feeBps),   // echo the signed fee as a JSON number (not a string or BigInt)
  }),
}).then(r => r.json());

Response shape

interface PlaceOrderResp {
  orderId: string;             // server-issued UUID; '' when rejected before the order was recorded
  status: 'PENDING' | 'OPEN' | 'FILLED' | 'CANCELLED' | 'REJECTED' | 'EXPIRED' | 'SETTLEMENT_FAILED';
  filledQty: string;           // cumulative fill at response time (decimal)
  remainingQty: string;        // quantity - filledQty
  trades: TradeFill[];         // synchronous fills produced by IOC/FOK or aggressive LIMIT
  code?: string;               // present when status=REJECTED (insufficient_funds, bad_signature, …)
  message?: string;            // human-readable explanation; pairs with code
  details?: Record<string, unknown>; // structured reject context; shape depends on `code`. Check it exists before reading.
  traceId?: string;            // correlation id, quote it in support requests (same value on every entry of a batch)
  clientOrderId?: string;      // echoed from request when supplied
}

On code: bad_signature, details contains recovered (the address your signature recovers to against the platform’s struct), expected_signer (the acting wallet: your key’s associatedWallet, or the X-User-Wallet on multi_wallet keys) and platform_canonical_struct (the exact Order the platform verified). Compare it field by field with the struct you signed. The field that differs is the cause. If recovered equals expected_signer, the struct matched and your non-zero expiry has already passed. See bad_signature diagnostic hints. The clientOrderId field is echoed verbatim when the request supplied one — present on every shape (success, REJECTED, idempotent replay). Use it to correlate the server-issued orderId to your own client-side handle without a follow-up GET /api/orders/{id}. The same value is also carried on the order_placed and order_cancelled frames of the user_orders channel on /ws/user, so partners that drive their state machine off the WS feed get the correlation key on both surfaces.

Post-only orders

Set postOnly: true to guarantee an order only ever rests on the book and never matches on entry. It’s the maker-side guarantee market makers need to avoid paying taker fees. (No order of yours ever trades against your own quotes, post-only or not: a limit order that would reach them is rejected, and a market order cancels the ones it comes to; see Self-trade prevention.)

POST /api/orders/place
X-Api-Key: ps_live_<keyId>_<secret>   # needs `orders:write` scope
Content-Type: application/json

{ /* ...single-place body... */ "marketId": "UAE-CUP-FINAL-20260425", "type": "limit", "timeInForce": "gtc", "postOnly": true }

Only valid for LIMIT orders with gtc time-in-force (optionally with expiry). Omit it (or send false) for today’s behavior.

Two rejection modes.

post_only_invalid_order_type — postOnly was sent with a MARKET order or an ioc / fok time-in-force. The combination is invalid and nothing is placed. On /place this is an HTTP 400. On /place-batch it comes back as that entry’s own { "success": false, "status": "REJECTED", "code": "post_only_invalid_order_type" } inside a successful batch response, and the other entries still process. In a batch, check the entry, not the HTTP status.
post_only_would_cross — the order was marketable at entry: its price meets or crosses the best price on the opposite side of the book (at-touch equality counts as crossing). It returns { "status": "REJECTED", "code": "post_only_would_cross" } with no fills — reprice inside the spread and resubmit. If its price also reaches one of your own resting orders, you get self_cross_blocked instead, even when another participant’s order sits in front of yours: self-trade prevention is checked first.

Self-trade prevention

A wallet never trades with itself. When a new order would meet one of your own resting orders, the platform stops that match. What it stops depends on the new order’s type:

New order from the same wallet	The new order	Your resting order
`limit` (any `timeInForce`, with or without `postOnly`) whose `price` reaches your own resting order on the other side	Rejected before anything matches: `status: "REJECTED"`, `code: "self_cross_blocked"`. Nothing fills and nothing rests	Stays on the book unchanged
`market` whose sweep comes to your own resting order (within its `price` cap, while it still has quantity left)	Keeps filling against other participants’ orders; any unfilled remainder is cancelled as usual	Cancelled with `reason: "self_trade_prevention"`. Your orders the sweep never gets to, because other orders filled it first, stay on the book
`limit` that doesn’t reach your own resting order (for example a bid at `0.30` while your ask rests at `0.70`)	Processed normally	Unchanged

For a limit order, “reaches” means a BUY priced at or above your lowest resting SELL, or a SELL priced at or below your highest resting BUY; an equal price counts. Quoting both sides with a spread between them is always allowed.

A limit order is checked against your own price, not against the whole book. If its price reaches one of your resting orders, the whole order is rejected, even when other participants’ orders at better prices would have filled it first. Example: another trader asks 0.45 and your own ask rests at 0.55. A BUY limit at 0.60 is rejected with self_cross_blocked and takes nothing; a BUY at 0.50 fills against the 0.45 ask. To trade through your own quote, cancel it first, or send a market order with a price cap, which cancels your own orders it comes to and fills against everyone else’s.

YES and NO share one book. On a binary market, buying NO at p is the same as selling YES at 1 − p, so your orders on both outcomes are checked together. A BUY YES and a BUY NO reach each other when their prices add up to 1.00 or more; a SELL YES and a SELL NO when they add up to 1.00 or less. With your BUY NO at 0.40 resting, a BUY YES at 0.60 is self_cross_blocked and a BUY YES at 0.55 is not. Different markets never block each other, including the questions of one multi-outcome event.
Checked first. The check runs before the post-only and fill-or-kill checks. A postOnly order that reaches your own order gets self_cross_blocked, not post_only_would_cross, and a LIMIT + FOK order comes back REJECTED with self_cross_blocked, not CANCELLED. A LIMIT + IOC order that reaches your own order takes nothing, not even better-priced orders of other participants.
Batches. place-batch entries are processed in array order. A limit entry that reaches an order an earlier entry of the same batch left resting is rejected with self_cross_blocked, and the earlier entry is unaffected. A market entry cancels that order instead, as described above.
Pre-market. While a market is PRE_MARKET, an order that would cross any resting order, yours or anyone else’s, is rejected earlier with code: pre_market_crossing_order (see Market status). An entry that crosses an order placed by an earlier entry of the same place-batch is not caught by that check and comes back as self_cross_blocked instead.
Just-expired orders. One of your orders whose expiry has just passed can still count for a few seconds, until the platform removes it from the book.
Per wallet. Orders from two different wallets are never blocked or cancelled against each other, even when they belong to the same multi_wallet API key: they match like any two participants. Trading between wallets you control is still subject to market surveillance.

What you receive

Rejected limit order. POST /api/orders/place answers HTTP 201 with status: "REJECTED", code: "self_cross_blocked" and a real orderId (on place-batch, that entry with success: false). Only this response names the code. On the user_orders WebSocket channel you get the usual order_placed frame, then order_cancelled with reason: "matcher_rejected" (not order_rejected), and GET /api/orders/{id} reads REJECTED.
Resting order cancelled by your market order. An order_cancelled frame on user_orders with reason: "self_trade_prevention". It can arrive without clientOrderId, originalQuantity and remainingQty, so key it by orderId. GET /api/orders/{id} reads CANCELLED, and the order’s locked funds are released as with any cancel. The market order’s own response doesn’t list the orders it cancelled.

Batch placement

Submit up to 10 orders in one request with POST /api/orders/place-batch. Each entry is the exact same body as single placement; the batch is processed sequentially in array order with independent per-order outcomes — one rejected order never aborts the rest, and there is no all-or-nothing atomicity. Request validation is the exception: if any entry is malformed (for example a non-numeric price, an unknown field or a missing signature), or the array holds 0 or more than 10 entries, the whole request fails with 400 invalid_request and no entry is processed.

POST /api/orders/place-batch
X-Api-Key: ps_live_<keyId>_<secret>   # needs `orders:write` scope
Content-Type: application/json

{ "orders": [ /* 1–10 PlaceOrderReq objects, same shape as single place */ ] }

The response is an array aligned to the request by index. Each item is a PlaceOrderResp (identical to single place) plus a success flag:

[
  { "success": true,  "orderId": "3f6c1a2e-8b4d-4c1e-9a7f-2d5e6b7c8d90", "status": "OPEN",     "filledQty": "0", "remainingQty": "2", "trades": [], "clientOrderId": "mm-1" },
  { "success": false, "orderId": "",                                     "status": "REJECTED", "filledQty": "0", "remainingQty": "0", "trades": [], "code": "insufficient_funds", "message": "..." }
]

Partner trade limits accumulate across the batch. For users who trade through a partner sign-in (partner_sso), the partner trade cap is charged against the running total of the entries accepted earlier in the same batch, so a batch can never admit more exposure than the same orders sent one at a time.

Business reject vs infrastructure failure. A rejected order (bad signature, insufficient funds, …) comes back as a per-entry success: false inside an HTTP 201 response, and the rest of the batch still processes. An infrastructure failure (matcher / verifier / DB unavailable) fails the whole request with a 5xx. Entries processed before the failure may already be placed, and the 5xx body does not say which ones.An entry the exchange was too busy to take comes back success: false with code: "journal_intent_not_durable" and details.retryable: true, and the other entries keep their own results. Nothing was admitted for that entry: resend the same signed order unchanged, under the same clientOrderId, shortly. Do not sign a new one.Always set your own clientOrderId on every entry. Then you can resend the same batch with the same keys: entries that were already placed return their original result, and the rest are processed normally.If you left clientOrderId out, the keys the server generated are not returned to you, so a resend is not linked to the first attempt. Resending the identical signed orders still cannot place anything twice: an entry that was already placed comes back success: false with code: "order_already_placed". You won’t get its original result, though, so look it up by its order hash (see Finding an order after a timeout). Don’t re-sign an entry with a new nonce until you’ve confirmed the first one was not placed.

Rate limited at 8 req/sec/wallet (token bucket, so up to 80 orders/sec). Single /place has its own limit of 50 req/sec/wallet. For the full table, see Rate limits. KYC deposit-tier gating applies, same as single place.

Finding an order after a timeout

When a place request times out or answers 5xx you don’t have the orderId, but you hold two keys for the order: the clientOrderId you sent, and its orderHash, the EIP-712 digest of the struct you signed (see EIP-712 signing). Look the order up by either one:

GET /api/orders/lookup?clientOrderId=mm-bot-42
GET /api/orders/lookup?orderHash=0x84a930f9e902ae91...
X-Api-Key: ps_live_<keyId>_<secret>   # needs `orders:read`

Pass exactly one of the two; neither or both answers 400 invalid_request.
The answer is the same Order object as GET /api/orders/{id}.
clientOrderId is matched exactly (case-sensitive, not trimmed). URL-encode it: a raw + in a query string reads as a space. orderHash is accepted in any case.
An unknown key and an order of another wallet both answer 404 order_not_found.
The server-generated srv-* key comes back (in details.clientOrderId) only on a single POST /api/orders/place 503. A place-batch 5xx carries no keys, so set your own clientOrderId on every batch entry, or look the order up by orderHash.
Orders that ended with no trade are archived after 30 days and are then not found here or by GET /api/orders/{id}: a 404 for an old order says nothing about it.

A 404 right after a timeout does not prove the order was never placed. It may not be recorded yet. The authoritative answer is still to re-send the identical request under the same clientOrderId: that returns the original result if the order was placed, and places it if it never reached us. It never creates a second order. Don’t sign a new order until you know the first one was not placed. If you sent no clientOrderId, look the order up by orderHash. Re-send only in that window, never an old order.

Sell orders

Same shape; side: 'sell'. No USDC is locked for a SELL order. Instead, the order reserves its quantity of the outcome token (ERC-1155), which must already sit in the vault, not the EOA. Tokens reserved by one open SELL cannot back another; cancelling or expiry releases the reservation for the unfilled remainder. Position resolution is keyed by maker (the vault), which is why on-chain splits (USDC → YES + NO) must be initiated by vault.splitPosition(...) rather than by the EOA directly. See Vaults for the split flow.

Time-in-force

GTC vs IOC vs FOK behaviour.

Cancelling orders

Single-order and cancel-all flows.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Request body

Validation rules

Worked example — BUY 10 YES at 0.42

Response shape

Post-only orders

Self-trade prevention

Batch placement

Finding an order after a timeout

Sell orders

Next

Time-in-force

Cancelling orders

​Request body

​Validation rules

​Worked example — BUY 10 YES at 0.42

​Response shape

​Post-only orders

​Self-trade prevention

​Batch placement

​Finding an order after a timeout

​Sell orders

​Next

Time-in-force

Cancelling orders

Request body

Validation rules

Worked example — BUY 10 YES at 0.42

Response shape

Post-only orders

Self-trade prevention

Batch placement

Finding an order after a timeout

Sell orders

Next