> ## Documentation Index
> Fetch the complete documentation index at: https://jephalabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Wallet Top-Up
> Fund approved Circle Agent Wallets from QTG-controlled USDC without exposing the treasury signer
> **Status (2026-05-26):** Implementation and Base Sepolia tiny-live evidence are
> merged into `main`. Public top-up route remains operator-gated and disabled by
> default (`MG_AGENT_WALLET_TOPUP_ENABLED=false`). This page describes the
> product boundary and operator model — not a license to enable the lane in
> production.
## What this lane is
Agent Wallet Top-Up gives a user-owned coding or research agent (Claude Code,
Cursor, Codex, autopilot CI, …) **bounded USDC purchasing power** without
giving that agent access to the QTG treasury signer.
```text theme={null}
QTG treasury signer ──▶ approved Circle Agent Wallet ──▶ Circle Gateway / x402 spend
controlled by QTG bounded hot wallet agent or user session
```
QTG only controls the funding step. After top-up finality, the Agent Wallet is a
bounded hot wallet — Circle Gateway deposit and x402 payment are the agent or
user session's responsibility.
## What this lane is *not*
* **Not an x402 HTTP proxy.** QTG does not relay paid HTTP requests.
* **Not a Circle Agent Wallet session controller.** QTG does not own the
destination wallet's session key.
* **Not a recovery or sweep feature.** Once funds reach the Agent Wallet, QTG
cannot guarantee or reverse the agent's spending.
* **Not a treasury-key delegation.** No credential available to the agent,
Agent Wallet session, or x402 spend flow can move funds from the QTG
treasury.
## Security invariant
> No credential available to the user agent, Circle Agent Wallet session, or
> x402 spend flow can move funds from the QTG treasury.
QTG enforces this by:
* Keeping the treasury signer **server-owned** (default: AWS KMS in your account).
* Resolving the source address / token / signer selector from a registered
**funding envelope** — the agent never names them.
* Enforcing **destination allowlists** at dispatch time.
* Recording **movement, ledger, and audit evidence** for every top-up.
* Bounding exposure with **caps, cooldowns, and rolling windows** — safety
comes from small balances and manual review above policy, not from claims of
reversibility.
## Operator model
The intended operating path is:
Operator seeds an active funding envelope for one approved Agent Wallet.
The envelope names: destination wallet address, provider, chain, asset,
source address, token address, treasury signer selector, caps, cooldown,
purposes, and non-secret metadata (e.g. optional display email).
The compile path enforces same-authority / USDC envelope compatibility,
cap and cooldown rules, and address allowlist membership.
A normal movement graph is built for a USDC ERC-20 transfer from the
treasury source to the Agent Wallet destination.
The dispatcher signs through the QTG treasury signer and observes
finality. Ledger rows progress through `reserved → submitted → completed`
(or release on failure).
The agent's session uses the funded wallet for Circle Gateway deposit and
x402 spend. QTG has no further role until the next top-up.
## Current evidence
The lane reached **Base Sepolia Stage 3 tiny live validation**:
| Field | Value |
| --------------------------- | ---------------------------------------------------------------- |
| Destination Agent Wallet | `` |
| Source KMS EVM address | `` |
| Amount | `0.01` USDC (`10000` raw) |
| Movement ID | `` |
| Transaction | `` |
| Result | Receipt `status=0x1`, movement `COMPLETED`, reservation consumed |
| Out of scope for this proof | No Circle Gateway deposit, no x402 seller call, no mainnet spend |
The dashboard surfaces the metadata projection for approved Agent Wallet top-up
envelopes, including optional display-only email metadata for operator
convenience. **That email is not an auth factor, signer input, recovery
authority, or payment control.**
## Operator readiness ladder
Stage 1 / 2 / 3 are evidence gates — each one has a tool-owned validator and
none of them is sufficient on its own to enable public/agent-facing top-up.
Markdown packet templates alone are not evidence; only filled packets that pass
`qtg agent-wallet topup validate-packet --stage stage{1,2,3,3-post}` count.
| CLI | Purpose | Live side effects |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `qtg agent-wallet topup env-probe` | Stage 0/1 no-live readiness check — redacted `SET`/`UNSET` output, refuses default DB / mainnet chain id under `testnet` mode | None |
| `qtg agent-wallet topup init-packet` | Scaffold a target-specific filled packet copy | None — refuses to overwrite existing files |
| `qtg agent-wallet topup preflight` | Read-only Stage 1 preflight for one authority / wallet / chain / amount — resolves balances and cap snapshot, and emits the packet fields for the Stage 1 evidence section | None — reads only |
| `qtg agent-wallet topup seed-stage1` | Operator-only seed path — dry-run by default, `--apply` to persist | Stage 1 DB writes only on `--apply` |
| `qtg agent-wallet topup drill-stage2` | No-live drill against an existing executor registry row | Process-local fake metadata only — no RPC / sign / broadcast |
| `qtg agent-wallet topup live-stage3` | Reviewed Stage 3 harness — requires filled packet + `--i-understand-this-can-sign-and-broadcast` | **Can sign and broadcast** |
| `qtg agent-wallet topup validate-packet` | Markdown packet validator (`stage1` / `stage2` / `stage3` / `stage3-post`) | None |
Stage 3 hardening invariants the harness must keep enforcing: public top-up
flag false, zero deployment-global active agent HMAC keys, KMS-only signer
runtime with raw private-key env unset, live-time active-envelope template
compatibility re-check, packet-approved signer/source/token equality, Stage 1
RPC balance timeout, terminal non-success movement immediate exit, JSON
`unexpected_error` report, and no retry without reviewed recovery after
ambiguous signed/broadcast evidence.
## Production enablement gate
Public/agent-facing enablement must remain behind a feature flag **and**
separate operator approval. Small testnet harness approval is not
production/public-route approval.
When this moves into broader user-facing docs, these claims stay intact:
* QTG **funds** approved Agent Wallets; it does not proxy paid HTTP requests.
* QTG **never gives** the agent treasury signing authority.
* QTG **cannot guarantee or reverse** every spend after funds reach the Agent
Wallet.
* Optional Agent Wallet email metadata is display/operations metadata **only**.
* Live readiness distinguishes no-live tests, Stage 1 environment evidence,
Stage 3 tiny testnet proof, and production enablement — they are not
interchangeable.