Skip to main content
POST
/
v1
/
cancelOrder
Cancel order
curl --request POST \
  --url https://api.testnet.arcus.xyz/v1/cancelOrder \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "address": "<string>",
  "marketId": 32767,
  "accountIndex": 4,
  "kind": "orderId",
  "orderId": "<string>",
  "validUntil": 123,
  "signature": "<string>",
  "timestamp": 4611686018427388000
}
'
{
  "address": "<string>",
  "accountIndex": 4,
  "marketId": 32767,
  "marketDisplayName": "<string>",
  "updateTime": 123,
  "orderId": "<string>",
  "clientId": "<string>",
  "remainingSize": "<string>",
  "filledSize": "<string>",
  "rateLimit": {
    "remaining": 123
  }
}
Cancel an open order by ID. Requires address query parameter matching the master Ethereum address for X-API-Key.

​
Response behavior

Asynchronous. The endpoint returns either 202 Accepted (the common case — the signed cancel was forwarded to the matching engine and the body does not carry terminal state) or 200 OK (the gateway already had definitive state for the cancel by the time it responded; status reflects that state). In both cases the body echoes the targeted orderId / clientId so subscribers can correlate WebSocket events with the request. To observe the resulting state (CANCELED, or FILLED if the order completed before cancel was processed) clients must subscribe to the orders WebSocket channel.

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:

placeOrder:   {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,"m":N,"op":1,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1}
cancelOrder:  {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1}
modifyOrder:  {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"v":1}

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

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

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.

Query Parameters

​
address
string
required

Master Ethereum address for this API key (must match address from POST /createApiKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

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

Body

application/json

Cancel target is exactly one of orderId (server-generated, CancelByOrderId) or clientId (from place order, CancelByClientId). Sending both is rejected by the server with HTTP 400.

​
address
string
required

Master Ethereum address for this API key (must match POST /createApiKey for the same key). May be sent here and/or as the address query parameter; if both are set, they must match.

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

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

Required range: 0 <= x <= 9
​
kind
enum<string>
required

Discriminator selecting the server-id cancel variant.

Available options:
orderId
​
orderId
string
required

Server-generated order ID to cancel (hex string).

Minimum string length: 1
​
validUntil
integer<int64> | null

Optional valid-until timestamp.

​
signature
string

Per-cancel Ed25519 signature (128 hex). REQUIRED when this cancel is an element of a POST /batchCancelOrders cancels array; omitted for single POST /cancelOrder (which uses X-Signature in the HTTP header instead).

Covers the ordersign typed canonical payload for this cancel (op=2): {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1}

ct must equal the shared X-Timestamp header value. Keys in brackets are conditional (omitted when empty — exactly one of id or c must be present).

​
timestamp
integer<int64>

Optional request timestamp (epoch ms).

Required range: 1 <= x <= 9223372036854776000

Response

Cancel processed and the gateway already has definitive state. status reflects that state (CANCELED / FILLED / REJECTED). Treat as best-effort enrichment of the 202 path; the orders WebSocket channel is still the source of truth.

Cancel response. The HTTP call is asynchronous and may return either:

  • 202 Accepted — common case. status is CANCEL_ACKNOWLEDGED and the body carries no terminal state; the orders WebSocket channel delivers the resulting state.
  • 200 OK — the gateway already had definitive state for the cancel by the time it responded. status reflects that state (CANCELED on success, FILLED if the order completed before the cancel landed, REJECTED if go-core refused the cancel) and enrichment fields may be populated. Clients should treat this as best-effort and not rely on it.

In both cases the body echoes exactly one of orderId (cancel targeted server id) or clientId (cancel targeted client id), so subscribers can correlate WebSocket events with the request. To observe the full lifecycle clients must subscribe to the orders WebSocket channel.

​
address
string
required

Master Ethereum address of the account that canceled the order.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
accountIndex
integer
required

Account index (subaccount) that canceled the order.

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
​
marketDisplayName
string
required

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

Example:

"BTC-USD"

​
status
enum<string>
required

CANCEL_ACKNOWLEDGED on the 202 path. On the 200 path, the definitive go-core state (CANCELED / FILLED / REJECTED). Subscribe to the orders WebSocket channel for the full lifecycle.

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:

"CANCEL_ACKNOWLEDGED"

​
updateTime
integer<int64>
required

On the 200 path, epoch microseconds of the definitive go-core state. On the 202 path, the gateway clock at the moment the cancel was forwarded to go-core.

​
orderId
string

Echoed when the cancel used orderId. Also populated when a clientId-scoped cancel was resolved to a concrete server id via the firehose before returning.

​
clientId
string

Echoed when the cancel used clientId.

​
remainingSize
string

Unfilled size at updateTime, in human-readable base-asset units. Populated only on the 200 path; otherwise see the orders WebSocket channel.

​
filledSize
string

Cumulative filled size at updateTime, in human-readable base-asset units. Populated only on the 200 path; otherwise see the orders WebSocket channel.

​
rejectionReason
enum<string>

Machine-readable reason when go-core rejected the cancel on the 200 path. Otherwise rejection reasons are delivered via the orders WebSocket channel.

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
​
rateLimit
object

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