Order sizing

Order sizing defines which quantity a client controls when placing an order. Every OrderIntent.sizing selects exactly one of two alternatives, on CreateOrder (POST /v1/orders), batch create, and preview alike.

Sizing alternatives

• base_qty_scaled · Scale: Pair base_quantity_scale · Eligible: BUY or SELL with any execution type
  Exact gross base quantity submitted for execution.
• max_quote_debit_scaled · Scale: Pair quote_quantity_scale · Eligible: BUY Market IOC or BUY Limit IOC
  Hard all-in quote debit ceiling, including any quote-denominated fee.

REST uses the equivalent decimal-string fields baseQty and maxQuoteDebit.

Exact base quantity

base_qty_scaled controls the gross base quantity sent for execution. It does not describe the net amount received after fees.

For a BUY with a quote-denominated fee, the account must fund trade notional plus the fee. For a BUY with a base-denominated fee, the fee reduces the base amount received. See Fee Assets.

Maximum quote debit

max_quote_debit_scaled sets the quote amount a BUY spends, including any quote-denominated fee. The order spends the whole amount at the prices its fills actually pay, never past its protected price boundary: when the book is better than the boundary, the same amount buys more base. It never debits more than the amount.

The whole amount counts against the Pair's maximums. It must fit maxOrderNotionalQuote and, for a market order, maxMarketNotionalQuote, or the order is rejected with MAX_NOTIONAL. See Pairs and trading rules.

A quote-denominated fee is budgeted at the account's own taker fee rate in force when the order is admitted, including its VIP tier and discounts, so the amount is not held back for a higher rate. The fills are never charged more than that rate.

The order buys in whole quantity steps, so less than one step's cost can stay unspent. When the book cannot fill the rest within the boundary, the order stops there and the unfilled amount is released.

A quote-budget order ends FILLED once it has spent its amount, that is when what is left of the amount buys no further quantity step at the next price it could fill at. Its last fill reports no remaining quantity, no cancel follows it, and its quantity is what it bought.

A quote-budget order that stops while its remaining amount could still buy more keeps its partial fill and ends CANCELED. A market order ends with cancel reason MARKET_REMAINDER when the book runs out, the next price is past its protection price, or it reaches the market's maximum order quantity. A Limit IOC order ends with IOC_REMAINDER. Its fills stand.

The base quantity resolved at admission is not the final quantity; read the filled quantity from the order. This sizing mode is invalid for SELL, Limit GTC, Limit GTD, and Limit FOK orders.

A quote-budget BUY can carry attached take-profit, stop-loss, or trailing-stop legs. Because it has no fixed quantity, its legs protect what its fills actually buy. At create, each leg's exit is checked against the Pair's minimums at the least the whole amount could buy: at the order's limit price, or at a market order's protected price. An exit below those minimums refuses the order with the minimum's own code, such as MIN_NOTIONAL. See Attached take-profit and stop-loss.

How much of the amount an order used

Order reads report the quote the fills used and the fee they paid, so the order alone tells how much of the amount was spent:

Compute what a quote-budget BUY used from these fields:

• Fee in quote: used is cumQuote plus feeTotal.amount, or minus it when feeTotal.isRebate is true.
• Fee in base: used is cumQuote, because the fee is taken from the base received.
• Unspent: submittedMaxQuoteDebit less what the order used.

These figures are exact when the Pair's base quantity scale is at most 9. Above that, each fill settles its quote rounded down to 18 decimal places, so the computed use can exceed the settled debit by less than 1e-18 per fill.

A fill's fee is recorded shortly after the fill executes, so feeTotal can trail the fills. Use it once feeTotal.qty equals the order's cumQty; a later read includes the missing fee. Order history reads and single-order reads that include execution history carry feeTotal. Open-order reads, single-order reads without execution history, and private stream order updates carry cumQuote only.

For example, a market BUY with submittedMaxQuoteDebit 6000 and a quote fee that stopped at its price limit reads cumQuote 3215.5809531728 and feeTotal.amount 0.96467428595184. It used 3216.54562745875184 and left 2783.45437254124816 unspent.

Request examples

{
	"order": {
		"symbol": "BTC-USDT",
		"side": "BUY",
		"maxQuoteDebit": "100.00",
		"feeAsset": "QUOTE",
		"marketIoc": {
			"maxSlippageBps": 50
		}
	}
}

{
	"order": {
		"symbolId": 1,
		"side": "BUY",
		"maxQuoteDebitScaled": "100000000",
		"feeAsset": "QUOTE",
		"marketIoc": {
			"maxSlippageBps": 50
		}
	}
}

Use Scaled integers to resolve Pair scales and Market order price protection for price-boundary behavior.

Create acknowledgement

CreateOrderResponse acknowledges admission, not execution:

• resolved_base_qty_scaled is the authoritative gross base quantity accepted for execution.
• submitted_max_quote_debit_scaled is present only when quote-budget sizing was submitted.

Do not infer fills from this response. Use order reads and realtime streams for working, filled, canceled, and terminal state.

SBE WebSocket

The client-facing SBE CreateOrder command requires sizingKind. See Schema version for the current schema version.

Successful create acknowledgements expose resolvedBaseQtyScaled and, for quote-budget orders, submittedMaxQuoteDebitScaled.

Use Preview order when an integration needs to check an order before submission.

Related Topics