Agent Wallet Guard

Inspiration

AI agents are starting to move money, but a prompt is not a safety control. I wanted a merchant to hand an agent a PayPal account and still be sure about three things: limits the agent cannot change, a human for risky payments, and a record of every decision.

What it does

Agent Wallet Guard is an MCP server in front of a merchant's PayPal account. An agent can create invoices and issue refunds through four tools: create_invoice, refund, check_approval and get_policy.

• The merchant sets rules in one plain sentence, for example "spend at most $200 a day, no single payment over $80, ask me above $50, refunds at most $30 each".
• Every request is decided by deterministic code: executed, denied with a plain-language explanation, or held for human approval.
• Approval happens in a terminal tool the agent cannot reach. There is no MCP tool to approve payments or change limits. Limits are re-checked when an approved payment executes.
• Every decision is stored in an audit log and shown on a read-only dashboard.

Everything was tested in the PayPal sandbox only, with test money.

How I built it

Python, MCP Python SDK v1, FastAPI-style flat structure, httpx, SQLite, PayPal Invoicing v2, Orders v2 and Payments v2 (refunds with idempotency keys), Gemini API (gemini-flash-lite-latest) and Langfuse.

• The model never decides whether money moves. Gemini only translates the merchant's sentence into rules and explains decisions. Its output is validated in code (NaN, infinity and negative values are rejected), and explanations fall back to the technical reason if the model is unavailable.
• Optional Langfuse tracing records every LLM call (rule parsing and explanations). It never affects decisions, and the server works the same without it.
• 18 unit tests. Open source, MIT.

Challenges

• Keeping the language model out of the money decision while still making rules easy to write.
• Re-checking hard limits at approval time, so a stale approval cannot exceed the policy.
• MCP SDK v2 renamed FastMCP, so I pinned mcp[cli]<2; mcp dev does not work in a Windows virtualenv, so I run Inspector through npx.
• Gemini model availability on new free keys (gemini-2.5-flash was unavailable).

Accomplishments

An end-to-end flow in the PayPal sandbox: executed, denied and approved payments, refunds with limits, an audit log and traced LLM calls, with a clear rule that the AI cannot move money by itself.

What I learned

I think such MCP server can really be helpful in business, especially in routine actions like refunding.

What's next

A payout tool, approvals through messaging apps, per-agent budgets and anomaly detection. Live mode testing is out of scope until the controls have been reviewed.

Built With

• docker
• fastapi
• github
• langchain
• langfuse
• langgraph
• mcp
• paypal
• pydantic
• pytest
• python
• react
• sandbox