Suggestions

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, suggestion-producing SDK calls (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 (string): Unique suggestion UUID

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 calling a supported suggestion-producing method.

Manual Clearing

Clear pending suggestions at any point during execution:

def clear_suggested_transactions() -> ClearSuggestionsResponse

async clearSuggestedTransactions(): Promise<ClearSuggestionsResponse>

Response:

success (boolean): Whether the pending suggestions were cleared
error (string | null): Error message if clearing failed

Example:

agent.clear_suggested_transactions()

await agent.clearSuggestedTransactions();

`expiresAt`

Suggestion-producing 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()

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",
    "expiresAt": expires
})

// Suggestion expires in 5 minutes
const fiveMinutes = new Date(Date.now() + 5 * 60 * 1000).toISOString();

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",
  expiresAt: fiveMinutes
});

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.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Automatic Clearing

Manual Clearing

`expiresAt`

Notes

See Also

​Automatic Clearing

​Manual Clearing

​expiresAt

​Notes

​See Also

Automatic Clearing

Manual Clearing

`expiresAt`

Notes

See Also