Market Order Price Protection

Polyester market orders use immediate-or-cancel execution with a price boundary. They can fill immediately at available prices within that boundary, while any unfilled quantity is canceled.

The boundary is calculated from a reference price and a slippage tolerance. A request can provide its own tolerance, or it can omit the tolerance and use the Pair's configured default.

How the execution boundary is calculated

For basis-point protection:

Fractional-tick adjustments round outward so the boundary never grants less tolerance than requested. A buy boundary rounds upward and a sell boundary rounds downward, making the effective boundary up to one price tick more permissive than the exact percentage.

Example: explicit 6% slippage

600 basis points equals 6%. With a reference price of 100:

The 600 bps value is used unchanged even if the Pair default is lower.

Explicit values, defaults, and limits

maxSlippageBps accepts values from 1 through 10,000:

1 bp      = 0.01%
600 bps   = 6%
10,000 bps = 100%

Values outside that range are rejected as MAX_SLIPPAGE_INVALID. Values inside the range are not silently resized.

Read the current Pair policy

Pair policy is returned by MarketDataService.GetSpotConfig. Read these fields for the selected Pair instead of hardcoding current defaults:

The default slippage fields are fallback values, not ceilings on client overrides.

The TypeScript SDK catalog exposes these values as percentages: defaultMarketSlippagePctBuy, defaultMarketSlippagePctSell, and maxClientRefDriftPct. Use the raw GetSpotConfig response when an integration needs the basis-point field names shown above.

Client reference drift

A client reference price records the price the client used for a preview or trading decision. When both client and server references are available, Polyester calculates:

drift bps = absolute(client reference - server reference) * 10,000 / server reference

For example, client reference 105 and server reference 100 produce 500 bps, or 5%, of drift. If drift exceeds maxClientRefDriftBps, the order is rejected as STALE_QUOTE.

maxClientRefDriftBps does not:

• cap the request's slippage value
• replace maxSlippageBps
• apply when the request omits a client reference price

The compounded bounds in that example are:

buy:  1.05 * 1.06 = 1.113
sell: 0.95 * 0.94 = 0.893

If an integration intends to enforce a total distance from current market data, it must account for both the permitted reference drift and the requested slippage. The server reference itself may differ from a simultaneously observed best bid or ask, so it should not be treated as an interchangeable top-of-book price.

Request fields by interface

Send either basis-point slippage or tick slippage, not both.

{
	"order": {
		"symbol": "BTC-USDT",
		"side": "BUY",
		"baseQty": "0.25",
		"clientOrderId": "market-buy-001",
		"marketIoc": {
			"maxSlippageBps": 600,
			"clientRefPrice": "100.000000"
		}
	}
}

{
	"order": {
		"symbol": "BTC-USDT",
		"side": "BUY",
		"baseQtyScaled": "25000000",
		"clientOrderId": "market-buy-001",
		"marketIoc": {
			"maxSlippageBps": 600,
			"clientRefPriceTicks": "100000000"
		}
	}
}

order {
  symbol: "BTC-USDT"
  side: BUY
  base_qty_scaled: 25000000
  client_order_id: "market-buy-001"
  market_ioc {
    max_slippage_bps: 600
    client_ref_price_ticks: 100000000
  }
}

For tick-based protection, replace maxSlippageBps with maxSlippageTicks, or max_slippage_bps with max_slippage_ticks in protobuf source fields. Price ticks use a fixed 1e-6 quote-unit scale. baseQtyScaled uses the Pair's base-quantity scale from GetSpotConfig. See Scaled Integers.

For a BUY market IOC, clients can send maxQuoteDebit in REST or max_quote_debit_scaled in protobuf instead of a base quantity. This value is a hard, all-in quote debit limit. Polyester resolves and returns the gross base quantity before execution. A quote fee counts toward the limit, while a base fee reduces the base amount received. See Order Sizing.

OrdersService.PreviewOrder accepts the same nested OrderIntent as create and returns the resolved quantity and price boundary without creating an order or reservation. It also checks current available balance and returns a typed admission result. Preview does not inspect future order-book depth or guarantee execution. See Preview Order.

Official SDKs expose the same controls through language-specific order inputs. See the applicable SDK Orders reference for its field names and types.

Error behavior

STALE_QUOTE is returned to the caller with the message:

Client reference price is stale relative to server market data.

The rejection can also appear as the order's terminal reason in order-state and realtime updates.

Integration guidance

• Fetch and refresh Pair policy rather than treating current defaults as permanent constants.
• Send the same client reference used to show the user an execution preview.
• Choose an application-level maximum below 100% when the integration requires a stricter risk policy.
• Treat STALE_QUOTE as a signal to refresh market data and obtain a new trading decision. Do not blindly retry the unchanged order.
• Do not retry MAX_SLIPPAGE_INVALID or request-validation errors unchanged. Correct the request before sending it again.

Related Topics