> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # Create TWAP order > Create TWAP order. Create a server-side TWAP (time-weighted average price) parent order. The matching engine executes it as a schedule of MARKET child orders with seeded size/timing randomization across the requested window, then stops hard at the end time — any unfilled remainder is reported as shortfall, never traded past the window. Delegated-agent sessions are rejected. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml post /api/v1/orders/twap openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: CopyTradingService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/orders/twap: post: tags: - OrdersService - Orders summary: Create TWAP order description: |- Create TWAP order. Create a server-side TWAP (time-weighted average price) parent order. The matching engine executes it as a schedule of MARKET child orders with seeded size/timing randomization across the requested window, then stops hard at the end time — any unfilled remainder is reported as shortfall, never traded past the window. Delegated-agent sessions are rejected. operationId: create_twap_order requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTwapOrderRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateTwapOrderResponse' '400': description: >- Invalid TWAP parameters (window bounds, quantity too small or too large to slice, margin field mismatch) or per-user active TWAP cap reached '401': description: >- Authentication required or delegated-agent session (rejected for TWAP) '409': description: Duplicate clientTwapId for this user and application '429': description: >- Order rate limit exceeded — a TWAP parent costs one order-creation item against the per-account budget and the account family's shared budget; retry after the interval in details.retryAfter '500': description: Internal server error or matching engine failure security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: CreateTwapOrderRequest: required: - tradingPairId - side - quantity type: object properties: tradingPairId: example: afae0e16-2d05-4ee9-9ee8-afae0e162d05 type: string description: Trading pair UUID format: uuid side: example: BUY type: string description: 'Order side: BUY or SELL' quantity: example: '10' type: string description: >- Total quantity to execute across the window as decimal string. Must be at least 2x the pair's minimum order size so it can be sliced, and small enough that the window's slice budget can carry it with every child at or below the pair's maximum order size. durationSeconds: example: 3600 type: integer description: >- Execution window length in seconds from launch. Exactly one of durationSeconds or endTime must be set. Bounds (env-tunable defaults): 60 to 2592000 (1 minute to 30 days). format: int64 nullable: true startTime: example: '2026-08-01T10:00:00Z' type: string description: >- Window start (RFC 3339, UTC only — use a Z suffix; non-UTC offsets are rejected). Only valid together with endTime; defaults to now. nullable: true endTime: example: '2026-08-01T11:00:00Z' type: string description: >- Window end (RFC 3339, UTC only — use a Z suffix; non-UTC offsets are rejected). Exactly one of durationSeconds or endTime must be set. The effective window must satisfy the same duration bounds. Execution stops hard at this time; any unfilled remainder is reported as shortfall. nullable: true limitPrice: example: '35000.00' type: string description: >- Optional parent-level limit price as decimal string. BUY child orders never execute above it, SELL children never below it. Omitted: slippage band protection only. nullable: true slippageToleranceBps: example: 100 maximum: 500 type: integer description: >- Per-slice protective price band in basis points around the reference price (default 100 = 1%, maximum 500 = 5% — deliberately tighter than the standalone market-order cap; TWAP slices never sweep deep) format: int32 nullable: true randomize: example: true type: boolean description: >- Apply seeded randomization to slice sizes and timing (default true). The seed is recorded for audit, so the schedule is reproducible to compliance but unpredictable to the market. nullable: true reduceOnly: example: false type: boolean description: >- Whether the TWAP parent is reduce-only (margin only). Child orders inherit it and clamp to the live position. nullable: true tradingMode: example: SPOT type: string description: 'Trading mode: SPOT or MARGIN (default: SPOT)' nullable: true marginAccountId: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: >- Margin account UUID for margin TWAP orders. Resolved once at creation and reused by every child order. format: uuid nullable: true riskBucketId: example: 123e4567-e89b-12d3-a456-426614174001 type: string description: >- Existing isolated risk bucket UUID for risk-bucket-scoped margin TWAP orders. Snapshot at creation. format: uuid nullable: true marginMode: example: CROSS enum: - ISOLATED - CROSS type: string description: >- Risk bucket mode for margin TWAP orders. Defaults to ISOLATED. Values: ISOLATED, CROSS. On an isolated-only market (TradingPairData.isolated_only) a CROSS order that is not reduce-only is rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code CROSS_MARGIN_NOT_ALLOWED. One margin mode per market and margin account: while the account holds the pair in its other risk bucket (an open position, or a resting order that is not reduce-only), an order that is not reduce-only is rejected with HTTP 400 / gRPC INVALID_ARGUMENT carrying the structured error code MARGIN_MODE_CONFLICT; reduce-only orders always pass, so a pair already held in both modes can be reduced on either side until one closes. nullable: true leverage: example: '5' type: string description: >- Leverage multiplier as a decimal string. Required for normal margin TWAP orders; optional and ignored for reduce-only. nullable: true strategyKey: example: my-strategy type: string description: Strategy key used to group risk buckets for margin orders nullable: true useMasterBalance: example: false type: boolean description: Use master account balance for sub-account orders nullable: true clientTwapId: example: oms-3f6a1c type: string description: >- Client-assigned idempotency key (max 36 chars), unique per user and application. A duplicate is rejected with 409. nullable: true executionStyle: example: PASSIVE enum: - TAKER - PASSIVE type: string description: >- Child execution style. TAKER (default): each slice executes immediately as a banded MARKET order. PASSIVE: each slice rests as a post-only limit at the same-side touch (maker where possible, repriced to follow the touch, never beyond the parent limit price or the protective band), and the leftover is swept as a banded MARKET order at the slice deadline. Passive parents use a slower default slice cadence (~60s). nullable: true triggerPrice: example: '98000.00' type: string description: >- Price-triggered activation: the parent waits (PENDING) until the reference price reaches or crosses this price in triggerDirection, then runs a floating window of durationSeconds from the trigger instant. Requires triggerDirection and durationSeconds; incompatible with startTime/endTime. Rejected if the condition is already met at creation. Margin markets arm against the oracle mark and the create is rejected while the market has no mark yet (retry once one is published); once the parent is waiting, activation evaluates the mark when it is available and the venue reference price (book-derived median, last-trade fallback) when it is not, so a mark outage cannot leave a live trigger unwatched. Spot markets use the venue reference price throughout. nullable: true triggerDirection: example: BELOW enum: - ABOVE - BELOW type: string description: >- Which way the reference price must cross triggerPrice to activate: ABOVE (activate when price rises to or through it) or BELOW (falls to or through it). Required with triggerPrice; no exact print is required — a reference price observed at or beyond the level activates. The condition is evaluated on the engine's own polling cadence rather than on every market tick, so a price that crosses and reverts entirely between two observations is not seen; there is no high/low watermark. nullable: true conditionalExpiry: example: '2026-09-01T00:00:00Z' type: string description: >- Deadline for the trigger to fire (RFC 3339, UTC only — Z suffix; non-UTC offsets rejected). If the trigger has not fired by then the parent cancels with terminal reason 'trigger expired'. Only valid with triggerPrice; must be in the future and at most the maximum window (default 30 days) from creation, which is also the default when omitted. nullable: true additionalProperties: false CreateTwapOrderResponse: type: object properties: twapOrderId: example: 123e4567-e89b-12d3-a456-426614174000 type: string description: Created TWAP parent order UUID format: uuid nullable: true status: example: SUCCESS type: string description: >- Result status: SUCCESS or FAILED. SUCCESS means the parent is durably recorded; execution itself is best-effort within the window. nullable: true message: example: TWAP order created successfully type: string description: Human-readable status message nullable: true state: example: PENDING type: string description: >- Initial parent state: always PENDING at create. An unconditional parent activates on its first attempted slice; a conditional one (triggerPrice set) stays PENDING until its trigger fires. nullable: true marginAccountId: type: string description: Resolved margin account UUID for margin TWAP orders format: uuid nullable: true riskBucketId: type: string description: >- Resolved isolated risk bucket UUID for risk-bucket-scoped margin TWAP orders format: uuid nullable: true plannedSlices: example: 120 type: integer description: Number of slices in the planned schedule format: int32 nullable: true firstSliceAt: example: '2026-08-01T10:00:27Z' type: string description: >- Planned time of the first slice (ISO 8601). PROVISIONAL for a conditional parent (triggerPrice set): its window floats from the trigger instant, which is unknown at create, so this is computed from the provisional [create, create + durationSeconds] window and is re-anchored when the trigger fires. Read the armed window back from the TWAP read model (startAt / endAt / triggeredAt) instead of scheduling on this value. nullable: true endTime: example: '2026-08-01T11:00:00Z' type: string description: >- Resolved window end (ISO 8601). Execution never continues past it. PROVISIONAL for a conditional parent (triggerPrice set) for the same reason as firstSliceAt: the real window is [trigger instant, trigger instant + durationSeconds] and is re-anchored on activation. nullable: true securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.