> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darknyx.trade/llms.txt
> Use this file to discover all available pages before exploring further.
> Cancel a resting order with a signed cancel request from the owning trading key.
# Cancel Order
**TL;DR**
`DELETE /orders/{order_id}` removes a resting order. The body carries a fresh
**trading-key signature** over the order id, cancel nonce, and current boot
session, proving the caller owns the order. Only the trading key that placed the
order can cancel it.
Auth: `Authorization: Bearer ` **and** a trading-key cancel signature in
the body.
## Path parameters
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------- |
| `order_id` | string | The 16-byte order id (hex) to cancel. |
## Request body
```json theme={null}
{
"trading_key": "…",
"cancel_nonce": "1",
"session_id": "…",
"trading_key_signature": "…"
}
```
| Field | Type | Required | Description |
| ----------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trading_key` | string | Yes | 32-byte hex. Must be the key that placed the order. |
| `cancel_nonce` | decimal string | Yes | A canonical `u64` decimal string bound into the signed cancel body. It must **strictly increase** per trading key; the string form avoids JavaScript precision loss. |
| `session_id` | string | Yes | Current 32-byte `/info.boot_session_id`, hex. It scopes the cancel to one engine boot. Programmatic clients verify the same value in the transport-attestation manifest; a substituted value only makes the engine reject the request. |
| `trading_key_signature` | string | Yes | 64-byte hex. Ed25519 signature over the canonical cancel body: `{ order_id, trading_key, cancel_nonce, session_id }`. |
The cancel nonce is part of the signed bytes, so a captured cancel request cannot
be replayed to cancel a *different* (later, same-id) order, because the canonical body,
and therefore the signature, differs.
The canonical body also binds the **boot session**, and the nonce must strictly
advance per trading key. Together these scope a signed cancel to one venue boot:
a cancel captured before a restart cannot be replayed against the session that
follows it, and one captured within a session cannot be replayed at all.
The session id is the same value place orders bind — the current
`/info.boot_session_id`. If you sign cancels yourself rather than through the
SDK, read it once per session and include it; a body missing it will not verify.
A CVM restart changes it, so refresh it before signing anything further.
## Example
```bash theme={null}
curl -s -X DELETE "$GATEWAY/orders/$ORDER_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"trading_key": "…",
"cancel_nonce": "1",
"session_id": "…",
"trading_key_signature": "…"
}'
```
## Success response
```json theme={null}
{
"order_id": "aa00000000000000000000000000000001",
"status": "cancelled"
}
```
| Field | Type | Description |
| ---------- | ------ | ------------------------- |
| `order_id` | string | The cancelled order's id. |
| `status` | string | `"cancelled"`. |
When an order is cancelled, the engine releases its collateral reservation and
drops the in-enclave note opening. A `cancelled` event is also emitted on the
[Orders Channel](../websocket/orders-channel.mdx) so a streaming client sees the
order leave without polling.
## Errors
| Condition | Status |
| ------------------------------------------------------------------------ | ------ |
| Malformed `order_id` / `trading_key` / signature hex | `400` |
| Missing or invalid bearer token | `401` |
| The signature does not verify, or the key does not own the order | `403` |
| No such (resting) order, already filled, expired, or cancelled | `404` |
| The cancel nonce did not advance, or the session belongs to another boot | `409` |
**Cancelling races the match**
An order can match in a batch between when you decide to cancel and when the
cancel lands. If the order has already left the book, the cancel returns `404`.
Treat a `404` on cancel as "the order is no longer resting" and reconcile via
[`GET /orders/{order_id}`](./get-order.mdx) or the orders stream.
## OpenAPI
````yaml api-reference/openapi/darknyx-public.yaml DELETE /orders/{order_id}
openapi: 3.1.0
info:
title: Darknyx TEE API
version: 4.1.0
description: |
Public + authenticated REST and WebSocket API for the Darknyx dark pool
TEE matching layer. One attested endpoint may expose several independently
routed spot markets. Pairs with the v2 on-chain custody program
(vault, program ID `C63vKvysCzX55PKraas4Wc22ijqjGJQdPC1mrzCFVWZx`).
contact:
name: Darknyx engineering
license:
name: PolyForm Perimeter License 1.0.1
url: https://polyformproject.org/licenses/perimeter/1.0.1
servers:
- url: https://api.darknyx.example.com
description: Mainnet placeholder; use the origin published with a deployment.
- url: https://api.devnet.darknyx.example.com
description: Devnet placeholder; use the origin published with a deployment.
security: []
tags:
- name: auth
description: OAuth2 client-credentials and bearer-token lifecycle.
- name: attestation
description: |
Darknyx engine and transport attestation plus the deployment gateway's
separate evidence bundle. Programmatic clients verify the certificate on
their actual connection with `/transport-attestation` before any
credential or sensitive write. `/evidences/*` describes surrounding
ingress infrastructure and is not a substitute for the engine check.
- name: info
description: |
Application/instance metadata, boot-session id, and settlement signers.
Verify measured identity through `/attestation`, not self-reported fields.
- name: instruments
description: Public market metadata.
- name: orders
description: Place / cancel / modify / inspect orders.
- name: system
description: Public engine liveness + server time (GTT slot conversion).
- name: account
description: Per-account open orders and preferences. Balances remain client-derived.
- name: tree
description: >-
Convenience Merkle-tree mirror; clients can verify the same state on
Solana.
- name: transparency
description: Public solvency snapshot + engine identity + aggregate stats.
- name: settlement
description: Batch settlement status (TEE → L1 tx_signature lookup).
paths:
/orders/{order_id}:
delete:
tags:
- orders
summary: Cancel an open order.
parameters:
- name: order_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelOrderRequest'
responses:
'200':
description: Cancellation processed.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelOrderResponse'
'400':
description: Malformed id, key, session, or signature encoding.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing / invalid / expired / revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >-
Account suspended, signature invalid, or trading key does not own
the order.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Order doesn't exist or is already terminal.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The cancel nonce did not advance or the boot session is stale.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
components:
schemas:
CancelOrderRequest:
type: object
required:
- trading_key
- cancel_nonce
- session_id
- trading_key_signature
properties:
trading_key:
type: string
description: 32-byte Ed25519 pubkey, hex.
cancel_nonce:
type: string
pattern: ^(0|[1-9][0-9]*)$
description: >-
Canonical decimal u64 string; strings preserve the full range in
JavaScript clients.
session_id:
type: string
description: |
32-byte hex boot session from /info; bound into the cancel signature
so a captured body cannot be replayed in a later boot. Programmatic
clients verify the same value in the transport-attestation manifest.
trading_key_signature:
type: string
description: 64-byte canonical cancel signature, hex.
CancelOrderResponse:
type: object
required:
- order_id
- status
properties:
order_id:
type: string
status:
type: string
enum:
- cancelled
Error:
type: object
description: |
The error envelope. Every non-2xx response renders as this shape, with
the mapped HTTP status. Success responses are NOT enveloped (their typed
body is returned directly). Every response — success and error — carries
an `x-request-id` header for correlation with server logs.
required:
- code
- message
properties:
code:
type: integer
description: |
Stable numeric error code. Ranges: 1000–1099 request validation,
1100–1199 auth, 1200–1299 conflict, 1300–1399 not found, 1400–1499
rate limit, 5000+ server. See the Error Codes reference.
One exception to the ranges: `1402` is returned with HTTP 503, not
429. It signals that credential verification is momentarily at
capacity and was refused rather than queued. Branch on the numeric
code rather than inferring the status from its range.
example: 1102
message:
type: string
example: trading_key_signature does not verify against the canonical body
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
Short-lived (≤ 1h) bearer token from POST /auth/token.
Expiry is EXACT — there is no grace period past `expires_in`, on REST
or on the streaming transport. Refresh on a margin.
A structurally valid, unexpired token is still refused when it has been
revoked (401), when the operator has invalidated the tokens the account
was holding (401), or when the account is suspended (403). Suspension
also blocks issuing a new one, so re-authenticating does not clear it.
````