TESTNET
Connect

Preview order

OrdersService.PreviewOrder (POST /v1/orders/preview) is an authenticated, account-aware admission preflight. It evaluates a complete order intent without submitting it.

What Preview checks

Preview evaluates the current inputs used for create admission:

  • request validation and execution compatibility
  • Pair policy and trading constraints
  • fee and risk rules
  • available account balance

It creates no order, hold, reservation, or client-order-ID claim.

Request shape

A preview request has the same shape as a CreateOrder request: an optional Subaccount and one complete order. Reuse the same order builder for both operations rather than maintaining a separate flat Preview model, so a preview checks exactly what you would submit, attached legs included.

See Order sizing and Fee Assets for those independent choices.

Request examples

Send the nested order object to POST /v1/orders/preview:

{
	"order": {
		"symbol": "BTC-USDT",
		"side": "BUY",
		"baseQty": "0.001",
		"feeAsset": "QUOTE",
		"limitGtc": {
			"price": "50000.00",
			"postOnly": true
		}
	}
}

The ConnectRPC example assumes BTC-USDT has symbolId 1 and a base quantity scale of 8, so 0.001 is 100000. Prices are in units of 1e-9 quote, so 50000 is 50000000000000. See Scaled integers.

Read the result

The full response schema is in the API reference for PreviewOrder. What each part tells you:

  • admissible says whether the current validation, policy, risk, and available-balance checks passed. When it is false, rejection carries the typed reason.
  • The resolved base quantity and protected price boundary are present only when evaluation got far enough to resolve them. REST returns them as decimal strings, resolvedBaseQty and protectedPriceBound; ConnectRPC returns scaled integers.
  • evaluated_at is when the evaluation completed. Account state and prices after that time are not reflected.

protected_price_bound_ticks is a safety boundary, not an expected fill price. Preview does not return expected fills, order-book depth, quote debit, fees, net proceeds, or required balance. Reservation and fee-ceiling calculations remain internal to the admission check.

Rejections and transport errors

Insufficient funds is a completed preview result. admissible is false and rejection.code is ERROR_CODE_INSUFFICIENT_FUNDS.

Over REST, a quantity or price with a nonzero digit beyond the Pair's scale is also a completed result: admissible is false with QTY_STEP_SIZE or PRICE_TICK_SIZE and a violation such as order.baseQty. Trailing zeros beyond the scale are accepted, so "0.001000" previews like "0.001".

Authentication failures, malformed requests, and failures that prevent evaluation still use normal RPC or HTTP errors. Preserve ErrorDetail.code and every field violation rather than parsing human-readable messages. REST violations, in rejection and in error bodies, name the REST request field, such as order.limitGtc.price; ConnectRPC violations name the protobuf field, such as order.limit_gtc.price_ticks.

Interface availability

Preview is available through REST and ConnectRPC. The SBE WebSocket command path does not expose a Preview command.

Order types and lifecycle Order types, time in force, statuses and their transitions, cancel and reject reasons, versions, modify and replace, and how to read orders and fills. Fills and trade history Read your executions, reconcile order totals and fees, and backfill a durable trading history. Order sizing Choose exact base-quantity or maximum quote-debit sizing and read the authoritative quantity accepted for execution. Client order IDs and idempotency Use client order IDs to prevent duplicate placement, correlate client intents, and reconcile uncertain outcomes. Market order price protection Understand market-order slippage overrides, Pair defaults, client reference drift, execution boundaries, and stale-quote errors. Self-trade prevention Prevent an incoming order from trading against a resting order of the same Main Account or its Subaccounts. Batch orders Create, replace, or cancel many orders in one request, read each item's result, and retry safely after a partial failure or an unknown outcome. Cancel all orders Cancel every open order that matches a filter, with an answer at acceptance and idempotent retries. Dead-man switch Arm a heartbeat timer with CancelAllAfter so your open orders are canceled automatically if your system stops refreshing it. Fee Assets Choose whether a BUY fee is charged in quote or deducted from received base, and decode fee amounts with the correct scale. Swap Convert Trading balances through spot order books with quotes, minimum output protection, and idempotent execution. Triggers overview How standalone and attached triggers watch a price or a schedule, place child orders, report their status, and count against limits. Rate limits Weighted quotas, default limits, rejection metadata, and retry behavior. WebSocket session model Understand shared connection, authentication, subscription, and recovery behavior for Polyester realtime channels. Recover after reconnect Rebuild a bot's orders, executions, balances, and triggers after a disconnect or restart without duplicating orders. Public IDs Understand what Polyester public IDs identify, why they are opaque, and how their representation differs per interface.
Previous

Client order IDs and idempotency
Next

Market order price protection