Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

Use suggestions when your agent supports manual mode and you need to control how long a pending transaction stays available for user approval, or clear stale suggestions mid-execution. In manual mode, transactional SDK calls (signAndSend, swap.execute, placeOrder, marketOrder, etc.) create suggestions instead of executing immediately. The user approves each suggestion in the Circuit UI before it’s broadcast. The response in manual mode includes:
  • suggested (boolean): true
  • suggestionId (number): Unique suggestion identifier
For a general overview of modes, see Manual vs Auto Mode.

​
Automatic Clearing

All pending suggestions are automatically soft-deleted at the beginning of each run execution. If you need a shorter expiry, pass an expiresAt timestamp when submitting the transaction.

​
Manual Clearing

Clear pending suggestions at any point during execution: 
def clear_suggested_transactions() -> ClearSuggestionsResponse
Response:
  • success (boolean): Whether the pending suggestions were cleared
  • error (string | null): Error message if clearing failed
Example: 
agent.clear_suggested_transactions()

​
expiresAt

All transactional SDK methods accept an optional expiresAt parameter (ISO 8601 timestamp). If the user hasn’t approved by this time, the suggestion is discarded. 
from datetime import datetime, timedelta, timezone

# Suggestion expires in 5 minutes
expires = (datetime.now(timezone.utc) + timedelta(minutes=5)).isoformat()

result = agent.sign_and_send({
    "network": "ethereum:1",
    "request": {
        "to_address": agent.sessionWalletAddress,
        "data": "0x",
        "value": "100000000000000",  # 0.0001 ETH
    },
    "expiresAt": expires
})

​
Notes

  • expiresAt is available on: signAndSend / sign_and_send, swap.execute, placeOrder / place_order, transfer, and marketOrder / market_order.
  • In auto mode, expiresAt is ignored — transactions execute immediately.
  • Suggestions that expire before user approval are automatically discarded.

​
See Also

  • Manual vs Auto Mode — Overview of execution modes and when to use each
  • Swap — expiresAt works on swap.execute() too