agent-wallet

# ChainGPT Agent Wallet Skill

The agent has its own EOA wallet on every EVM chain it supports. The admin (you, in your shell) sets policies that the agent cannot violate or revoke — even if a malicious prompt convinces the LLM to try.

## Threat model

**The attacker's goal:** prompt-inject the agent to drain its wallet to an attacker address.

**The plugin's defense:** the policy check is in **code, not in the LLM's prompt**. Every `chaingpt_agent_wallet_sign_and_send` call:

1. Loads the policy file fresh from disk (no caching — admin can update mid-session).
2. Runs `checkPolicy(intent)` — pure deterministic code that doesn't see the LLM's context.
3. Refuses if any rule fails, with a clear reason the agent surfaces back to the user.

The attacker can convince the LLM to call `sign_and_send(to=attacker, value=ALL)` — but the tool layer refuses because `attacker` isn't in `allowedToAddresses` or `value` exceeds `maxTxValueWei` or `killSwitch=true`. **The trust boundary is the tool code, not the LLM.**

There is no MCP tool that writes the policy file. The admin edits it directly with a text editor. There is no MCP tool that reads or sets the passphrase. The passphrase lives only in the shell env var **or** the OS keychain — never in the keystore file, never in the LLM's context.

## Setup (admin steps — done once)

The keystore passphrase resolves in this priority order:

1. **`CHAINGPT_AGENT_WALLET_PASSPHRASE` env var** — explicit override. Best for CI / headless / power users who want zero process-list and zero keychain exposure.
2. **OS keychain** — auto-managed. On macOS (Keychain via `security`) or Linux (libsecret via `secret-tool`), if no env var is set, `chaingpt_agent_wallet_init` **generates a strong 256-bit passphrase and stores it in the keychain**. You never type or remember it; the MCP server reads it back on each load.

### Option A — zero-setup (macOS / Linux with a keychain) — recommended for most

```bash
# Just init — a strong passphrase is generated + stored in your OS keychain.
claude
> initialize the agent wallet
```

The init output tells you it used the keychain and how to export the passphrase for backup.

### Option B — explicit env var (CI / headless / max control)

```bash
# Set a strong passphrase BEFORE starting the MCP server (>= 16 chars)
export CHAINGPT_AGENT_WALLET_PASSPHRASE="your-strong-passphrase-here-min-16-chars"
claude
> initialize the agent wallet
```

> **Back up the passphrase either way.** Keychain entry: `service=chaingpt-mcp-agent-wallet account=keystore-passphrase`. Export on macOS with `security find-generic-password -s chaingpt-mcp-agent-wallet -a keystore-passphrase -w`. Lose it (and any backup) → the keystore is unrecoverable. There is no recovery path.

> **Security tradeoff of the keychain option:** the secret stays out of plaintext-on-disk and out of the LLM context, but the keychain is unlocked while you're logged in — a local attacker on an unlocked session could read it. That's a much higher bar than a plaintext file and appropriate for a low-value bounded hot wallet. For zero local exposure, use Option B.

This creates two files:

| File | Contents | Who edits it |
|---|---|---|
| `~/.chaingpt-mcp/agent-wallet/keystore.json` | AES-256-GCM encrypted private key | Generated once by the init tool. Never edit by hand. Back it up. |
| `~/.chaingpt-mcp/agent-wallet/policy.json` | Plain JSON rules | **You, the admin, with a text editor.** The agent has NO tool that writes this file. |

Both default to `~/.chaingpt-mcp/agent-wallet/` but can be overridden via `CHAINGPT_KEYSTORE_FILE` and `CHAINGPT_AGENT_POLICY_FILE`.

## Tools

| Tool | Mutates state? | Notes |
|---|---|---|
| `chaingpt_agent_wallet_init` | Creates keystore | One-shot. Refuses if file exists. |
| `chaingpt_agent_wallet_address` | No | Returns the agent's EOA address. Use this to receive funds. |
| `chaingpt_agent_wallet_status` | No | Address + policy digest + kill-switch state. **Run this before any signing.** |
| `chaingpt_agent_wallet_balances` | No | Native-coin balances across requested chains. |
| `chaingpt_agent_wallet_policy` | No (read-only) | Shows the current policy JSON. Cannot modify it. |
| `chaingpt_agent_wallet_sign_and_send` | **Signs + broadcasts a tx** | The only tool that can move funds. Gated by policy. |
| `chaingpt_agent_wallet_serve_ui` | Starts a local HTTP server | Dashboard on `http://127.0.0.1:8787`. Read-only view. |

## Policy file format

Default `policy.json` (lazily created on first read) is the **Balanced DeFi** policy: `killSwitch: false`, major DEX/lending routers allow-listed, 0.1 native per-tx cap, 0.3 native + 20 txs per rolling 24h (`maxDailySpendWei` / `maxDailyTxCount`), memo required. A corrupt or partially-missing policy file always falls back to fail-closed (`killSwitch: true`) — tampering can never open the gates. Apply the "Locked down" template (or set `killSwitch: true`) for a refuse-everything posture.

Example **production policy** (allow DEX rebalancing on Base, capped at 0.1 ETH/tx, audit memo required):

```json
{
  "version": 1,
  "killSwitch": false,
  "allowedChains": [8453],
  "allowedToAddresses": [
    "0x6352a56caadc4f1e25cd6c75970fa768a3304e64",
    "0x111111125421ca6dc452d289314280a0f8842a65"
  ],
  "blockedToAddresses": [
    "0x0000000000000000000000000000000000000000"
  ],
  "maxTxValueWei": "100000000000000000",
  "maxTxGas": "500000",
  "blockedSelectors": [],
  "requireMemo": true,
  "notes": "Base only, OpenOcean + 1inch routers only, 0.1 ETH cap, memo required for audit",
  "updatedAt": "2026-05-18T20:00:00Z"
}
```

### Field reference

| Field | Type | Behavior when unset | Behavior when set |
|---|---|---|---|
| `killSwitch` | bool | refuses everything (fail-closed) | `true` refuses everything; `false` proceeds to other checks |
| `allowedChains` | int[] | any chain allowed | refuses if `chainId` not in list |
| `allowedToAddresses` | string[] | any address allowed | refuses if `to` not in list (