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
The first entry in the array is used as the default mode when testing locally with circuit run.

​
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
const result = await agent.signAndSend({
  network: "ethereum:1",
  request: {
    toAddress: "0x...",
    data: "0x",
    value: "100000000000000",
  }
});

// In auto mode: result.data.txHash is the transaction hash
// In manual mode: result.data.suggested = true, result.data.suggestionId = 123

​
Suggestion Lifecycle

In manual mode:
  1. Your agent calls a transactional method (e.g., signAndSend, placeOrder, marketOrder)
  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

All transactional 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") {
  // 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

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