Skip to main content
POST
Cancel a single order

Authorizations

X-Api-Key
string
header
required

Partner / integrator key — format ps_live_<keyId>_<secret>. Partner keys are issued by PredictStreet; a user can also create keys bound to their own wallet from their account settings in the web app. Never ship to a browser. multi_wallet partners must additionally send X-User-Wallet: 0x<40-hex> on every authenticated request to declare the acting wallet. See the API keys guide for scope taxonomy, partner kinds, rate limits, and rotation procedure.

Headers

X-User-Wallet
string

Required for multi_wallet partners on every authenticated request; ignored for single_wallet. Declares the acting end-user wallet for this request — drives KYC checks, balances/positions/orders attribution, rate-limit buckets, and audit. Lower-cased server-side. Missing on a multi_wallet key → 401 api_key_user_wallet_required; malformed → 401 api_key_user_wallet_invalid. The on-chain CTFExchange/Vault contracts still verify EIP-712 signer ↔ vault binding, so loosening API-layer attribution is safe by construction.

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3"

Body

application/json
orderId
string
required

Response

orderId
string
required

Server-side order id (echoes the request).

status
enum<string>
required

Cancel outcome. CANCELLED matches the OrderStatus enum every other endpoint returns. already_terminal — this wallet holds the order and it had already ended (cancelled, filled, expired, rejected, settlement failed). not_found — this wallet holds no such order (an unknown id, or another wallet's). Both are 200, NOT 404: the cancel call is idempotent, and a foreign id reads the same as an unknown one. cancel_pending — answered with HTTP 202 and Retry-After: 5 (also retryAfterSec): the cancel is recorded, but no answer to it is recorded yet (for example the matching engine is restarting and has not answered it). The order may still be open with its collateral held, and can still fill. Send the same cancel again after Retry-After: retrying with the same order id is safe, cannot cancel twice, and is what completes it soonest. The platform may also complete it on its own. Its final status (CANCELLED, or FILLED if it filled first) arrives on the user_orders WebSocket channel and on GET /api/orders/{id}. A retry answered 409 order_cancel_not_taken means the engine refused this cancel and the order is still open.

Available options:
CANCELLED,
not_found,
already_terminal,
cancel_pending
remainingQty
string

Quantity that was still unfilled at cancel time — the same meaning as remainingQty on /api/orders/place and /api/orders/{id}. Only set when status is CANCELLED.

code
enum<string>

Only with status=cancel_pending (HTTP 202): the same value, as a code to switch on.

Available options:
cancel_pending
message
string

Only with status=cancel_pending (HTTP 202): what the code means, in words.

retryAfterSec
number

Only with status=cancel_pending (HTTP 202): seconds to wait before sending the same cancel again; the same value as the Retry-After header.