API ReferenceExecution
Cancel an armed conditional order
const url = 'https://exec.predictefy.com/v1/exec/conditional/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel';const options = { method: 'POST', headers: {'Idempotency-Key': 'example', Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://exec.predictefy.com/v1/exec/conditional/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \ --header 'Authorization: Bearer <token>' \ --header 'Idempotency-Key: example'Requires Authorization: Bearer <api-key> with the trade scope and a unique Idempotency-Key. The order moves to canceled and any stored hosted artifact is erased in the same statement.
Cancellable means armed in either fire mode, plus triggered in client mode: nothing but you fires a client order, so you can still withdraw it after it triggers — until you reserve. A reservation you could still be acting on closes that window, because the venue submit it authorises never passes through this API: one that is live, one that was consumed however long ago, or any taken since the order was armed. One that predates the arm and has already lapsed does not. Report the outcome instead — fired, or not_submitted if the venue never accepted it. A triggered or firing hosted order belongs to the fire loop and answers CONDITIONAL_NOT_ARMED, as does one that has already fired or expired.
Cancelling an already-canceled order is a no-op success, and so are two concurrent cancels: both receive the canceled order rather than one of them taking a spurious conflict.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Conditional (take-profit / stop-loss) order id.
Header Parameters
Section titled “Header Parameters”Caller-generated non-empty key. Build/cancel/modify keys identify newly persisted intents; a submit key identifies that relay attempt and cannot be rebound to another ID. The literal strings undefined and null are rejected with 400 VALIDATION_ERROR, so a client that stringified a missing key cannot bind or replay one. Two prefixes are RESERVED by the execution service for keys it mints itself and are rejected with 400 RESERVED_IDEMPOTENCY_KEY before anything is written: cond: (a hosted conditional order's own fire key) and dry-run: (the preview key handed to a venue lane). The match is case-sensitive.
Responses
Section titled “Responses”The canceled conditional order.
object
An armed take-profit / stop-loss order. The stored artifact, its hash, its key id and any fire lease are deliberately absent from this shape and are never returned.
object
The trusted-edge country at arm time, re-applied to the venue geofence at fire.
Present on the single-order read only.
One append-only transition, with the evidence that caused it.
object
The trigger rule. Every optional field has an engine default that is stored explicitly on the armed row, so an order always says exactly what it meant.
object
The direction the reference price must cross.
The probability the reference must reach.
mark is the median of best bid, best ask and a fresh last trade; bid/ask select the executable side explicitly.
Consecutive qualifying samples required before the order triggers.
How long the condition must hold, measured on book timestamps.
No trigger while the book's spread is wider than this.
The qualifying quote must show at least this size.
Sugar. Rewritten to when from the stored order's side (a stop sells below and buys above; take-profit mirrors it), and echoed back on the stored rule.
Example
{ "success": true, "data": { "events": [ { "actor": "api" } ], "fireMode": "hosted", "status": "armed", "trigger": { "when": "at_or_above", "reference": "mark", "confirmations": 2, "dwellMs": 2000, "maxSpread": 0.1, "minSize": 1, "tpsl": "tp" } }}A missing or RESERVED Idempotency-Key, or an invalid request/body/lifecycle state.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Missing, invalid, unknown, or revoked Predictefy API key.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The API key lacks the mandatory trade scope, or the account's plan does not include conditional orders (Pro is the minimum).
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The conditional order is missing or not owned by the caller, or the family is not enabled for this account.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The conditional order has already left the state this change requires — a trigger, expiry, or cancel landed first. Cancel also returns CONDITIONAL_NOT_ARMED for a triggered client order whose linked execution is no longer built, or that carries a reservation you could still be acting on — a live one, a consumed one however old, or any taken since the order was armed — checked under its execution row lock. A reservation hands the caller a token to submit with, and that submission never passes through this API, so the order stays triggered and can no longer be canceled: use /v1/exec/conditional/{id}/report to report the outcome instead — that route decides which outcomes it accepts for the state the execution is actually in. A reservation that predates the arm and has already lapsed does not fence. A sibling attempt that still owns an outstanding marker or unreturned token refuses not_submitted with CONDITIONAL_ATTEMPT_CONFLICT. Nothing is released or cleared. New reservation issuance and ordinary submission also return this code if another attempt owns the outstanding marker. Tokens already issued remain acknowledgeable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The authenticated execution token bucket is exhausted.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Unexpected internal execution failure.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Authentication, billing, or execution storage is temporarily unavailable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}