Skip to main content
POST
Cancel an order and place a replacement non-atomically
Cancel one order and submit its replacement in one request. The two actions are not atomic: cancellation and replacement have independent outcomes, and a successful cancellation does not guarantee a successful replacement.

​
Request

replacement.ownerId must own the order being cancelled. Put onBehalfOf only at the operation level, not inside replacement. The x-on-behalf-of header is not supported by this endpoint.

​
Failure modes

​
Authentication and signing

Use a scoped API token with the trading scope and HMAC-sign the exact request body and path /orders/cancel-replace; see Authentication. The cancellation itself is not EIP-712 signed. For a direct request, the replacement is a normal order and must contain an EIP-712 signature. The authenticated profile must be a valid signer of the order being cancelled. For an authorized partner sub-account, set the operation-level onBehalfOf to the sub-account profile ID and set replacement.ownerId to the same ID. This path requires delegated_signing in addition to trading. If the replacement omits its order signature, the server signs it only for a managed server-wallet sub-account under the existing delegated signing rules.

​
Example: stop after cancellation failure

The order values below illustrate the request shape. Generate order.signature from the complete replacement payload instead of copying the placeholder signature.
If old-order-001 is not found, the response is 409 Conflict:

​
Example: allow replacement after cancellation failure

Changing mode to ALLOW_FAILURE attempts the replacement even if cancellation fails. The replacement reports its own result. The response remains 409 Conflict because the complete cancel-and-replace operation did not succeed:

​
Validation and outcomes

Request-level authentication, authorization, validation, market, signature, maintenance-mode, and receive-window failures return their ordinary HTTP status without a cancel/replace result. Maintenance-mode and receive-window rejections use 425 Too Early. A successful cancellation does not guarantee replacement success. Insufficient balance or allowance can produce cancel.status: "SUCCESS" with replacement.status: "FAILURE" and an HTTP-status error code such as "400"; the endpoint returns 409 Conflict. A receive-window or trading-availability rejection can likewise produce a successful cancellation with replacement.status: "FAILURE" and error.code: "425".

​
Response semantics

cancel.status can be SUCCESS, FAILURE, or UNKNOWN. replacement.status can be SUCCESS, FAILURE, UNKNOWN, or NOT_ATTEMPTED. Operation error codes are strings, not a closed enum. A missing cancellation target uses ORDER_NOT_FOUND; request failures use their decimal HTTP status such as 400, 404, 409, 425, or 500; other failures use INTERNAL_ERROR. FAILURE identifies a known failure and UNKNOWN an inconclusive outcome. Cancellation authorization failures remain request-level 401 or 403 responses.
replacement.status: "SUCCESS" means the placement was accepted. It does not guarantee on-chain settlement. A matched replacement remains top-level SUCCESS when replacement.data.execution.settlementStatus is FAILED; the settlement failure and reason remain nested under execution. There is no top-level SETTLEMENT_FAILED replacement status.

Authorizations

​
lmts-api-key
string
header
required

Scoped API token with HMAC-SHA256 signing. Requires three headers: lmts-api-key (token ID), lmts-timestamp (ISO-8601), lmts-signature (Base64-encoded HMAC). See Authentication docs for details.

Body

application/json
​
cancel
object
required

Order to cancel; provide exactly one identifier

​
replacement
object
required

Replacement order fields. This is the POST /orders request shape without onBehalfOf; delegation is set on the enclosing cancel-replace operation.

​
mode
enum<string>
required

Whether to stop this operation or attempt replacement after cancellation failure

Available options:
ALLOW_FAILURE,
STOP_ON_FAILURE
Example:

"STOP_ON_FAILURE"

​
onBehalfOf
number

Authorized partner sub-account profile ID. Applies to both cancellation and replacement.

Required range: x >= 1
Example:

12345

Response

Cancellation and replacement both succeeded

Independent cancellation and replacement outcomes.

​
cancel
object
required
​
replacement
object
required

The matching engine accepted the replacement. The canonical created-order, owner, maker-match, and execution schemas are reused; nested settlementStatus may still be FAILED with a free-form reason.