fund-agent-wallet

What this skill does

## Overview

For an overview of the Circle CLI's **full** capability set — bridging, smart contract execution, x402 payment, and more — see the `use-circle-cli` master skill. This skill is the narrower funding flow.

Funding an agent wallet means putting USDC where the CLI can spend it. There are **two balance pools** to be aware of:

- **On-chain (vanilla x402)** — USDC sitting at the wallet address on a specific chain. Each chain is separate. Used to pay endpoints whose `accepts[]` does not include `GatewayWalletBatched`. Settles in one block.
- **Nanopayments (powered by Gateway)** — USDC held off-chain in your Circle Gateway balance, batched and settled for you across supported chains. Per source chain — no cross-chain pooling at payment time. Used to pay endpoints whose `accepts[]` includes `GatewayWalletBatched`. Settles in <500ms once the balance exists.

### Gas note
**Agent wallet payment flows are gas-abstracted** — users can pay with USDC without pre-funding native gas. 

This skill covers funding both pools. Pick the path with the shortest time-to-result and hide chain complexity from the user.

## Prerequisites

```bash
# Confirm session is good
circle wallet status

# Get the wallet address
circle wallet list --chain BASE --type agent --output json

# Check current on-chain balance (per chain)
circle wallet balance --address <addr> --chain BASE --output json

# Check current Gateway balance (per chain)
circle gateway balance --address <addr> --chain BASE --output json
```

If `circle wallet status` errors with "Not logged in" or "Terms acceptance is required", hand off to the `use-agent-wallet` skill — it covers install, terms, login, and wallet creation.

## Step 1 — Pick a funding path

Ask the user: *"How would you like to fund your wallet?"*

- **Fiat (USD or local currency)** — Buy USDC with a card or bank transfer via the CLI's built-in fiat on-ramp. Best for users who don't have crypto yet.
- **Existing USDC** — Send USDC from a wallet they already have (MetaMask, Coinbase, Phantom, etc.). Faster and free of on-ramp fees.
- **Gateway deposit (advanced)** — Move existing on-chain USDC into the Gateway balance for low-latency batched payments. Only useful if the seller they're paying supports Gateway on a specific chain.

**Default recommendation: existing USDC → BASE.** Fastest, lowest friction, and BASE is the most commonly accepted chain across the marketplace.

## Step 2 — Required flags for non-interactive use

The CLI prompts for missing values when run interactively. **Agents are non-interactive**, so every `circle wallet fund` invocation against mainnet MUST include:

- `--address <addr>` — wallet address from `circle wallet list`
- `--chain <chain>` — e.g. `BASE`
- `--method <fiat|crypto>` — without it: `Error: --method is required in non-interactive mode.`
- `--amount <number>` — USDC amount; without it: `Error: --amount is required.`

`--token usdc` is the default and can be omitted, but pass it explicitly when the user asked for USDC specifically.

## Path A — Fiat on-ramp

Opens a fiat on-ramp window in the user's default browser. Funds deposit directly to the wallet on the selected chain.

```bash
circle wallet fund --address <addr> --chain BASE --amount 25 --token usdc --method fiat --open
```

The user completes purchase in the on-ramp window. USDC arrives in the wallet on the selected chain after on-ramp settlement (typically minutes for card, longer for bank transfer).

Verify after the user reports purchase complete:

```bash
circle wallet balance --address <addr> --chain BASE --output json
```

## Path B — Crypto transfer (existing USDC)

The user already holds USDC somewhere (another wallet, an exchange, etc.) and wants to send it to the agent wallet.

### Recommended — browser-rendered QR (best UX)

```bash
circle wallet fund --address <addr> --chain BASE --amount 10 --token usdc --method crypto --open
```

`--open` renders the EIP-681 QR code on a local HTML page in the user's default browser. Use this by default. **Terminal-rendered QR codes are frequently truncated or unscannable** inside agent UIs (Claude Code, Codex, etc.); the browser page renders the QR at full resolution and works on both desktop and mobile.

The user scans the QR with any mobile wallet (MetaMask, Coinbase Wallet, Rainbow, Phantom) and confirms the transfer.

### Alternative — save the QR as a PNG file

```bash
circle wallet fund --address <addr> --chain BASE --amount 10 --token usdc --method crypto --export ~/Downloads
```

### Alternative — manual transfer (no QR)

Provide the user the raw transfer details:

- Destination: the wallet address from `circle wallet list`
- Token: USDC
- Network: BASE (chain ID 8453)
- USDC contract on BASE: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`

For other chains, look up the USDC contract address at https://developers.circle.com/stablecoins/usdc-contract-addresses.

### Verify after transfer

```bash
circle wallet balance --address <addr> --chain BASE --output json
```

## Path C — Gateway deposit (powered by Gateway, advanced)

Only suggest a Gateway deposit when:

- The user has on-chain USDC, AND
- They want to pay a service whose `accepts[]` includes `GatewayWalletBatched` on a specific chain, AND
- That chain is one Gateway supports (Polygon, BASE, ETH, ARB, OP, AVAX, UNI).

### Eco vs direct — pick eco unless one of four conditions holds

`circle gateway deposit --method eco` deposits BASE vanilla USDC into Gateway and **lands on Polygon** (Gateway domain 7) in ~30-50s for a $0.03 flat fee. The follow-up payment is `pay --chain MATIC`.

Use `--method direct` **only** when:

1. **The user explicitly asked for direct** — e.g. "deposit on BASE without going to Polygon", "stay on BASE", "use direct deposit". Implicit preferences and your own inferences do not count.
2. **The source chain isn't supported by eco** — eco only supports BASE as a source today; check `circle gateway deposit --help` for the current list. Trying an unsupported source returns "Unknown method" or chain-not-supported.
3. **The seller does NOT accept Gateway on Polygon** — verify by reading the seller's raw 402 `accepts[]` (not `circle services inspect`). Eco lands on Polygon, so if the seller can't pay there, the Gateway balance won't be reachable for this payment.
4. **The user already has vanilla on a fast chain the seller accepts** — `direct --chain <fast-chain>` is ~8s and skips the eco fee. (e.g., user has 5 USDC vanilla on Polygon → `direct --chain MATIC`.)

If none of conditions 1–4 holds, **the answer is eco**. Picking direct anyway costs the user 13–19 minutes of finality wait + gas vs eco's ~30-50s + $0.03.

### Compare per-workflow, not per-call

The cold-start cost of eco (~30-50s deposit + $0.03 fee) is paid **once**. After that, every Gateway-supported call is <500ms. Vanilla x402 has no deposit, but every call costs ~2s plus facilitator overhead, forever, with no amortization. Agentic workflows are almost never single-call. For any multi-call task, treat the deposit as wallet onboarding, not as a per-call optimization. Pure time breakeven lands at roughly N=7-13 calls (vanilla `30 + 2N` vs eco `30-50 + 0.5N` across the realistic timing range), but the immediate wins land at call 1: Gateway-only seller access, wallet onboarding for every future call (each <500ms), and amortizing a single $0.03 fee.

### Eco deposit (BASE → Polygon)

```bash
# Deposit (--amount, --address, --chain, --method are all required)
circle gateway deposit --amount 10 --address <addr> --chain BASE --method eco

# Verify (Gateway balance shows Polygon in the per-chain breakdown)
circle gateway balance --address <addr> --chain BASE --output json

# If the wallet hasn't been used on the destination chain yet, the first
# payment / transfer on that chain will deploy it. There is no dedicated
# "deploy" command — consult `circle wallet --help` for current options.
```

Once the deposit verifies, hand off to the `pay-via-agent-wallet` ski