Preview Order

OrdersService.PreviewOrder 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.

Preview is advisory

Preview does not walk order-book depth, simulate fills, reserve funds, or guarantee execution. Account state, prices, fees, and Pair policy can change before submission. CreateOrder always evaluates the intent again.

Request shape

PreviewOrderRequest and CreateOrderRequest both contain:

optional subaccount_id
required order: OrderIntent

Reuse the same OrderIntent builder for both operations. Do not maintain a separate flat Preview model. The intent includes symbol, side, sizing, execution, fee asset, client order ID, self-trade prevention, and optional attached risk.

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
		}
	}
}

Call /orders.v1.OrdersService/PreviewOrder:

{
	"order": {
		"symbol": "BTC-USDT",
		"side": "BUY",
		"baseQtyScaled": "100000",
		"feeAsset": "QUOTE",
		"limitGtc": {
			"priceTicks": "50000000000",
			"postOnly": true
		}
	}
}

The examples assume the Pair scales have already been applied. See Scaled Integers.

Response fields

Protobuf field	Meaning
`admissible`	Whether current admission and available-balance checks passed
`rejection`	Typed `ErrorDetail` when the order is not currently admissible
`resolved_base_qty_scaled`	Gross base quantity resolved during admission, when sizing reached resolution
`protected_price_bound_ticks`	Protective execution boundary, when price protection reached resolution
`evaluated_at`	Time at which the admission evaluation completed

REST exposes the optional resolved values as resolvedBaseQty and protectedPriceBound.

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.

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.

Interface availability

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

Public IDs Understand what Polyester public IDs identify, why they are opaque, and how their representation differs per interface. Client order IDs and idempotency Use client order IDs to prevent duplicate placement, correlate client intents, and reconcile uncertain outcomes. Order Sizing Choose exact base-quantity or maximum quote-debit sizing and read the authoritative quantity accepted for execution. Fee Assets Choose whether a BUY fee is charged in quote or deducted from received base, and decode fee amounts with the correct scale. 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 from the same trading account. 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.