Confirmation Queue

By default, web3agent does not execute financial transactions immediately. When an AI agent calls a tool that moves funds, the operation is placed in a confirmation queue and paused. A human (or an automated system) must explicitly confirm it before execution proceeds.

This is controlled by the CONFIRM_WRITES environment variable, which defaults to true.

---

Why Confirmation Exists

AI agents make mistakes. They misread context, hallucinate token addresses, or misinterpret amounts. For read operations like balance checks or price quotes, a mistake is harmless. For write operations like swaps, transfers, or order placements, a mistake can be costly and irreversible.

The confirmation queue puts a human checkpoint between the AI's decision and the actual on-chain execution. The AI prepares the operation and describes what it's about to do. A human reviews it and either approves or rejects it.

---

Which Operations Require Confirmation

Confirmation applies to tools with riskLevel: "financial" or riskLevel: "destructive". Safe reads are never queued.

Risk Level	Examples	Confirmation Required?
safe	orbs_get_quote, blockscout_get_address, list_supported_chains	No
financial	orbs_swap, evm_transfer, lifi_execute_bridge	Yes (when CONFIRM_WRITES=true)
destructive	Contract deployments, large approvals	Yes (when CONFIRM_WRITES=true)

---

The Confirmation Flow

Step by Step

1. AI calls a write tool. The agent invokes something like orbs_swap with the swap parameters.
2. Runtime validates and queues. Arguments are validated against the Zod schema. If valid, the operation is placed in the queue with a unique pendingId and a TTL timestamp.
3. Runtime returns immediately. The tool call returns { ok: true, data: { pendingId, description, expiresAt } }. The operation has not executed yet.
4. Agent surfaces the pending operation. The AI agent tells the user what's waiting for confirmation, including the operation details and the pendingId.
5. Human confirms. The user (or an automated approver) calls transaction_confirm with the pendingId.
6. Runtime executes. The queued operation runs. The result (including txHash for on-chain operations) is returned.

---

Confirming an Operation

The transaction_confirm tool takes a pendingId and executes the queued operation:

// Via MCP (AI agent calls this after human approval)
tools/call {
  name: "transaction_confirm",
  arguments: { id: "conf_abc123" }
}

// Response on success
{
  ok: true,
  data: {
    txHash: "0x...",
    status: "confirmed",
    // ... operation-specific result fields
  }
}

To reject an operation without executing it:

tools/call {
  name: "transaction_reject",
  arguments: { id: "conf_abc123" }
}

---

TTL and Expiry

Pending confirmations don't wait forever. Each queued operation has a TTL (time-to-live). If the TTL expires before confirmation arrives, the operation is automatically removed from the queue and cannot be executed.

This prevents stale operations from being confirmed long after the market conditions that prompted them have changed. A swap quote that was valid 10 minutes ago may no longer be valid now.

If a pending operation expires, the AI agent will need to re-prepare it. The original pendingId is no longer valid after expiry.

---

Disabling Confirmation for Autonomous Agents

For autonomous agents that don't have a human in the loop, set CONFIRM_WRITES=false. This bypasses the confirmation queue entirely. Write operations execute immediately when called.

CONFIRM_WRITES=false npx web3agent

Or in code when creating a runtime:

import { createRuntime } from "web3agent/runtime";

const runtime = await createRuntime({
  env: {
    CONFIRM_WRITES: "false",
    // ... other config
  }
});

Only disable confirmation for agents where autonomous execution is intentional and other safeguards (like the policy engine) are in place. An autonomous agent with CONFIRM_WRITES=false and no policy limits can execute unlimited financial transactions without any human oversight.

---

Combining Confirmation with Policy

The confirmation queue and the policy engine are independent layers. Both can be active at the same time.

When CONFIRM_WRITES=true and POLICY_ENABLED=true:

1. The policy engine evaluates the operation's USD value against configured limits.
2. If the policy rejects it, the operation never reaches the queue.
3. If the policy allows it, the operation is queued for human confirmation.
4. Human confirmation triggers execution.

This gives you two checkpoints: an automated policy check and a human approval step.

---

Audit Logging

Every write operation, whether confirmed, rejected, or expired, is recorded in the audit log at ~/.web3agent/audit.log. The log includes the operation type, arguments, outcome, and timestamp.

{
  "timestamp": "2026-04-30T10:23:45.000Z",
  "type": "orbs_swap",
  "pendingId": "conf_abc123",
  "status": "confirmed",
  "args": {
    "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toToken": "0x4200000000000000000000000000000000000006",
    "fromAmount": "100000000",
    "chainId": 8453
  },
  "result": {
    "txHash": "0x..."
  }
}

The audit log is append-only and never modified after writing. It's the source of truth for what actually executed.

---

Configuration Reference

Variable	Default	Description
CONFIRM_WRITES	true	Require confirmation for financial and destructive operations

Set to false for autonomous agents. Leave at true (or omit entirely) for interactive use with a human in the loop.