---
title: "Cancel a single order"
method: POST
path: "/orders/{order_id}/cancel"
tags: ["Orders"]
---

# Cancel a single order

`POST /orders/{order_id}/cancel`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/orders/{order_id}/cancel`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Cancels one order by internal id. Polymarket cancellation is an L2 API-key (HMAC) operation on the venue side, so no EOA/wallet signature is required — this works identically for custodial and external-signing orders.
**This endpoint almost always returns `200`, even on failure to cancel.** `success: false` with a `message` covers: the order is already terminal (filled/cancelled/expired/failed), or the venue currently refuses the cancel (still live — retry). Non-2xx status codes are reserved for auth/ownership/not-found/infrastructure failures, not "the cancel didn't happen."
**Cancel-before-submit race.** If the order hasn't reached the exchange yet (still `pending`/`queued`), it is cancelled locally via an atomic conditional update that races safely against the in-flight submission. If the submission wins that race (order mid-submission), the response is `success: false` asking the caller to retry shortly.
**Fill-during-cancel.** A venue acknowledgement is followed by terminal fill verification. Until the response carries `terminal_fill_verification.state: complete`, it returns `success: false` and consumers must keep protection active. The completed receipt's `final_filled_quantity` is the authoritative venue cumulative (never the latest fill delta), including explicit zero, and is published only after the corresponding Trade/Position fold. Kalshi may complete this barrier synchronously; other venues normally complete through the polling worker and expose the retained receipt on retry or `GET /orders/{order_id}`.
**Auth & scope.** Requires `trade:execute` and ownership of the order (`403` otherwise).

## Path parameters

- `order_id` string, uuid, required

## Response `200`

Cancel outcome. Check `success` — a `200` does not guarantee the order was actually cancelled (see description).

- OrderCancelResponse: Response for `POST /orders/{order_id}/cancel`. Returned with HTTP 200 even when `success` is `false`.
  - `success` boolean, required: Whether cancellation and terminal fill verification are both complete. A venue DELETE acknowledgement alone still returns false while verification is pending.
  - `order_id` string, uuid, required
  - `message` string: Human-readable outcome detail, e.g. "Order cancelled on exchange" or "Order is being submitted to exchange. Please try again in a moment."
  - `filled_quantity` string, nullable: Total cumulative filled quantity, decimal string, when terminal verification is complete. Omitted while pending or unknown; do not infer omitted as zero. The durable receipt repeats this exact cumulative in `final_filled_quantity`.
  - `avg_fill_price` string, nullable: Average fill price (decimal, 0..1) of any portion that filled before the cancel landed. Omitted when nothing filled or unknown.
  - `venue_reconciled` boolean, required: True only when a venue-final snapshot was observed and its exact cumulative fill has passed through Kairos' position fold. Currently authoritative for Kalshi.
  - `reconciled_position` ReconciledPositionExposure
    - `exchange_id` string, required: Canonical venue identity.
    - `market_id` string, required
    - `token_id` string, required
    - `outcome` string, nullable, required
    - `net_size` string, required: Exact signed post-fold position size as a decimal string, including zero.
    - `base_established` boolean, required: Explicit proof that the durable position base was established. A returned reconciliation authority always sets this to true; clients must fail closed when it is absent or false during rolling deployment.
    - `market_resolved` boolean, nullable, required: Tri-state resolution authority. Null means resolution was not proven and must not be interpreted as false.
  - `terminal_fill_verification` TerminalFillVerification
    - `state` 'pending' | 'complete', required
    - `exchange_order_id` string, required: Exact venue-order generation covered by the barrier.
    - `reason` 'explicit_cancel' | 'venue_absent', required
    - `target_status` 'cancelled' | 'expired', required
    - `started_at` string, date-time, required
    - `final_filled_quantity` string, nullable: Exact venue cumulative, including explicit `0`; required when state is complete.
    - `verified_at` string, date-time, nullable: Receipt completion timestamp; required when state is complete.

## Other responses

- `400`: No executor is registered for the order's exchange. Empty body (status code only).
- `401`: No valid credential presented — missing/invalid API-key headers or an invalid/expired session token.
- `403`: Order belongs to another user, missing `trade:execute` scope, or API-key access to the order's provider is disabled. Note this endpoint is behind the service-token/CSRF/API-key mutation gate, whose own rejections are `403` with a minimal `error` body. Otherwise empty body (status code only).
- `404`: No order with that id, or the order disappeared mid-cancel. Empty body (status code only).
- `500`: Database read/write failed, credentials could not be loaded, or the cancel outcome could not be confirmed at all. Empty body (status code only).
- `503`: API-key access to the order's provider could not be checked (fails closed). Empty body (status code only).

---

[API](https://skmtc.dev/kairos/apis/kairos-order-execution-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-order-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-order-execution-api/revisions/9ba7d463d505?raw)