Manual vs Auto Mode

Execution Modes

Declare which modes your agent supports in circuit.toml:

allowedExecutionModes = ["manual", "auto"]

auto - Transactions execute immediately when your code calls a transactional SDK method
manual - Supported money actions become suggestions that the user must approve in the Circuit UI before they are broadcast. Methods without a suggestion card are rejected.

Manual mode captures only SDK methods backed by a suggestion card: swaps; Polymarket marketOrder and redeemPositions; Hyperliquid placeOrder and deleteOrder; and Kraken placeOrder and cancelOrder. Raw transactions, transfers, signMessage, and any other method without a suggestion card fail instead of executing. For card-backed methods, the same call works in both modes and returns a suggestion envelope when the session is manual. The first entry in the array is the default mode for circuit run when you don’t pass --mode. Manual approvals require Circuit’s hosted suggestion store and approval UI. A fully embedded run rejects a resolved manual mode before authentication, funding, dependency installation, or agent spawn. A --dry-run may keep the agent’s manual branch because it cannot cause effects, but it warns that writes are journaled and approvals are not simulated.

Same Code, Different Behavior

You write the same code regardless of mode. Circuit handles the routing:

# This code works in both auto and manual mode
midpoint = agent.platforms.hyperliquid.midpoint_price("BTC")
if not midpoint.success or midpoint.data is None or isinstance(midpoint.data, list):
    raise RuntimeError(midpoint.error or "No BTC midpoint")
btc_mid = float(midpoint.data.price_usd)

result = agent.platforms.hyperliquid.place_order({
    "coin": "BTC",
    "side": "buy",
    "size": 0.001,
    "price": btc_mid * 1.01,  # 1% above the live mid for a market buy
    "market": "perp",
    "type": "market",
})

# In auto mode: result.data.order_id is the order id
# In manual mode: result.data.suggested = True, result.data.suggestion_id is a UUID string

// This code works in both auto and manual mode
const midpoint = await agent.platforms.hyperliquid.midpointPrice("BTC");
if (!midpoint.success || !midpoint.data || Array.isArray(midpoint.data)) {
  throw new Error(midpoint.error || "No BTC midpoint");
}
const btcMid = Number(midpoint.data.priceUsd);

const result = await agent.platforms.hyperliquid.placeOrder({
  coin: "BTC",
  side: "buy",
  size: 0.001,
  price: btcMid * 1.01, // 1% above the live mid for a market buy
  market: "perp",
  type: "market",
});

// In auto mode: result.data.orderId is the order id
// In manual mode: result.data.suggested = true, result.data.suggestionId is a UUID string

Suggestion Lifecycle

In manual mode:

Your agent calls a card-backed method such as placeOrder, marketOrder, swap.execute, redeemPositions, deleteOrder, or cancelOrder
Circuit creates a suggestion visible to the user in the UI
The user approves or ignores the suggestion
If approved, Circuit executes the transaction
At the start of the next run cycle, all unapproved suggestions are automatically cleared

`expiresAt`

Suggestion-producing methods accept an optional expiresAt parameter (ISO 8601 timestamp). If the user hasn’t approved by this time, the suggestion is discarded. Useful when the transaction is only valid for a limited window (e.g., a quote that expires).

Checking Mode at Runtime

if agent.execution_mode == "manual":
    agent.log("Suggesting a swap - please approve in the Circuit UI")

if (agent.executionMode === "manual") {
  // Optionally provide more context in logs for manual mode users
  await agent.log("Suggesting a swap - please approve in the Circuit UI");
}

Which Modes to Use

Scenario	Recommended Modes
Fully automated strategy (yield farming, rebalancing)	`["auto"]`
User wants full control over each trade	`["manual"]`
Flexible - let the user decide	`["manual", "auto"]`

Notes

If your agent only supports ["auto"], it cannot be run in manual mode.
If your agent only supports ["manual"], every transaction requires user approval.
The clearSuggestedTransactions() method lets you manually clear pending suggestions mid-execution. See Suggestions.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Manual vs Auto Mode

Execution Modes

Same Code, Different Behavior

Suggestion Lifecycle

`expiresAt`

Checking Mode at Runtime

Which Modes to Use

Notes

See Also

​Execution Modes

​Same Code, Different Behavior

​Suggestion Lifecycle

​expiresAt

​Checking Mode at Runtime

​Which Modes to Use

​Notes

​See Also

Execution Modes

Same Code, Different Behavior

Suggestion Lifecycle

`expiresAt`

Checking Mode at Runtime

Which Modes to Use

Notes

See Also