TWAP

A TWAP (time-weighted average price) trigger splits a total quantity into slices and places one slice per interval over a duration. Use it to work a larger order without sending it to the book at once. A TWAP does not watch a price and does not guarantee the market's average price or a full fill. Create one with CreateTrigger (POST /v1/triggers) and a twap strategy.

Fields

Set exactly one of market_ioc and limit_gtc. fee_asset, self_trade_prevention_mode, and client_trigger_id follow the same rules as other triggers. In REST, the limit price is limitGtc.price and the quantity qty, both decimal strings; the durations stay integers.

How slices are planned and sized

The number of slices is duration_ms divided by slice_interval_ms, rounded up, and at most 1,000,000. The first slice is placed when the TWAP is accepted, and each later slice one interval after the previous one.

Each slice's quantity is decided when it is due: the quantity not yet filled or open, divided by the slices left, rounded down to the Pair's quantity step. Quantity that an earlier slice did not fill moves into later slices, and the last slice takes everything that remains.

Because slices never shrink while they fill, the first slice is the smallest. A create whose first slice could never pass the Pair's order limits is rejected with that check's code, and nothing is created: STEP_SIZE when it rounds down to zero, or MIN_QUANTITY or MIN_NOTIONAL. A market slice is valued at its slippage bound from the current price.

Market and limit slices

The slippage cap protects each slice on its own. It does not bound how far the price moves over the whole duration. See Market order price protection.

Funds

A TWAP reserves nothing when it is created. Each slice is funded when it is placed, like an order you send. A slice that your available balance cannot cover is rejected, and the TWAP fails.

How a TWAP ends

A live TWAP is RUNNING. twap_state shows slice_idx, slice_count, and executed_qty_scaled, the quantity its slices have filled.

Slices placed before a TWAP fails or is canceled remain real orders, and their fills stand. A failed TWAP does not retry the rejected slice and places no further slices.

The duration is a plan, not a hard deadline. A slice that waits, for example for placement budget or for the previous limit slice to be canceled, delays the slices after it.

Managing a TWAP

A TWAP takes only CancelTrigger. Pause, resume, and modify are refused with TRIGGER_NOT_MODIFIABLE; cancel and create a new TWAP to change it.

Each slice is an ordinary order with the client order ID trg:<trigger_id>:<child_seq>, and EVENT_FIRED names it. You can amend or cancel a slice like any order, but you cannot raise it above what the TWAP still has to execute: that is refused with CHILD_QTY_EXCEEDS_REMAINING. Canceling a slice does not cancel the TWAP. A cancel-all cancels the open slice and leaves the TWAP running.

Limits

An account can run up to 20 TWAPs on one Pair at once, and they count toward its 100-trigger limit on that Pair. A TWAP beyond either limit is refused with MARKET_TWAP_LIMIT_EXCEEDED or MARKET_TRIGGER_LIMIT_EXCEEDED, and nothing is created. When the Pair has no room for another TWAP across all accounts, the create is refused with TWAP_CAPACITY_REACHED; retry later.

Creating a TWAP costs one unit of TRADING_PLACE, and each slice costs one more when it is placed. A slice that meets an empty budget, or an account under an automatic repair, waits and is placed shortly; the TWAP records EVENT_FIRE_REFUSED for the refused attempt and stays RUNNING. See Rate limits.

Example

A TWAP that buys 1 BTC over 10 minutes in market slices, each capped at 0.5% slippage.

{
	"trigger": {
		"symbol": "BTC-USDT",
		"qty": "1",
		"clientTriggerId": "twap-btc-1",
		"twap": {
			"side": "BUY",
			"durationMs": 600000,
			"sliceIntervalMs": 60000,
			"marketIoc": { "maxSlippageBps": 50 }
		}
	}
}

{
	"trigger": {
		"symbolId": 1,
		"qtyScaled": "100000000",
		"clientTriggerId": "twap-btc-1",
		"twap": {
			"side": "BUY",
			"durationMs": "600000",
			"sliceIntervalMs": "60000",
			"marketIoc": { "maxSlippageBps": 50 }
		}
	}
}

Errors

See Error codes for HTTP and ConnectRPC statuses.

Related Topics