Modify order
Modify the price and/or quantity of an open order.
address query parameter matching the master Ethereum address for X-API-Key.
Identify the order to modify by exactly one of orderId or clientId — setting both, or neither, is rejected with a validation error.
No separate cancel + place event pair is emitted. On the orders WebSocket channel the client observes: a non-crossing modify → a single orders update; a crossing modify → a fill followed by a PLACED (or REJECTED). Correlate by orderId / clientId.
Response behavior
Asynchronous. Returns either202 Accepted (common case — forwarded to the matching engine, body carries the orderId for correlation) or 200 OK (gateway already has definitive state for the order). Subscribe to the orders WebSocket channel to observe the order’s lifecycle.Authorizations
Hex-encoded Ed25519 public key (64 chars). The public key IS the API key — register it via POST /createApiKey. Required on every authenticated request, both read-only and signed.
Unix time in nanoseconds as a decimal string (e.g. "1713825891591000000"). Millisecond or second epochs are rejected with 401 Unauthorized. Must be within ±30,000 ms (MaxTimestampDriftMs, the drift window stays configured in milliseconds) of server wall-clock, or the request is rejected with 401 Unauthorized. Required on all mutating / credential-creating endpoints. This same value must appear as the ct field in the ordersign typed canonical payload (single-order endpoints) or in each element's ct field (batch endpoints).
Lowercase hex-encoded Ed25519 signature (128 chars).
Single-order endpoints (placeOrder, cancelOrder, modifyOrder, and other non-batch mutating routes) sign over the ordersign typed canonical payload — a compact, key-sorted JSON object built from parsed request fields using engine-native integer values:
ct must equal the X-Timestamp header value. Keys in brackets are conditional (omitted when empty). op values: 1=place, 2=cancel, 3=modify. See the ordersign package for field definitions and reference signing code.
Other signed routes (e.g. createApiKey, tokens, userPreferences) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.
Batch endpoints (batchPlaceOrders, batchCancelOrders) do NOT use this header. They authenticate with per-element typed ordersign signatures embedded in the request body (see the global auth description and the per-field signature descriptions on OrderRequest / CancelOrderRequest).
Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required. The one exception is GET /v1/affiliate/inviteCodes, which returns bearer secrets and therefore requires the full header triple; with no body its signing message is X-Timestamp + ACTION. canonicalJSON(body) is the JSON body with object keys sorted lexicographically at every level and no whitespace; the server canonicalizes the received body before verifying, so only the bytes signed over must be canonical. Required on all mutating / credential-creating endpoints.
Body
Modify the price and/or size of a single open order (processed as an atomic cancel + replace).
Identify the order to modify by exactly one of orderId (the server-generated id) or clientId (resolved engine-side against the account's client-id index). Setting both is rejected, and so is setting neither — supply one or the other, never both.
Master Ethereum address for this API key (must match POST /createApiKey for the same key).
^(0x|0X)?[0-9a-fA-F]{40}$Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.
0 <= x <= 9Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.
0 <= x <= 65535The order's expiry as an epoch-microsecond timestamp (string). Required — echo the resting order's goodTilTime from placement, and it must be at least one month ahead of the current system timestamp. If it differs from the resting order's value, the engine performs a cancel-replace with the new expiry. Covered by the Ed25519 request signature (g field of the canonical modify payload, in nanoseconds).
1New size in human-readable base-asset units (e.g. "0.5" for 0.5 BTC), at most the market's maxOrderSize (reduce-only orders are not exempt).
1^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$New price in human-readable USD (e.g. "50000.5").
1^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$BUY, SELL GTT = Good Till Time (rests until goodTilTime), IOC = Immediate or Cancel, FOK = Fill or Kill, ALO = Add Liquidity Only (post-only).
Submissions must use GTT for resting orders. Note: order reads (REST order queries and the orders WebSocket channel) currently report resting orders as GTC — the legacy name for the same bucket — for backward compatibility; see TimeInForceResponse.
GTT, IOC, FOK, ALO Required — must be explicitly true or false (immutable; echo the resting order's value). Covered by the Ed25519 request signature. A missing or null value is rejected with InvalidRequest.
Server-generated order ID to modify (hex string). Provide exactly one of orderId or clientId, never both.
1Identify the order to modify by its placement-time clientId. Subject to the same constraints as at placement: 1–36 characters, [A-Za-z0-9_-] only. The gateway resolves the value against the account's client-id index engine-side. Provide exactly one of orderId or clientId; supplying both is rejected with HTTP 400.
36^[A-Za-z0-9_-]+$Client-side timestamp as a string of Unix nanoseconds — this is the signed ct replay nonce and must equal the X-Timestamp header. A millisecond or second value is rejected with 401.
Response
Modify processed and the gateway already has definitive state for the replacement order. Treat as best-effort enrichment of the 202 path; the orders WebSocket channel is still the source of truth.
Modify-order response. The HTTP call is asynchronous and may return either:
202 Accepted— common case.statusisACKand the body carries the replacementorderIdfor correlation; theordersWebSocket channel delivers the lifecycle.200 OK— the gateway already had definitive state for the replacement order by the time it responded.
Master Ethereum address of the account that modified the order.
"0x1234567890abcdef1234567890abcdef12345678"
Account index (subaccount) that modified the order.
0 <= x <= 9Parsed clientTime from the request when provided as an integer-like string; otherwise 0.
Server-generated id of the replacement order created by the modify operation.
Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.
0 <= x <= 65535Market symbol (e.g. BTC-USD).
"BTC-USD"
ACK on the 202 path. On the 200 path, the definitive state.
PENDING, OPEN, PARTIALLY_FILLED, FILLED, CANCELED, MARGIN_CANCELED, REJECTED, UNTRIGGERED, TPSL_PLACED, TPSL_TRIGGERED, TPSL_CANCELED, LIQUIDATED, ADL, ACK, CANCEL_ACKNOWLEDGED, CANCEL_ALL_ACKNOWLEDGED, CANCEL_PENDING, ERROR "ACK"
Gateway clock (epoch microseconds) at the moment the modify was forwarded to the matching engine.
Echo of the client id attached to the replacement order, when provided.
Echo of the time-in-force from the modify request.
GTT, IOC, FOK, ALO The resting order's expiration timestamp in epoch microseconds (as string). Populated once the matching engine confirms the modify. Present only on the 200 path for GTT/ALO orders; absent on 202 and for IOC/FOK orders.
Unfilled size of the replacement order. Populated only on the 200 path.
Cumulative filled size of the replacement order. Populated only on the 200 path.
Populated when status is REJECTED on the 200 path.
POST_ONLY_WOULD_CROSS, SELF_TRADE, UNDERCOLLATERALIZED, COULD_NOT_FILL, IOC_CANCELED, FOK_FAILED, REDUCE_ONLY_WOULD_INCREASE, TOO_MANY_CLIENT_IDS, DUPLICATE_CLIENT_ID, POSITION_TPSL_ALREADY_EXISTS, ENTRY_TPSL_CANNOT_BE_POSITION_TPSL, ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT, ORDER_NOT_FOUND_FOR_MODIFY, MODIFY_CHANGED_IMMUTABLE_FIELD, MODIFY_ZERO_SIZE, PRICE_WILL_EXCEED_MAXIMUM_OUTSIDE_RTH_TRADING_BOUND, MODIFY_WOULD_CROSS_OUTSIDE_RTH_TRADING_BOUNDARY, FILL_WILL_EXCEED_TRADING_BOUND, OPEN_INTEREST_CAP_EXCEEDED Per-subaccount order-pool rate-limit snapshot after this modify. Omitted when rate limiting is not configured.