API ReferenceExecution
Arm a take-profit / stop-loss trigger on a built execution
const url = 'https://exec.predictefy.com/v1/exec/hyperliquid/orders/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/arm';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"fireMode":"hosted","trigger":{"when":"at_or_above","price":1,"reference":"mark","confirmations":2,"dwellMs":2000,"maxSpread":0.1,"minSize":1,"tpsl":"tp"},"expiresAt":"2026-04-15T12:00:00Z","ocoGroupId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","artifact":{},"marketId":"example","outcomeId":"example"}'};
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/hyperliquid/orders/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/arm \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "fireMode": "hosted", "trigger": { "when": "at_or_above", "price": 1, "reference": "mark", "confirmations": 2, "dwellMs": 2000, "maxSpread": 0.1, "minSize": 1, "tpsl": "tp" }, "expiresAt": "2026-04-15T12:00:00Z", "ocoGroupId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "artifact": {}, "marketId": "example", "outcomeId": "example" }'Requires Authorization: Bearer <api-key> with the trade scope and a unique
Idempotency-Key. DARK: the conditional family is registered only on deployments that
enable it, and an account outside its beta allowlist receives 404 ROUTE_NOT_FOUND.
The path executionId must name one of your own executions that is still built. This
operation builds nothing, signs nothing, and relays nothing — it attaches a trigger rule
to an existing intent.
Two fire modes:
-
client(every venue): Predictefy watches the book and emitsconditional.triggeredwhen the rule is satisfied. You submit with your own credentials and call the report operation.artifactis refused in this mode. -
hosted(only whereGET /v1/exec/venuesreportsconditional.hosted: true): you supplyartifact, the already-signed submit body you would have posted yourself. It is encrypted at rest and replayed by the execution service when the trigger fires. A venue whose submit needs any caller credential is refused withHOSTED_FIRE_NOT_ELIGIBLE, and a deployment holding no artifact key answersHOSTED_FIRE_UNAVAILABLEwhile client arming keeps working. The artifact carries ONLY the fields that venue's submit reads, each in the shape that submit expects, and it must carry the ones that submit cannot run without. For Limitless bothownerandsignatureare REQUIRED:owneran EVM address string,signaturea 65-byte0xhex ECDSA signature that parses as r-s-v. A 32-byte value is a wallet private key, not a signature, and is refused as one.executionIdis optional and must be a uuid matching the path.Any other field is refused, the order itself included: the service relays the order it stored at build, which is what stops a signed body being swapped for a different trade. A field carrying an object or an array where a string belongs is refused for the same reason. The artifact must also contain no credential field of any kind, matched however the name is spelled, and nest at most six levels, so nothing we cannot inspect is stored.
trigger.tpsl is accepted as sugar and rewritten to trigger.when from the stored order's
side. expiresAt is required, must be in the future and within a year, and must be at or
before the market close when the catalog knows it.
trigger.price and trigger.maxSpread must sit on the engine's 1e-6 tick grid — at most
six decimals. The engine compares in whole ticks, so an off-grid rule could never mean what
it says: 0.4100004 would trigger at 0.41, and 0.4050005 would never match at all. Like
every other bound here it is a 400 VALIDATION_ERROR, never a silent rounding, because a
rounded trigger is a different trigger from the one you asked for.
One execution may own at most ONE live conditional order (armed, triggered, or
firing): arming a second answers 409 CONDITIONAL_ARMED. Retrying the ORIGINAL arm with
its own Idempotency-Key still replays, because the key is read first.
An execution whose conditional the customer closed as not_submitted is closed off for
good and arming it again answers 409 CONDITIONAL_CLOSED_NOT_SUBMITTED, in either fire
mode — the same fence reserve, submit and ack hold. That report says nothing reached the
venue, so a second order on the same execution (a hosted one especially, which fires with
no customer call at all) would put a live venue order beside it. Build a new execution.
ocoGroupId groups orders one-cancels-other. A group accepts new members only while every
member is still armed; joining one that already holds a triggered, fired, canceled, or
expired member answers 409 OCO_GROUP_CLOSED. Groups are per account, so your chosen uuid
is never visible to or closeable by another tenant.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Execution venue slug. Availability is deployment-specific; discover armed lanes with GET /v1/exec/venues. Settlement-only lanes may appear but report order verbs false.
Account-owned execution UUID.
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.
Request Bodyrequired
Section titled “Request Bodyrequired”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.
When the armed order expires. Must be in the future, within a year, and at or before the market close when the catalog knows it.
One-cancels-other group; triggering one member cancels its siblings.
HOSTED ONLY, and required there: the already-signed submit body you would have posted yourself. Stored encrypted (AES-256-GCM) and never returned by any read. It must carry no credential field; executionId, if present, must match the execution being armed. Refused for client mode.
object
Only consulted when the stored artifact does not name the market itself. The value read from the artifact always wins.
Only consulted when the stored artifact does not name the outcome itself. The value read from the artifact always wins.
Responses
Section titled “Responses”A duplicate Idempotency-Key replays the original armed 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" } }}Headers
Section titled “Headers”Present with value true when stored state satisfied an idempotent retry.
The armed 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, an invalid trigger/expiry/artifact, an execution that is no longer built when locked, an execution that is not an ORDER (intent: order) — a cancel, modify or redeem execution is refused, because only an order can be a conditional's leg — or a venue that can never be armed in hosted mode. Hosted signatures require exactly 65 bytes, nonzero r and s below the secp256k1 curve order, canonical low-s, and v of 27/28 or 0/1. Limitless owner recovery still runs at fire time because its trusted EIP-712 exchange domain is not stored in the build available to arm.
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 build would breach a configured execution spend cap.
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 trade scope, the venue geofence rejected the request, 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 venue lane is absent, the execution is missing or not owned by the caller, or the conditional 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 stored build is incompatible, this execution already has a live conditional order, the customer already closed a conditional on it as not_submitted (which says nothing reached the venue and closes the execution off for good — build a new one), or the named OCO group already holds a member that is no longer armed.
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" }}The execution service is unavailable, or hosted conditional arming has no artifact key on this deployment (client arming is unaffected).
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" }}