# Agent Wallet MCP

[![tests](https://github.com/GitLoopDesign/agent-wallet/actions/workflows/tests.yml/badge.svg)](https://github.com/GitLoopDesign/agent-wallet/actions/workflows/tests.yml)

A **prepaid, capped payment method for an AI agent**, exposed over MCP. The agent
never touches your real bank accounts — it gets an isolated float and a server that
lets it *request* charges but never unilaterally move money.

Safety rests on five properties: **isolation, capping, revocability, out-of-band
confirmation, and auditability.**

> **▶️ Try it in your browser** (no signup, mock money): **https://agentwallet.loopdesign.com.au/demo**
> — make a mock agent request charges and watch the real policy engine auto-clear, hold for
> approval, or deny (including a prompt-injected "$5,000 to a scammer" that gets refused).
> Landing page: **https://agentwallet.loopdesign.com.au**

## The one rule that matters

The agent can only call `request_charge`, which creates a **pending intent**. The
**server** (policy engine) decides whether it clears. Charges at/above your threshold
wait for **you** to approve on a channel the agent cannot reach (`cli_approve.py` or
Telegram). A prompt-injected agent can *ask* to send $5,000 to a scammer; the server
just says no.

## Layers of protection

| Layer | Setting |
|---|---|
| Hard float ceiling (blast radius) | `WALLET_FLOAT_CENTS` (default $200) |
| Per-transaction cap | `WALLET_PER_TXN_CAP_CENTS` (default $50) |
| Rolling 24h spend cap | `WALLET_DAILY_CAP_CENTS` (default $100) |
| Rolling 1h transaction count | `WALLET_HOURLY_TXN_LIMIT` (default 5) |
| Auto-approve threshold | `WALLET_AUTO_APPROVE_UNDER_CENTS` (default 0 = confirm everything) |
| Merchant allow / deny lists | `WALLET_MERCHANT_ALLOWLIST` / `_DENYLIST` |
| Out-of-band approval | `cli_approve.py` (agent cannot call it) |
| Audit log | every request + capture in the `audit` table |

## How a charge flows

```mermaid
flowchart TD
    A["AI agent<br/>(can only request)"] -->|request_charge| P{Policy engine<br/>caps · velocity · merchant}
    P -->|over cap / denylist / no float| D["DENY<br/>agent cannot override"]
    P -->|under auto-approve threshold| C["Capture against float"]
    P -->|at / above threshold| H["Pending intent<br/>held for a human"]
    H -.->|out-of-band, agent can't reach| U["You: Telegram · dashboard · CLI"]
    U -->|approve| RC{Re-check at capture}
    U -->|deny| D
    RC -->|still in policy| C
    RC -->|now out of policy| D
    C --> L[("Append-only ledger<br/>balance derived from captures")]
    D --> L
```

Everything the agent can touch is on the left; the approval channel on the right is
deliberately out of its reach. [Play with this exact flow in your browser.](https://agentwallet.loopdesign.com.au/demo)

## Quick start (no secrets, mock money)

```bash
pip install -r requirements.txt
python test_policy.py          # 8/8 — the policy engine
python test_oauth.py           # 8/8 — the OAuth 2.1 core (16 tests total)
python server.py               # starts the MCP server (stdio)
```

With `WALLET_AUTO_APPROVE_UNDER_CENTS=0`, every charge the agent requests pauses as
`pending_approval` and prints an approval line to the console:

```bash
python cli_approve.py                    # list what's waiting
python cli_approve.py <intent_id>        # approve + capture
python cli_approve.py <intent_id> --deny
```

## Local dashboard

A single-page web UI to watch the balance, approve/deny pending charges, and read
history — dependency-free (stdlib), bound to `127.0.0.1`, and token-protected. Like the
CLI and Telegram, it's an out-of-band approver the agent cannot reach.

```bash
python dashboard.py     # prints http://127.0.0.1:8787/?token=... — open it
```

Set `DASHBOARD_TOKEN` to pin a token, or leave it blank to auto-generate one each run.

## Tools the agent sees

- `get_balance()` — float / spent / remaining
- `get_policy()` — the active limits
- `request_charge(amount, merchant, reason)` — creates a pending intent only
- `get_intent(intent_id)` — poll the outcome
- `list_transactions(limit)` — recent history

## Connecting an agent

- **Claude Desktop / MCP clients (stdio):** add this server (command `python`, arg
  `server.py`, cwd = this folder) to the client's MCP config.
- **ChatGPT (HTTP + OAuth):** run `server_http.py`, which wraps the same tools in an
  HTTP endpoint fronted by a real OAuth 2.1 flow (see below).

### ChatGPT connector (OAuth)

`server_http.py` (Starlette) serves the MCP endpoint at `/mcp` plus a full OAuth 2.1
authorization server (`oauth.py`): Dynamic Client Registration, Authorization Code +
PKCE, refresh tokens, discovery metadata, and bearer verification scoped to
`wallet.read` + `wallet.request_charge`. The `/authorize` step is gated by your
`OWNER_PASSCODE`, so only you can approve a connector.

```bash
pip install -r requirements.txt
export OAUTH_ISSUER=https://your-public-host   # ChatGPT requires HTTPS
export OWNER_PASSCODE=some-strong-secret
uvicorn server_http:app --port 8000            # put an HTTPS tunnel in front
```

In ChatGPT, add a custom connector pointing at `<OAUTH_ISSUER>/mcp`; it discovers the
OAuth endpoints, registers itself, and sends you to `/authorize` to sign in with the
passcode. The OAuth core is unit-tested (`test_oauth.py`), but the end-to-end ChatGPT
flow is yours to deploy behind HTTPS and verify. Never expose `cli_approve.py`,
`dashboard.py`, or the Telegram/Stripe processes to the agent.

## Approve from your phone (Telegram)

1. Create a bot with **@BotFather** → `TELEGRAM_BOT_TOKEN`.
2. Message the bot once, open `https://api.telegram.org/bot<token>/getUpdates`, read
   your numeric chat id → `TELEGRAM_CHAT_ID`.
3. `WALLET_APPROVER=telegram`, then run the poller alongside the server:

```bash
python telegram_poller.py
```

Now every over-threshold charge pings your phone with **Approve / Deny** buttons; one
tap finalizes it. Only messages from your own `TELEGRAM_CHAT_ID` are honoured, and the
agent has no access to Telegram — that's what makes it safe. You can also send
`/pending`, `/approve <id>`, `/deny <id>`.

## Going live with Stripe (recommended, economical)

Stripe Issuing is ~$0.10 per virtual card with no forced monthly minimum — you fund a
Stripe Issuing balance and spend against it. First confirm Issuing is **enabled on your
Stripe account** (Dashboard → Issuing; it may need activation, and this is where you
verify current availability in your country).

Stripe cards are **pull-based**: the merchant charges the card, so the hard ceiling is
the card's own `spending_controls`, enforced by Stripe independently of this server.

1. **Create the card once** (test mode first). In a Python REPL:
   ```python
   from issuer import StripeIssuer   # needs STRIPE_API_KEY set
   print(StripeIssuer().provision_card("Agent Wallet", "you@example.com",
                                        per_auth_cap_cents=5000, monthly_cap_cents=20000))
   ```
   Paste the printed id into `STRIPE_CARD_ID`, set `WALLET_ISSUER=stripe`.
2. **Fund the Stripe Issuing balance** with your set float — that's the max you can lose.
3. **Turn on real-time authorizations** and run the webhook so the policy engine gates
   each live charge (auto-declines out-of-policy amounts/merchants):
   ```bash
   stripe listen --forward-to localhost:4242/webhook   # Stripe CLI, in one terminal
   python stripe_webhook.py                             # in another
   ```
   For this path set `WALLET_AUTO_APPROVE_UNDER_CENTS` to your per-transaction cap so the
   card works up to the cap while float/24h/velocity/merchant limits still bind.
4. **Set `WALLET_APPROVER=telegram`** and run the poller so large buys the agent flags via
   `request_charge` hit your phone for a tap before it uses the card.

Alternative issuer (**Airwallex**, `WALLET_ISSUER=airwallex`): auth, a Payouts/Transfers
`execute_payment`, and a reconciliation read are implemented, but untested against the
live API and pricier — test in their demo host and verify fields first.

## Kill switch

Freeze/close the card at the issuer, revoke the agent's OAuth token, or just stop
`server.py`. The float is the maximum you can ever lose.

## Files

| File | Role |
|---|---|
| `config.py` | policy config from env |
| `policy.py` | **the safety boundary** — pure decision function |
| `store.py` | SQLite: intents, captures, audit; balance is derived |
| `issuer.py` | payment execution (mock / **Stripe** / Airwallex) |
| `approvals.py` | out-of-band notify (console / Telegram buttons) |
| `wallet.py` | orchestration shared by server + CLI + poller |
| `server.py` | MCP tools the agent can call |
| `cli_approve.py` | your approval channel — **not** an agent tool |
| `telegram_poller.py` | phone approvals via bot buttons — **not** an agent tool |
| `dashboard.py` | local web approval dashboard — **not** an agent tool |
| `stripe_webhook.py` | real-time Stripe authorization gate — **not** an agent tool |
| `oauth.py` | OAuth 2.1 authorization server for the connector |
| `server_http.py` | HTTP MCP transport + OAuth (ChatGPT connector) |
| `test_policy.py` / `test_oauth.py` | tests for the policy engine and OAuth core |

## Not implemented on purpose

OAuth for the MCP endpoint is left to you. The Stripe calls use the official SDK but
should be run in **test mode** first; the Airwallex calls are untested against the live
service. Anything that touches real money or credentials is yours to verify and
authorise.