Prepare the wallet-signed TradeOrder_Cancel of an open order.
POST /api/v1/orders/{orderId}/cancel/prepare. Prepare the wallet-signed TradeOrder_Cancel of an open order.
Request
POST /api/v1/orders/{orderId}/cancel/prepare
Authentication is required. Supported credentials: a customer API key with trade scope in X-API-Key or a signed-in customer session token in Authorization: Bearer …. Send one credential type only; never both. API-key requests also require the Ed25519 headers described in request signing, and the key must be authorized for the selected Party.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
orderId | path | string | Yes | min length: 1; max length: 255; pattern: ^[A-Za-z0-9._:-]+$ | — |
X-Service-Act-As | header | string | No | min length: 3; max length: 512 | Service-principal path only (local and devnet stages; refused by configuration on mainnet). With an OAuth client-credentials bearer token from the validator, names the allow-listed Party the client acts as. Missing: 400 SERVICE_ACT_AS_REQUIRED; not allow-listed: 403 SERVICE_PARTY_NOT_ALLOWED. Ignored for customer session tokens. |
X-API-Timestamp | header | string | No | pattern: ^[0-9]{13}$ | Required with X-API-Key on trade operations: Unix time in milliseconds (13 digits), at most 1 s ahead of the server and no older than the receive window. |
X-API-Recv-Window | header | string | No | pattern: ^[0-9]{1,5}$ | Optional with X-API-Key on trade operations: signature validity window in milliseconds (default 5000, maximum 60000). It is part of the signed string. |
X-API-Signature | header | string | No | pattern: ^[A-Za-z0-9_-]{86}$ | Required with X-API-Key on trade operations: Ed25519 signature, unpadded base64url (86 characters), of the canonical string (see the apiKey security scheme). |
X-Request-Id | header | string | No | min length: 8; max length: 128; pattern: ^[A-Za-z0-9._:-]+$ | Optional client correlation identifier. The server always generates a separate authoritative request ID and retains a valid supplied value only as secondary audit correlation metadata. |
Send a signed request
Use the signed POST helper with this exact API path and the body declared above. It serializes and signs the same bytes it sends. Preserve the idempotency key and payload for a retry; create a fresh timestamp and signature.
A raw unsigned API-key request will be rejected. For the distinction between a request signature and a ledger signature, read the order flow.
Responses
201
The cancel command for sendTransaction.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
commandId | string | Yes | min length: 1; max length: 255 | — |
orderId | string | Yes | min length: 1 | — |
partyId | string | Yes | min length: 1 | — |
actAs | array of string · Schema 1 | Yes | min items: 1; max items: 1 | — |
commands | array of object · Schema 2 | Yes | min items: 1; max items: 1 | — |
disclosedContracts | array of object · Schema 3 | Yes | max items: 0 | — |
packageIdSelectionPreference | array of string · Schema 4 | Yes | max items: 4 | — |
Additional fields are not allowed.
400
The request is malformed or failed validation. Codes: VALIDATION_FAILED, AMBIGUOUS_CREDENTIALS, SERVICE_ACT_AS_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
401
Credentials are missing, malformed, expired or revoked. Codes: AUTHENTICATION_REQUIRED, INVALID_AUTHORIZATION_HEADER, INVALID_ACCESS_TOKEN, SESSION_REVOKED, API_KEY_INVALID, API_KEY_REVOKED, API_KEY_SIGNATURE_INVALID, API_KEY_TIMESTAMP_OUT_OF_WINDOW.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
403
The credential may not call this route. Codes: ACCOUNT_RESTRICTED, ANONYMOUS_ACCOUNT_NOT_ALLOWED, API_KEY_ROUTE_NOT_ALLOWED, SERVICE_PARTY_NOT_ALLOWED, SERVICE_PRINCIPAL_NOT_ALLOWED, SIGNUP_NOT_INVITED, API_KEY_IP_NOT_ALLOWED, PRODUCT_ACCOUNT_RESTRICTED, API_KEY_SCOPE_REQUIRED, API_KEY_PARTY_NOT_AUTHORIZED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
404
No such owned order.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
409
The order is no longer open.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
428
The signed-in account must accept the current product terms first. Codes: PRODUCT_LEGAL_ACCEPTANCE_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
429
The caller exceeded an IP or principal request budget.
| Header | Type | Description |
|---|---|---|
Retry-After | integer | Whole seconds to wait before retrying a rate-limited request. |
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
503
The ledger or database is unavailable. Also: AUTHENTICATION_UNAVAILABLE, AUTHORIZATION_UNAVAILABLE.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
default
Machine-readable API error. The HTTP status identifies the error class.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
Nested schemas
Field links above lead to the complete nested object, array, and variant definitions below. Required fields are scoped to their containing object.
Schema 1
Response 201.actAs
Type: array of string.
min items: 1; max items: 1
Array items: string. min length: 1
Schema 2
Response 201.commands
Type: array of object.
min items: 1; max items: 1
Array items: object · Schema 5.
Schema 3
Response 201.disclosedContracts
Type: array of object.
max items: 0
Array items: object · Schema 5.
Schema 4
Response 201.packageIdSelectionPreference
Type: array of string.
max items: 4
Array items: string. pattern: ^[0-9a-f]{64}$
Schema 5
Response 201.commands item
Type: object.
Additional field values: any value.
Source contract
This page is generated from the checked-in customer OpenAPI snapshot. Download JSON, download YAML, or compare the live API reference. Snapshot provenance records the retrieval date and checksum.