# Web wallet and USDC delegation

The web console is configured for **https://wallet.evidence.contact**. It manages an **owner-controlled signer on your computer**. The public website serves static files; it does not store wallet keys, run a hosted wallet account or receive custody of USDC. The signer implementation is available in this repository; the hosted console serves only browser assets.

Only native **USDC on Base mainnet** is supported: chain `8453`, token `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, six decimals. This implementation adapts the owner-pairing and wallet/delegation/activity layout of the Agent Dollar reference wallet. Its test tokens, minting, treasury, liquidity and campaign features are not imported.

You can connect an **existing browser-wallet account** to view its Base USDC and deposit into the paired agent wallet. The browser wallet keeps that account's key. The agent receives spending permission only over the separate owner-controlled signer wallet; connecting a browser wallet creates no allowance or delegation over the browser wallet account.

```text
wallet.evidence.contact                 OWNER COMPUTER
  static browser console                 local signer + private journal
           |                                      |
           +-- one-use pairing ------------------>|
           +-- create / inspect / delegate ------>|
           |                                      |
           |<-- scoped agent credential ----------+
                                                  |
AGENT -- credential + task --> LOCAL TASK API ------+
                                                  |
                                policy check -> Base USDC payment
                                                  |
                                             SELLER WALLET
```

## 1. Start the owner signer

Use Node.js 24+ on Linux or macOS, with the repository dependencies installed using `npm ci`.

```sh
npm run runtime -- wallet web \
  --dir "$HOME/.local/share/402mob/runtime-owner"
```

The process starts two **loopback-only** interfaces:

| Interface | Default address | Credential |
| --- | --- | --- |
| Owner management | `http://127.0.0.1:4032` | One-hour browser session obtained by pairing |
| Agent tasks | `http://127.0.0.1:4031` | Scoped agent credential |

The command prints two private pairing links: the public console and a local fallback. Open **one** on the computer running the signer and click **Connect signer**. The code expires after five minutes and can be used once. Press Enter in the signer terminal for a new link. Reloading the page or restarting the signer requires pairing again; it does not delete the wallet or its agent grants.

The pairing code is in the URL fragment, which the browser removes before making requests. Owner sessions stay in page memory. Do not share a pairing link or copy it into public logs. Disconnect ends that owner session, not the agents’ spending permissions.

The website may need your browser's permission to access localhost. If the connection is blocked, open the **local console link printed by the signer**; it serves the same interface without a cross-origin connection. This follows the browser's [Local Network Access rules](https://developer.chrome.com/docs/modern-web-guidance/guides/security/local-network-access). Do not disable browser protections.

For a signer on another owner-controlled host, keep both ports private and forward them to the browser's machine through an authenticated SSH tunnel. Preserve the advertised ports or pass matching `--port` and `--web-port` values when starting the signer. Run the agent on that host or through its own authenticated private transport. The website is not a remote signer relay.

## 2. Create and fund the wallet

In **01 / Agent wallet**, click **Create wallet**, optionally entering a shared spending ceiling. By default there is no extra wallet ceiling; each delegation still requires its own total USDC allocation. The local signer generates the EOA and stores it in the private runtime directory. An existing runtime wallet opens with its existing identity, ceiling, grants and journals; the console cannot silently replace it.

Copy its receiving address and deposit native USDC on Base from a wallet you control, or use the browser wallet flow below. Creation and enrollment do not fund it. The balance is a read-only chain observation, separate from:

- **Reserved:** unresolved signed or reserved payments.
- **Spent:** payments confirmed by the runtime.
- **Remaining ceiling:** the lifetime ceiling minus reserved and spent amounts.

A deposit increases the balance, not a configured ceiling or delegation allocation. Use **Change shared ceiling** to set, raise or remove the extra wallet ceiling; it cannot fall below spent and reserved amounts. Use **Increase allocation** on an active agent to increase its lifetime allocation while preserving its credential and other restrictions. The console never labels an unavailable RPC balance as zero or displays an old balance as fresh. It has no generic send, withdrawal or token-swap action. The runtime signs x402 authorizations; the facilitator submits settlement, so its normal buyer flow does not require this wallet to submit a gas-paying transaction.

### Connect a browser wallet and deposit

1. Enable an Ethereum wallet extension. In **02 / Add USDC**, select an extension in the wallet list, click **Connect wallet**, then choose an account in that extension. Connecting requests account access only and works before pairing the signer.
2. Click **Switch to Base** if needed and approve the network change in your browser wallet. The console reads the connected account's native Base USDC and ETH balances. Account or network changes clear the displayed balances and any unsubmitted deposit review.
3. Pair your owner signer and create or open its agent wallet. The deposit recipient is this wallet's address; it cannot be replaced with an arbitrary address in the form.
4. Enter a positive USDC amount with at most six decimals, then click **Review deposit**. Check the sender, agent receiving address, Base network and USDC contract. Click **Confirm in your wallet** and review the transaction and gas there. The sending account needs Base ETH for gas; a nonzero ETH balance is not a guarantee that it covers the estimate.
5. Keep the funding record and click **Check same transaction**. The console checks the recorded nonce, submission block boundary, transaction terms and exact USDC Transfer log, then waits for three Base block confirmations. A submitted hash is not a confirmed deposit. Confirmed reverts also require three confirmations before another deposit is offered.
6. After confirmation, review the agent wallet's balance and create its spending delegation separately. Funding does not increase its lifetime ceiling, enroll it as a merchant or pay a seller.

```text
EXISTING BROWSER WALLET                  OWNER SIGNER WALLET
  owner approves one USDC transfer ------> receives Base USDC
  extension retains this key              local signer retains this key
                                                     |
                                 scoped credential --+--> AGENT
                                                     |
                                 bounded purchase ---+--> SELLER
```

The console discovers compatible Ethereum extensions through EIP-6963 and also lists EIP-1193 providers exposed through legacy `window.ethereum` injection. MetaMask is one option; there is no brand allowlist. Names are supplied by extensions and displayed as text, not treated as verified identities; wallet icons are not loaded. Choose the provider you intend to use. Discovery and rescanning never request accounts or automatically switch a connected provider. If it is not detected, enable the extension for this browser and click **Scan again**. Mobile QR pairing and direct delegation from a browser wallet account are not implemented. Disconnecting a browser wallet from this page removes the active connection; saved site permissions are managed in your browser wallet.

The extension must support Base and standard `eth_sendTransaction` calls that honor an explicit sender nonce and return a transaction hash. Funding uses native Base USDC and ordinary transaction/receipt RPC reads. Wallets that expose only smart-account user operations, batched calls or mobile QR sessions are outside this adapter. If programmatic network switching is unsupported, select Base in the extension and click **Refresh wallet balance**.

### Recover an interrupted deposit

Before requesting a transfer, the console saves a non-secret funding record in this tab's `sessionStorage`: sender, recipient, amount, network, token, nonce, starting block and, when returned, transaction hash. The request to the browser wallet includes that nonce; recovery rejects a different nonce or a transaction mined at or before the starting block. It contains no wallet keys or owner/agent credentials. Funding is blocked if that record cannot be saved. It survives a reload in the same tab, but is not a durable or cross-tab journal; closing the tab or clearing browser data can remove it. Keep the transaction hash and leave the tab open while a transfer is unresolved. Re-pair the owner signer after reloading.

A rejected prompt (`4001`) or an unsupported send method (`4200`) clears this unsubmitted record. For an EIP-6963 provider identifying itself as MetaMask, its already-pending request error (`-32002`) is also treated as a pre-submission rejection. Unknown providers and legacy injection retain an unknown outcome for that nonstandard error code. Finish any existing request in your browser wallet before reviewing another deposit. Other wallet errors leave the outcome unknown and block another deposit. Inspect browser wallet activity, paste the actual transaction hash into the recovery field and use **Check same transaction**. Checking never sends a payment. If no hash can be established, keep the record and investigate the wallet activity instead of assuming the transaction failed.

If the wallet supports speeding up a transaction, paste its replacement hash even if the original hash is already displayed. Recovery requires the same sender, nonce and USDC transfer terms. A zero-value, empty-data transfer from that sender to itself at the same nonce is recognized as a cancellation. Deposits, reverts and cancellations all require three confirmations before **Start another deposit** clears the record. An older identical transfer does not resolve a new deposit.

Version 1 funding records lack nonce and block binding. The console can check their original saved hash, but cannot safely attach a missing or replacement hash. Preserve those records and inspect browser wallet activity; do not clear an unresolved record to send again.

Funding recovery is separate from the runtime's durable purchase journal. Owner and agent bearer tokens stay out of browser storage. Browser-wallet discovery uses [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963); network and token parameters follow [Base](https://docs.base.org/get-started/connect-to-base) and [Circle's USDC addresses](https://developers.circle.com/stablecoins/usdc-contract-addresses).

## 3. Delegate spending to an agent

In **03 / Set agent spending permissions**, enter an agent name and its total USDC allocation. By default the agent chooses the seller for each task, may spend the remaining allocation in one payment and has no delegation expiry.

Open **Optional spending restrictions** to fix a merchant, payout address, service, per-payment ceiling or expiry. Each restriction is independent; leave unused fields blank. **Inspect seller** fills the merchant and payout restrictions using the configured 402Mob service. It does not certify availability or service quality. Existing delegations keep their original restrictions. Revocation, the allocation and the shared wallet ceiling still apply.

The runtime supports `text-statistics-v1` direct Work Tickets and `prepared-artifact-v1` prepared JSON/text purchases, including pinned Payment Links. Protected escrow and other execution handlers remain separate workflows.

Click **Review delegation**, inspect the exact terms, then **Authorize and download credential**. This creates spending permission; it does **not** transfer or escrow funds for the agent. Limits use exact six-decimal USDC amounts. Each grant has an allocation, and all grants share any configured wallet ceiling and the actual funds. Creating several grants does not multiply that ceiling or reserve their full limits.

The downloaded JSON contains the delegation ID, scoped bearer token, wallet address, policy and agent gateway. Store it in the agent's secret manager or restrict its local file permissions:

```sh
chmod 600 /absolute/private/agent-credential.json
```

Keep the **wallet directory inaccessible to the agent**, using separate OS users or containers and a private route to its task API. The limits are enforced by owner software over an EOA. They are not restrictions in the USDC contract or an on-chain session-key wallet. Private wallet files are unencrypted; the filesystem owner remains trusted.

## 4. Give the agent work

Run the seller separately as described in the [runtime guide](/agent-runtime.md#1-start-the-seller). The download shows a ready-to-copy `buyer check` command with its credential filename. Move the file into private agent storage, run that check, then `buyer workers` or `buyer resources` to discover candidates. The check reports effective capacity and observed funds without signing. For fresh text work, use:

```sh
npm run runtime -- buyer prepare \
  --text-file input.txt --merchant-id SELLER_MERCHANT_UUID --max-usdc 0.02 \
  --out .local/buyer-request.json

npm run runtime -- buyer run \
  --file .local/buyer-request.json \
  --credential /absolute/private/agent-credential.json
```

Supply the chosen merchant UUID with `--merchant-id`; it may be omitted only when the delegation fixes a merchant. Each saved task retains its seller on retry. The buyer CLI reads the gateway from the downloaded credential, including a custom signer `--port`. An explicit buyer `--gateway` overrides it; older CLI credentials without a gateway default to `http://127.0.0.1:4031`. Automatic credential destinations must be HTTP loopback addresses. A remote private transport requires an explicit override.

The owner signer must stay running. The agent can submit tasks, read its own budget and recover its existing jobs. Its token cannot create wallets, grant permissions, revoke another agent or use owner APIs. Owner browser sessions cannot call the agent task API.

## 5. Inspect, revoke and recover

For prepared artifacts and Payment Links, follow [the purchase commands](/agent-runtime.md#buy-a-prepared-artifact-or-payment-link).

The console shows each delegation's policy, spent/reserved amounts, expiry and revocation status, plus the latest 50 jobs in this wallet's runtime journal. It does not represent a complete on-chain transaction history. It omits raw task inputs, result bytes and signed payment payloads from the activity response.

**Revoke spending** prevents new payment authorizations. It cannot cancel one already signed; that authorization may still settle, and recovery of its result remains available. Revoked and expired agent credentials retain read access to their own existing jobs.

The browser assigns a request ID before granting permission. If a grant response is lost, **Recover same credential** reuses that ID and the exact policy. It cannot create a second delegation or silently change its limits. **Download credential** retrieves the same token with its current policy after an owner allocation update. A definitive rejection, such as expiry before confirmation or invalid limits, returns to editable fields. A timeout, unreadable response or server error keeps the original request for recovery.

A paired owner can also download the same non-revoked web-created credential from the delegation list. For an expired grant, **Download recovery credential** preserves its expiry and allows access only to existing jobs; it cannot authorize new spending. CLI-created random credentials cannot be recovered this way. Revoked grants report `credentialRecoverable: false` and cannot be downloaded or reactivated through replay.

The signer stores only the credential hash in the delegation table. Web-issued credentials can be re-derived by the trusted owner signer using a domain-separated keyed derivation over their request ID. The private key never leaves it. Browser reload does not revoke an issued credential: inspect existing grants before creating replacements.

After correcting a stopped job's cause, **Retry same job** uses the runtime's existing bounded owner-retry operation. It preserves accepted terms, the payment nonce and reservations. Do not reset or copy a wallet ledger to clear uncertain spending. Retain the complete directory and recovery records. The console currently refuses wallets configured with optional model admission rather than silently disabling their configured admission policy.

## Domain and deployment configuration

`deploy/Caddyfile` includes a separate `wallet.evidence.contact` site. It serves only the six browser assets (`index.html`, `app.js`, `browser-wallet.js`, the compatibility module `metamask.js`, `style.css`, `favicon.svg`) through `/wallet/` on the existing app. It does not expose owner `/api/*` or agent `/v1/*` endpoints on the subdomain.

Before deployment, point the subdomain at the web server, enable HTTPS with Caddy and include the updated `public/wallet/` assets and app build. Restart a local signer after updating its source so it serves the new module route. The deployment script runs `deploy/refresh-web.sh` to validate the selected Caddy configuration in a fresh container, then recreates Caddy so replaced bind-mounted files are loaded. It preserves enabled protected-work and inspection listeners. `deploy/check-wallet-release.mjs` verifies all five HTTPS assets against the release files and checks that owner and agent APIs return 404 on the public subdomain; failed checks stop deployment from reporting success.

The signer defaults to accepting browser management calls from exactly `https://wallet.evidence.contact` and its own local console origin. Agent-facing origin restrictions remain unchanged. Owner POST calls require `Origin`, `X-402Mob-Wallet: 1` and JSON; these headers are defined in the owner OpenAPI parameters. Browsers set `Origin` themselves. Authenticated requests use the same origin as pairing.

For development with the main app on port 4020:

```sh
npm run runtime -- wallet web \
  --dir "$HOME/.local/share/402mob/runtime-owner" \
  --web-origin http://localhost:4020
```

Open `http://localhost:4020/wallet/` and use the printed pairing code, or use the signer's local console link. `--web-origin` takes an exact origin, not a path. Never expose either loopback service directly on a public interface.

## Contracts and validation

- [Wallet manifest](/web-wallet.json): host configuration, currency, custody, interfaces and supported controls.
- [Owner OpenAPI](/web-wallet.openapi.json): the loopback management API, not a public hosted API.
- [Agent OpenAPI](/agent-runtime.openapi.json): credential-scoped task/status calls.

Run `npm run test:runtime` and `npm run docs:runtime:check`. Tests use disposable wallets, mocked chain balances/settlement and simulated EIP-1193 providers from multiple wallet brands. They cover account changes, exact deposit encoding, recipient rechecks, duplicate confirmation, storage failures and same-transaction recovery. The previous [controlled live runtime exchange](/agent-runtime-live-validation.json) predates this browser console; it is evidence for the buyer/seller payment flow, not a live-money test of web-created delegation or browser-wallet deposits. No real funds are spent by the console tests; a real extension connection and deposit remain separately testable by the owner.

The [live delegation record](/wallet-delegation-live-validation.json) covers owner HTTP pairing, a minimal grant, allocation increase with the same credential and two real 0.01-USDC purchases. Browser extension deposit approval still requires a separate interactive check.

Deployment verifies wallet assets at `/wallet/` on the main site even before the dedicated hostname has DNS. It reports the missing DNS explicitly and checks the dedicated hostname once configured. Use the local console link printed by `wallet web` while waiting for DNS.
