Skip to main content
POST
Modify order
The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.
Modify the price and/or quantity of an open order. A modify is applied in place — preserving queue priority — only when it keeps the same price and reduces size. Any other change (a price move, or a size increase) is handled as an atomic cancel + replace, which loses queue priority. Requires 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. ALO modifies are prioritized like cancels. A modify on a post-only (ALO) order can only shrink or reprice a maker order — it can never take liquidity — so it is routed on the high-priority path ahead of order placements, the same as cancels (and skips the taker speed bump). Modifies with any other timeInForce ride the normal path and are subject to the speed bump. Like a cancel, a prioritized modify may be processed ahead of an earlier not-yet-sequenced placement of its own target, which would then reject as ORDER_NOT_FOUND_FOR_MODIFY (and, under cancel-replace modify semantics, be buffered briefly and applied when the placement arrives). 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. Cancel-replace semantics (feature-flagged rollout). When the modify_cancel_place engine flag is active, every modify unconditionally cancels the original order and re-places it under the same orderId: the orders channel emits a CANCELED update with cancelReason: MODIFY_CANCELED immediately followed by the replacement outcome (PLACED, fills, or REJECTED). Under these semantics:
  • A modify whose target has not yet reached the book is rejected with ORDER_NOT_FOUND_FOR_MODIFY but also buffered briefly — if the target placement arrives shortly after, it is canceled (MODIFY_CANCELED) and replaced with the modify’s parameters, mirroring buffered-cancel behavior.
  • Untriggered TPSL orders cannot be modified: the modify is rejected with MODIFY_TPSL_NOT_SUPPORTED and a live TPSL survives unchanged. If a buffered modify meets an arriving TPSL placement, the TPSL is canceled as a precaution.
  • A pending cancel always dominates a modify for the same order; the modify is rejected with MODIFY_SUPERSEDED_BY_CANCEL and the order’s final state is canceled.

​
Response behavior

Asynchronous. Returns either 202 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

​
X-API-Key
string
header
required

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.

​
X-Timestamp
string
header
required

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).

​
X-Signature
string
header
required

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) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.

Batch endpoints (batchPlaceOrders, batchCancelOrders, batchModifyOrders) 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 / ModifyOrderRequest).

Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required. 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

application/json

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.

​
address
string
required

Master Ethereum address for this API key (must match POST /createApiKey for the same key).

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
​
accountIndex
integer
required

Account index (account index, 0–9). Identifies the account for orders, positions, fills, and API keys.

Required range: 0 <= x <= 9
​
marketId
integer
required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535
​
goodTilTime
string
required

The 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).

Minimum string length: 1
​
quantity
string
required

New 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).

Minimum string length: 1
Pattern: ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$
​
price
string
required

New price in human-readable USD (e.g. "50000.5").

Minimum string length: 1
Pattern: ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$
​
side
enum<string>
required
Available options:
BUY,
SELL
​
timeInForce
enum<string>
required

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.

Available options:
GTT,
IOC,
FOK,
ALO
​
reduceOnly
boolean
required

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.

​
orderId
string

Server-generated order ID to modify (hex string). Provide exactly one of orderId or clientId, never both.

Minimum string length: 1
​
clientId
string | null

Identify 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.

Maximum string length: 36
Pattern: ^[A-Za-z0-9_-]+$
​
clientTime
string | null

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.

​
signature
string

Per-modify Ed25519 signature, required inside POST /batchModifyOrders only (single POST /modifyOrder signs via the X-Signature header instead). Covers the same typed canonical modify payload as a standalone modifyOrder — the signed bytes are identical whether the modify is submitted alone or in a batch: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1}

Keys in brackets are conditional (omitted when empty — exactly one of id or c must be present, matching the request's identity field).

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. status is ACK and the body carries the replacement orderId for correlation; the orders WebSocket channel delivers the lifecycle.
  • 200 OK — the gateway already had definitive state for the replacement order by the time it responded.
​
address
string
required

Master Ethereum address of the account that modified the order.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
accountIndex
integer
required

Account index (subaccount) that modified the order.

Required range: 0 <= x <= 9
​
clientTime
integer<int64>
required

Parsed clientTime from the request when provided as an integer-like string; otherwise 0.

​
orderId
string
required

Server-generated id of the replacement order created by the modify operation.

​
marketId
integer
required

Perpetual market identifier (uint16). Map to display name via GET /markets. Used for orders, positions, funding, and market metadata.

Required range: 0 <= x <= 65535
​
marketDisplayName
string
required

Market symbol (e.g. BTC-USD).

Example:

"BTC-USD"

​
status
enum<string>
required

ACK on the 202 path. On the 200 path, the definitive state.

Available options:
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
Example:

"ACK"

​
updateTime
integer<int64>
required

Gateway clock (epoch microseconds) at the moment the modify was forwarded to the matching engine.

​
clientId
string

Echo of the client id attached to the replacement order, when provided.

​
timeInForce
enum<string>

Echo of the time-in-force from the modify request.

Available options:
GTT,
IOC,
FOK,
ALO
​
goodTilTime
string

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.

​
remainingSize
string

Unfilled size of the replacement order. Populated only on the 200 path.

​
filledSize
string

Cumulative filled size of the replacement order. Populated only on the 200 path.

​
rejectionReason
enum<string>

Populated when status is REJECTED on the 200 path.

Available options:
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,
POSITION_SIZE_CAP_EXCEEDED,
MODIFY_TPSL_NOT_SUPPORTED,
MODIFY_SUPERSEDED_BY_CANCEL,
MODIFY_SIZE_ALREADY_FILLED
​
error
string

Present when status is ERROR — a per-row failure inside POST /batchModifyOrders (validation, signature, or immutable-field mismatch). Never set on single POST /modifyOrder responses, which report failures at the HTTP level instead.

​
rateLimit
object

Per-subaccount order-pool rate-limit snapshot after this modify. Omitted when rate limiting is not configured.