Advanced orders

How advanced orders execute

Build persistent limits, conditional orders, execution schedules and linked orders directly through the API. An LLM is not required. Once accepted, the API manages the order even when the trading screen is closed.

The API holds the parent strategy and submits individual child orders through the existing quote-execution path when its conditions are met. Triggers and schedules are not resting orders in a public exchange order book. The parent can fill across multiple child executions. An acknowledgement means the parent was accepted, not that a trade filled.

This is an additive reference. Existing order endpoints retain their ordinary execution behavior. A plain LIMIT with GTC alone does not select an API-managed persistent limit.

Create a persistent limit

Use the existing POST /api/order transport with explicit advanced intent. This requests 0.001 BTC at a maximum price of $60,000, or $60 notional. Prices are illustrative, not live quotes.

{
  "symbol": "BTC/USD",
  "side": "BUY",
  "type": "SYNTHETIC_LIMIT",
  "quantity": "0.001",
  "price": "60000",
  "timeInForce": "GTC",
  "newClientOrderId": "btc-limit-001"
}

Alternatively use type: "LIMIT" with apiManaged: true. Sign this existing transport using its existing authentication convention; the V3 rules below apply to the new V3 routes.

1. Resolve the market and convert size to base-asset units.
2. Validate notional and precision; retain a stable client ID for each logical order.
3. Save the returned parent orderId and inspect both status and apiState.
4. Follow private order updates and reconcile with the bounded managed-order list.

Request JSON examples show business fields. Add authentication fields for the chosen transport. No example places an order automatically.

REST endpoints

Production base URL: https://app.quote.trade. Use the configured host for another environment. All routes below are authenticated and account-scoped.

Single-parent creation still uses POST /api/order; single-parent status and cancellation use the existing order transports. There is no new POST /api/v3/order route in this implementation.

account defaults to the authenticated owner. Another account requires delegated permission. If supplied, userId must identify the authenticated actor, not a different user. Both managed openOrders methods require apiManaged=true.

Sign V3 REST requests

Send X-MBX-APIKEY and signature headers. The signature is hexadecimal HMAC-SHA256 of the exact raw query string (without ?) followed immediately by the exact UTF-8 body bytes, using the API secret. Do not insert a separator.

These are the scoped V3 servlet rules. Do not copy the older generic GET example that signs a JSON-encoded path. Use Content-Type: application/json for JSON bodies. Put each parameter in one place; fields must be scalar, with no nested objects, arrays or null values. Maximum body: 32,768 bytes.

Use a fresh nonce according to the existing REST client convention. Nonce alone is not an idempotency guarantee. Retain client IDs and reconcile uncertain results before retrying.

import hashlib
import hmac
import os
import time
import urllib.parse

# Read-only request signing. This example sends no network request.
query = urllib.parse.urlencode({
    "apiManaged": "true", "includeHistory": "true",
    "newestFirst": "true", "limit": "50", "afterOrderId": "0",
    "nonce": str(time.time_ns()),
})
body = b""
signature = hmac.new(
    os.environ["QUOTE_API_SECRET"].encode("utf-8"),
    query.encode("utf-8") + body,
    hashlib.sha256,
).hexdigest()
url = "https://app.quote.trade/api/v3/openOrders?" + query
headers = {"X-MBX-APIKEY": os.environ["QUOTE_API_KEY"],
           "signature": signature}

For a body-only V3 POST or DELETE, use an empty query and sign the exact minified body sent. Never log your secret or signed credentials.

Size, precision and shared fields

Admission uses the limit price when present, otherwise the stop price, otherwise the current quote. Opening TWAP slices and iceberg display quantities must also meet the minimum. Children are checked again at the executable quote. Reduce-only orders are exempt from the opening-notional minimum but still need valid precision, permissions and reducible exposure.

An accepted order can later have an unexecutable residual below the minimum. It is not enlarged automatically and may expire. Decimal precision and minimum notional are separate checks.

Order types and triggers

Triggers observe the fresh executable side: ask for BUY, bid for SELL. BUY stops trigger at or above the stop; SELL stops at or below. BUY take-profits trigger at or below the stop; SELL take-profits at or above. Buy limits need quotes at or below the cap, sell limits at or above the floor. The quantity-aware child quote is checked again before submission.

Trailing distance

Choose one: trailingDelta (integer basis points, 1–9,999), price2 (percentage, e.g. 1.5 for 1.5%, greater than zero and below 100), or trailingAmount (positive absolute USD distance, up to 8 decimals). BUY tracks the lowest reference then triggers on a rise; SELL tracks the highest then triggers on a fall.

Optional stopPrice gates activation; otherwise tracking starts with the first fresh observation. For a dynamic trailing limit, limitOffset is added on BUY and subtracted on SELL; without it the supplied limit price is fixed.

{
  "symbol": "ETH/USD",
  "side": "SELL",
  "type": "TRAILING_STOP_MARKET",
  "quantity": "0.02",
  "trailingDelta": 150,
  "reduceOnly": true,
  "newClientOrderId": "eth-trail-001"
}

TWAP, VWAP and participation

TWAP divides quantity across scheduled attempts. Each opening slice must meet the minimum. Unfilled residual after the final attempt expires; total fill is not guaranteed.

VWAP uses completed Quote.Trade executed base-asset volume, not exchange-wide volume or depth. Its default profile uses completed one-minute history, a 512-bar window, whole-minute intervals and duration up to 512 minutes. Missing/empty history rejects profile creation, rather than silently becoming TWAP. Explicit weights support other valid intervals and durations.

Weights are frozen at admission. Zero weights are allowed; missed opportunities do not cause a retroactive burst. Residual may continue after the final interval until expiry or another terminal condition; set expiry for a hard end time. No benchmark price is guaranteed.

POV participates in fresh Quote.Trade executed volume observed after admission, including its own fills. Fresh price and trade data are required; stale observations pause eligibility.

{
  "symbol": "BTC/USD",
  "side": "BUY",
  "type": "TWAP",
  "quantity": "0.01",
  "interval": 60000,
  "intervalCount": 10,
  "intervalDelay": 0,
  "newClientOrderId": "btc-twap-001"
}

{
  "symbol": "BTC/USD",
  "side": "BUY",
  "type": "LIMIT",
  "targetStrategy": 1000002,
  "quantity": "0.01",
  "price": "60000",
  "interval": 60000,
  "intervalCount": 4,
  "volumeProfile": "1,2,3,4",
  "newClientOrderId": "btc-vwap-001"
}

OCO, OTO and OTOCO

Use flat fields, not nested order arrays. Set a unique listClientOrderId (1–36 characters, the same character set as order IDs), and retain it for retries of the same intent. Conflicting reuse is rejected. Scheduled/participation legs are not supported inside lists.

OCO · one cancels the other

Both legs share symbol, side and quantity. Prefix supported leg fields with above and below: Type, Price, StopPrice, TimeInForce, ClientOrderId, TrailingDelta, IcebergQty and ReduceOnly. The upper level must exceed the lower.

For SELL the upper leg is take-profit and lower is stop-loss; BUY reverses these roles. A winning trigger cancels its sibling before child submission. A winning stop-limit can then wait for a quote inside its price cap.

{
  "symbol": "BTC/USD",
  "side": "SELL",
  "quantity": "0.01",
  "listClientOrderId": "btc-oco-001",
  "aboveType": "TAKE_PROFIT_LIMIT",
  "aboveStopPrice": "70000",
  "abovePrice": "69950",
  "aboveTimeInForce": "GTC",
  "belowType": "STOP_LOSS_LIMIT",
  "belowStopPrice": "55000",
  "belowPrice": "54950",
  "belowTimeInForce": "GTC"
}

OTO · one triggers the other

Prefix fields with working and pending, including Type, Side, Quantity, Price and other fields supported by the leg type. The pending leg activates only after a full working fill; a partial entry does not activate it.

{
  "symbol": "ETH/USD",
  "listClientOrderId": "eth-oto-001",
  "workingType": "LIMIT",
  "workingSide": "BUY",
  "workingQuantity": "0.02",
  "workingPrice": "2500",
  "workingTimeInForce": "GTC",
  "pendingType": "LIMIT",
  "pendingSide": "SELL",
  "pendingQuantity": "0.02",
  "pendingPrice": "2800",
  "pendingTimeInForce": "GTC",
  "pendingReduceOnly": true
}

OTOCO · entry followed by an OCO pair

Use working fields, shared pendingSide/pendingQuantity, then pendingAbove…/pendingBelow… leg fields. A full working fill releases the pair. Apply reduce-only to each exit when the working order opens exposure.

{
  "symbol": "ETH/USD",
  "listClientOrderId": "eth-bracket-001",
  "workingType": "LIMIT",
  "workingSide": "BUY",
  "workingQuantity": "0.02",
  "workingPrice": "2500",
  "workingTimeInForce": "GTC",
  "pendingSide": "SELL",
  "pendingQuantity": "0.02",
  "pendingAboveType": "TAKE_PROFIT_LIMIT",
  "pendingAboveStopPrice": "2800",
  "pendingAbovePrice": "2795",
  "pendingAboveTimeInForce": "GTC",
  "pendingAboveReduceOnly": true,
  "pendingBelowType": "STOP_LOSS_LIMIT",
  "pendingBelowStopPrice": "2300",
  "pendingBelowPrice": "2295",
  "pendingBelowTimeInForce": "GTC",
  "pendingBelowReduceOnly": true
}

Working cancellation, rejection or expiry cancels unreleased pending legs. Canceling any list leg cancels the entire list. Held legs report PENDING_NEW and held: true.

Legacy OCO

POST /api/v3/order/oco accepts price, stopPrice, optional stopLimitPrice and stopLimitTimeInForce, plus limitClientOrderId, stopClientOrderId, limitIcebergQty, stopIcebergQty and trailingDelta as applicable. For BUY the stop is above the limit; for SELL it is below.

Bounded history and pagination

GET /api/v3/openOrders lists managed parents, including standalone orders and list legs, across every market in the account. It does not replace the existing ordinary-order list.

GET /api/v3/openOrders?apiManaged=true&includeHistory=true&newestFirst=true&limit=50&afterOrderId=0&nonce=FRESH_NONCE

The envelope has apiManaged, includesHistory, total, nextOrderId and orders, plus newestFirst: true when requested. Total is all matching records, not page size. Zero nextOrderId means the end. Managed IDs are negative and newer IDs decrease; do not assume ordinary positive-ID sorting.

{
  "apiManaged": true,
  "includesHistory": true,
  "newestFirst": true,
  "total": 0,
  "nextOrderId": 0,
  "orders": []
}

1. Start with afterOrderId=0 and newestFirst=true.
2. Render each order's type, side, quantity, limit, trigger and state.
3. If nextOrderId is nonzero, request it with the same account, history, sort and limit, and a freshly signed request.
4. Refresh from zero for new orders; deduplicate by orderId when combining pages.

Pages are not an atomic snapshot: orders can change between requests. Terminal history is an operational cache, not an immutable audit archive. The managed route rejects symbol, instrumentId and side because its scope is all markets.

Linked-list queries differ

GET /api/v3/orderList uses orderListId or origClientOrderId/listClientOrderId, with an optional symbol/instrument check. openOrderList and allOrderList have default limit 500, range 1–1,000 and optional startTime/endTime in epoch milliseconds. They do not expose the managed-parent cursor or promise newest-first sorting. Use managed-parent pagination for the order UI.

Cancellation and uncertain outcomes

Cancel a linked list with DELETE /api/v3/orderList using its server or client list ID. Placement ownership rules apply.

{
  "orderListId": -101
}

Account-wide cancellation: DELETE /api/v3/openOrders with apiManaged=true cancels pending managed orders across all markets. It rejects symbol, instrumentId and side filters. Show that scope clearly before offering cancel-all.

{
  "apiManaged": true
}

The result reports matchedCount, canceledCount and cancelPendingCount. In-flight children may leave cancellation pending. Continue monitoring until the outcome is known; a successful cancellation request does not guarantee that no in-flight child filled.

After a timeout, 5xx, or apiState: "UNKNOWN", reconcile the original client/server ID. Do not generate another client ID and submit duplicate exposure while the first outcome remains uncertain.

Response fields and lifecycle

List replies include orderListId, listClientOrderId, contingencyType (OCO/OTO/OTOCO), listStatusType (EXEC_STARTED/ALL_DONE), listOrderStatus (EXECUTING/ALL_DONE), transactionTime, orders identities and full orderReports. Inspect individual legs to distinguish fills from cancellation, expiry or rejection.

Show parent state alongside filled quantity. WAITING can mean a valid limit awaiting its price; WORKING can mean a child is in flight. Neither means fully filled.

WebSocket methods

Private request endpoint: wss://app.quote.trade/ws/listenKey, with the configured host for your environment. Signed requests use the envelope below and the same business fields/scopes as REST.

{
  "id": "history-page-1",
  "method": "openOrders.status",
  "params": {
    "apiKey": "YOUR_API_KEY",
    "apiManaged": true,
    "includeHistory": true,
    "newestFirst": true,
    "limit": 50,
    "afterOrderId": 0,
    "timestamp": 0,
    "recvWindow": 5000,
    "signature": "YOUR_HMAC_SIGNATURE"
  }
}

Set timestamp to current epoch milliseconds. Sign every scalar parameter except signature: sort the key=value entries alphabetically, join with &, then HMAC-SHA256 with the secret. Include apiKey, timestamp, recvWindow and all business fields. Preserve decimal strings and lowercase booleans. This differs from REST query/body signing.

recvWindow defaults to 5,000 ms, maximum 60,000 ms. Timestamp must be within that window and less than one second ahead of server time. This timestamp validation replaces the REST nonce field.

Replies correlate by id and return status/result or an error code/message. Use existing private stream authentication/subscription for ORDER_TRADE_UPDATE and listStatus events, and reconcile after reconnecting. See the existing order stream reference.

Execution limits and errors

Quotes, margin, permissions and exposure can change after admission. Eligibility does not guarantee a fill. Stale market data pauses execution; conditions do not bypass freshness, minimum size, price caps or account restrictions.

Inspect the body as well as HTTP status: existing business-error conventions may return errors inside HTTP 200. Transport success is not execution success.

This layer does not offer exchange-native queue priority, pegged/midpoint/SOR orders, new self-trade-prevention or hedge-position modes, or index/mark-price triggers.

Based on current API route, input, sizing, serialization and WebSocket implementations. Reviewed 8 October 2026. Deployment availability must be checked separately.