POST

Markets and execution

Cancel order

/api/v2/orders/{order_uuid}/cancellations

AUTHENTICATIONBearer token · trading:writeService ownermatching-engineContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Request cancellation of an eligible open order.

When to use it

Call this when a market-data, trading, risk, or reconciliation client needs to apply the documented order transition after re-reading the current authoritative state so it can understand market, order, trade, position, or collateral state without confusing a read model with execution authority.

OUTCOME · Create or advance

What changes

Creates or advances only the order resource described by this contract after authorization, validation, policy, and idempotency gates pass.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance order.
Separates decision-support and reconciliation data from the controls that admit, match, publish, or settle an order.

ISOLATION + AUTHORITY

The authenticated owner, market, order, position, matching, risk, publisher, and settlement boundaries remain distinct. Documentation, contract visibility, and read access grant no execution authority; possession of a write scope still cannot bypass market status, risk, admission, allowlist, suspension, matching, publisher, or settlement gates. Current trading, matching, prediction, ingress, publisher, allowlist, suspension, market-status, and traffic controls remain frozen unless separately approved through their controlling process.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required order_uuid (path) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the current market status, owner-specific restrictions, risk posture, and applicable trading freeze before relying on this result.

WHAT TO DO NEXT

Re-read order using the canonical identifier returned by this operation.
Reconcile an ambiguous response with the same idempotency key before attempting another mutation.
Re-read the relevant market and owner-specific state before any later order or position decision, and preserve the current trading freeze.

AGENT GUIDANCE

Use order only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required order_uuid (path) exactly as defined by the live contract.
Distinguish market data, owner-specific restrictions, order admission, matching, fills, positions, collateral, cancellation, settlement, and finality; no one state implies another.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

Before submitting an order

Confirm the market admits orders and your account has the required permissions and collateral. A listed route does not enable a suspended market or select a matching engine. HTTP 202 means acceptance—not execution or settlement. After an ambiguous response, reconcile order state and reuse the same Idempotency-Key only for the same logical request.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the trading:write scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLElaunch-treasury-v1-001

order_uuidpathRequired

safe identifier · 8–128Canonical owner-scoped order identifier.EXAMPLEorder-1234

venuebodyOptional

dex | securities | virtualVenue containing the order; defaults to dex.

reasonbodyOptional

stringOptional operator-readable cancellation rationale.

REQUEST

JSON body example

{
  "venue": "securities",
  "reason": "client request"
}

RESPONSES

Status and payload examples

202Owner-scoped cancellation accepted.Accepted for processing · JSON RESPONSE+

{
  "order_id": "order-1234",
  "status": "CANCELLED",
  "revision": 3,
  "market_sequence": 184224
}

INTEGRATION DECISION

CALLER ACTION: Persist the returned tracking identifier or receipt, then re-read order using the canonical identifier returned by this operation.
RETRY SAFETY: Acceptance is not completion. Do not submit a duplicate while work is pending. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Poll or re-read authoritative state until it reaches a terminal result; preserve the last receipt while status is pending. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

400The JSON body or Idempotency-Key header is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_json",
  "message": "The JSON body or Idempotency-Key header is malformed."
}

INTEGRATION DECISIONinvalid_json

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

401The bearer credential is missing, expired, or invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is missing, expired, or invalid."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

403The credential lacks trading:write authority.Authority or policy denied · JSON RESPONSE+

{
  "code": "insufficient_scope",
  "message": "The credential lacks trading:write authority."
}

INTEGRATION DECISIONinsufficient_scope

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for market-scoped catalog, order, trade, position, collateral, and settlement projections while Python remains authoritative.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

404The owner-scoped order, trade, position, or market does not exist in the selected venue.Resource not visible · JSON RESPONSE+

{
  "code": "order_not_found",
  "message": "The owner-scoped order, trade, position, or market does not exist in the selected venue."
}

INTEGRATION DECISIONorder_not_found

CALLER ACTION: Verify the canonical identifier and authenticated owner boundary. A 404 may intentionally conceal a resource outside the caller's authority.
RETRY SAFETY: Do not retry the unchanged identifier repeatedly. Refresh the relevant collection or lookup before choosing another identifier.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

409Core could not reserve the replacement or closure requirement before submission; the existing order remains unchanged.State reconciliation required · JSON RESPONSE+

{
  "code": "insufficient_collateral",
  "message": "Core could not reserve the replacement or closure requirement before submission; the existing order remains unchanged."
}

INTEGRATION DECISIONinsufficient_collateral

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

409The idempotency key or authoritative lifecycle state conflicts with the request.State reconciliation required · JSON RESPONSE+

{
  "code": "order_conflict",
  "message": "The idempotency key or authoritative lifecycle state conflicts with the request."
}

INTEGRATION DECISIONorder_conflict

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

422The canonical mutation or authoritative matching implementation rejected the request.Request must change · JSON RESPONSE+

{
  "code": "order_rejected",
  "message": "The canonical mutation or authoritative matching implementation rejected the request."
}

INTEGRATION DECISIONorder_rejected

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

503Core or the current authoritative matching implementation is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "matching_unavailable",
  "message": "Core or the current authoritative matching implementation is unavailable."
}

INTEGRATION DECISIONmatching_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions. Use bounded backoff with jitter.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

OPERATIONAL NOTES

Security and lifecycle guarantees

The order is resolved within the authenticated owner and selected venue; callers cannot cancel another vault's order.
An identical retry returns the retained mutation receipt. HTTP 202 remains command acceptance until the read projection reflects terminal state.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory