Conditional Intents and Limit Orders

SDK 4.19.0 exposes useSpiceConditionalIntents and useSpiceLimitOrders. They are separate APIs with separate lifecycle objects. Both require a ready embedded wallet in 7702 mode and a configured backend that supports the requested service. Registration is not transaction completion.

Conditional Intents

useSpiceConditionalIntents() prepares a fixed action for a configured trigger service and evaluator. The host defines the trigger specification and protocol calls; the SDK binds the reviewed calls and trigger bytes to the signatures and registration request.

Draft Fields

Field	Type / meaning
`clientId`, `serviceId`	Strings identifying your configured client and conditional service
`evaluator`	Evaluator address authorized for the trigger
`triggerSpecification`	Exact hex-encoded trigger specification understood by your service; not an arbitrary human-language prompt
`semantics`	`"state"` or `"event"`
`maxSignalAgeSeconds`	Bigint freshness bound, 1 through 86,400 seconds
`validAfter`, `expiresAt`	Unix seconds as bigints; valid-after must not exceed expiry; expiry must be future and within 30 days
`chainBatches`	Fixed nonempty action batches for `prepare`; each batch needs a valid chain and calls

prepare(draft) does not turn arbitrary protocol calls into a funded or fee-quoted action. Supply complete executable batches, including required funding and fee calls, and review their validity at execution time. For the supported swap path use prepareSwap, which owns its swap/funding/fee plan. prepareSwap(draft) replaces chainBatches with chainId, tokenIn, tokenOut, amountIn, minimumOutput, and an AerodromeVenueConfig in venue. Amounts are raw token-unit bigints. amountMode is "fixed-input" or "input-inclusive". Review the returned swapAmountIn, fees, feeFundingSource and feeSourceAmount; do not infer the executable swap input from the gross budget. A zero minimum output does not protect the fill price. Show any actionSummary disclosure.

Review, Sign and Register

Keep the hook mounted throughout preparation, review, signing and registration. Use the exact object returned by that hook; a serialized, cloned or independently reconstructed object cannot replace it. A wallet/provider/API change requires a new preparation.

import { useState } from "react";
import {
  useSpiceConditionalIntents,
  type ConditionalIntentDraft,
  type PreparedConditionalIntent,
} from "@spicenet-io/spiceflow-ui";

export function useConditionalReview() {
  const intents = useSpiceConditionalIntents();
  const [review, setReview] = useState<PreparedConditionalIntent | null>(null);

  async function prepare(draft: ConditionalIntentDraft) {
    const prepared = await intents.prepare(draft);
    setReview(prepared);
    return prepared;
  }

  // Call only after rendering the prepared action and obtaining user confirmation.
  async function confirm() {
    if (!review) throw new Error("Prepare and review an action first");
    const signed = await intents.sign(review);
    setReview(signed);
    return intents.register(signed);
  }

  return { prepare, review, confirm, get: intents.get, list: intents.list, cancel: intents.cancel };
}

Render actionSummary (chain, target, value, selector and available swap bounds), the trigger and expiry, and the returned fee data before calling confirm. The prepared object reports additionalSignatureCount: 2 plus delegationAuthorizationCount. These are signature requirements, not a promise of a particular number of wallet popups. The trigger is enforced by the conditional-intent service; it is not an on-chain condition added to every protocol call. Registration does not guarantee a later fill: balances, liquidity, allowances, contract state and the authorization’s validity must still permit execution.

Read and Cancel

Method	Behavior
`authorizeRead(serviceId)`	Obtain a cached wallet-authorized read token; can request a signature
`get(id, serviceId)`	Read one intent; obtains read authorization as needed
`list(serviceId, { limit?, cursor? })`	Return `intents` and optional `nextCursor`
`cancel(id, serviceId)`	Sign and submit cancellation; inspect the returned status

Status reads can prompt for a read signature. Keep polling and cancellation tied to the current wallet and service. Cancellation cannot undo a transaction already executed; reconcile returned status and receipts before presenting funds as available or creating a replacement.

Limit Orders

useSpiceLimitOrders({ combineSourceBalances?: boolean }) handles supported limit swaps funded from account Cash. Combined funding is off by default; opting in lets the SDK fund a shortfall from an eligible account-wallet balance. It may submit a real deposit during placement before registering the order, so placement is not a read-only call.

`LimitOrderInput` field	Meaning
`chainId`, `tokenIn`, `tokenOut`	Supported execution chain and token addresses
`grossAmount`	Total raw input-token budget including execution fees
`minimumOutput`	Positive raw output-token minimum
`expiresAt`	Unix seconds as a number, in the future and within 30 days
`venue`	Optional Aerodrome Slipstream configuration; the built-in Base configuration is the default

Use the methods in this order, with the same mounted hook:

Wait for canPrepare, then call prepareOrder(input).
Render the returned amountIn, minimumOutput, feeAmount, grossAmount and any funding or fundingWarning. The funding fields use the original source asset’s units; grossAmount is the escrow budget after any funding fee.
After user confirmation call signOrder(prepared) and retain its exact returned request.
Check canPlace(request) and call placeOrder(request).
Read getOrder(id) or listOrders(after?); cancel with cancelOrder(id).

Render status.step, status.message, status.isExecuting, status.pending and status.error. Call refreshStatus() after an uncertain funding or registration outcome; do not start a fresh funding sequence to work around a pending original order. Retain the original signed request while the hook remains mounted so the SDK can reconcile placement rather than deposit twice. listOrders returns { orders, nextCursor }. Order statuses are open, executing, filled, cancelled, expired, failed and needs_attention. Inspect actionId, transactionHash, lastError and any balance warning. An open order is not a fill, and a reserved amount is not proof that all execution-time funding is available.

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

Conditional Intents and Limit Orders