> ## Documentation Index
> Fetch the complete documentation index at: https://spiceflow-docs.spicenet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conditional Intents API

> Register signed trigger plans, read revisions and cancel conditional execution

Use [`useSpiceConditionalIntents`](https://spiceflow-docs.spicenet.io/guides/conditional-intents) to prepare, review, sign and manage these requests. The application defines the protocol action and trigger; the SDK binds them to one accepted execution plan.

## Endpoints

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/conditional-intents` | Register a signed plan, or a signed replacement revision. |
| `POST` | `/conditional-intents/:id/signals` | Submit a fresh signal signed by the authorized evaluator. |
| `POST` | `/conditional-intents/:id/cancel` | Submit owner-signed cancellation. |
| `POST` | `/conditional-intents/read-token` | Exchange owner-signed read authorization for a short-lived token. |
| `GET` | `/conditional-intents?limit=20&cursor=...` | List current owner-scoped intents using a list read token. |
| `GET` | `/conditional-intents/:id` | Read an exact revision. |
| `GET` | `/conditional-intents/:id/current` | Resolve the current revision in its order family. |
| `GET` | `/conditional-intents/:id/revisions` | Read revision history for that family. |

The configured API service, evaluator and supported execution environment must match the signed authorization. A client cannot create an evaluator by rendering an order form.

## Registration contract

The registration body contains:

* `authorization` and `authorizationSignature`: owner consent binding the service and client, execution digest, execution-plan hash, trigger hash, evaluator, signal semantics, validity window and one allowed execution.
* `triggerSpecification`: the exact encoded trigger bytes covered by the authorization.
* `action`: one pre-signed `7702` execution owned by the same account, with `signatureType: "ecdsa"` and `nbf: 0`.
* Optional `executionWaits`: signed conditions for supported later EVM batches.

The execution signature must cover the conditional authorization's expiry. Finite registrations are limited to the supported validity window; the exported `CONDITIONAL_INTENT_UNTIL_CANCELLED` sentinel supports the explicit until-cancelled contract. Let the SDK set the matching signed fields rather than inventing a far-future timestamp.

A new registration returns `201`; an exact registration retry can return `200` with its original lifecycle. The response includes `conditionalIntentId`, `orderId`, `revisionId`, `revision`, `state`, `validAfter` and `expiresAt`, plus `actionId` once linked to execution.

## Signals and execution

Only a signal from the signed evaluator can make a registered intent eligible. It must match the intent, execution digest and trigger hash and fit the signed freshness and validity bounds.

`state` semantics require a sufficiently fresh observation when execution is claimed. `event` semantics latch an accepted qualifying event. Signal acceptance returns `202` for a new signal or `200` for an identical accepted duplicate; it is not an execution receipt.

Lifecycle states include `armed`, `eligible`, `executing`, `completed`, `cancelled`, `expired`, `failed` and `needs_attention`. Read the returned state and linked action rather than inferring success from registration or signal submission.

The backend worker owns execution after claiming the intent. Manual action-step execution is rejected for this managed action.

## Read access

Send the issued token as `Authorization: Bearer <readToken>` on reads. The signed read grant identifies owner, reader, service, intent scope, expiry and nonce. A zero intent ID requests owner-scoped list access; an exact intent ID requests that revision's scope. Tokens expire within the service's one-hour read window.

List requests accept `limit` from 1 to 50 and an opaque `cursor`. Use `nextCursor` from the response. A per-intent token does not grant owner-wide list access.

## Replacement and cancellation

To amend an order, prepare and sign a new registration with `authorization.replacesIntentId` identifying the prior revision. Submit it to `POST /conditional-intents`; there is no separate conditional `/amend` endpoint. The stable `orderId` connects immutable signed revisions, and `replacedBy` identifies the successor where present.

Cancellation requires owner-signed terms scoped to the service and exact intent, with a short expiry. It can cancel an unclaimed `armed` or `eligible` revision. Once an execution claim owns the action, cancellation or replacement can return `409`; do not display success or register a second action to bypass that result.

After a lost registration response, recover the original signed revision with the controller. Changing terms requires a fresh review and signature. A network failure is not proof that the earlier authorization was rejected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.