Skip to main content

​
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 — Transactions become suggestions that the user must approve in the Circuit UI before they are broadcast
Manual mode is a strict safeguard: every value- or signature-producing SDK method is captured for approval, never executed by the agent run. This includes swaps, Polymarket and Hyperliquid orders, raw transactions, Polymarket redeemPositions, Hyperliquid deleteOrder / transfer, and signMessage. You never have to special-case manual mode in your agent code — 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 used when you don’t pass --mode to circuit run --hosted engine.

​
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
result = agent.platforms.hyperliquid.place_order({
    "coin": "BTC",
    "side": "buy",
    "size": 0.001,
    "price": 100000,
    "market": "perp",
    "type": "limit",
})

# 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

​
Suggestion Lifecycle

In manual mode:
  1. Your agent calls any transaction- or signature-producing method (e.g., placeOrder, marketOrder, swap.execute, redeemPositions, deleteOrder, transfer, or signMessage)
  2. Circuit creates a suggestion visible to the user in the UI
  3. The user approves or ignores the suggestion
  4. If approved, Circuit executes the transaction
  5. 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.executionMode == "manual":
    agent.log("Suggesting a swap — please approve in the Circuit UI")

​
Which Modes to Use

ScenarioRecommended 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.

​
See Also