Inspiration

AI agents can now pay on people's behalf. When an agent buys something its owner never wanted, the payment was authorized (the agent had permission) but not intended. PayPal's own merchant research (498 US merchants, April 2026) found no clear agreement on who is responsible when a customer disputes an agent's purchase. Today the only fix is reversing the payment afterwards: fees, time and disputes. We wanted the check to happen before the money moves.

Payments run on trust. I wanted agents to earn it before they spend.

What it does

Spending limits stop how much an AI agent spends. AgentGuard checks whether the buyer meant it.

The buyer writes what they want in plain English ("one pair of noise-cancelling earbuds from SoundMart, under USD 150, up to USD 500 this week"). An AI drafts rules from it; nothing applies until the buyer approves them. The rules are versioned and fingerprinted. (Rule drafting is off on the public demo, which has no paid AI key; it runs locally with your own key.)

When the agent asks to pay, AgentGuard checks the cart against those rules, the shop's own records and an independent product catalogue, never the agent's word:

  1. Rules: budget, shops, item price cap, quantity, expiry.
  2. Hidden-instruction check on the page the agent read.
  3. AI intent check: does this cart match what the buyer asked for? The AI can only make a decision more cautious, never less; any AI error or timeout means "ask the buyer".
  4. Channel3 market price and product check: a price more than 20% above the market middle holds the payment; a listing that isn't the real product asks the buyer first.

Then one of four decisions: approve (PayPal authorizes and captures), hold (PayPal authorizes; the buyer says yes to capture, or no to void at USD 0.00 fee), ask first or block (PayPal is never called). Every decision gets a signed receipt (Ed25519) and an entry in a hash-chained audit log; a reviewer works through them in an AG Grid console.

To be adoptable: per-agent revocable keys, an MCP server whose four tools cannot approve or move money, and a shadow mode that lets a merchant see what AgentGuard would have stopped before turning it on.

How we built it

  • PayPal (sandbox): OAuth 2.0 client credentials; Orders v2 with intent: AUTHORIZE (the mandate fingerprint rides in custom_id); Vault saved card, merchant-initiated, so the agent pays with no buyer present; Payments v2 capture, void and get authorization; PayPal-Request-Id on every money call, so a retried capture returns the same capture; webhooks believed only after verify-webhook-signature succeeds (refunds, reversals, denials and disputes update the payment, the budget and the log). All calls go through the APIMatic-generated PayPal Server SDK.
  • AI: gemini-3.5-flash-lite drafts the rules and runs the intent check. The six demo scenarios replay real model answers saved from earlier checks, labelled "saved answer" on screen, so they behave the same for every judge. The public demo has no paid AI key, so live AI is off there; run it locally with your own key for live answers.
  • Sponsor tools, one job each: Channel3 (market price and product identity, the only source that is neither the shop nor the agent), AG Grid Community (review console with approve/reject inside the grid), APIMatic (SDK and the PayPal Context Plugin, used to build the gateway and later to review it: 9 findings, 3 fixed with tests), Render (hosts the live demo from a one-file Blueprint).
  • Engineering: Python, FastAPI, SQLite with an atomic budget reservation (one conditional UPDATE); 251 tests, 94% line coverage (11 Nov), CI on every push; threat model; CSP, HSTS and rate limits.
  • Evaluation planned before results: frozen attack sets, a held-out set, and a pre-registered real-agent experiment with its plan hashed before the runs.

Challenges we ran into

  • Limits can't see intent. Rules alone caught 0 of 75 attacks that stayed inside the budget. That result shaped the whole design.
  • Too many questions to the buyer. On the held-out set 20% of good purchases were asked about, above our own 15% target. With the AI unavailable that rises to 83%. We report it rather than tune it away.
  • Free-tier AI is unreliable under load. 31 Google "503 high demand" errors during the real-agent runs; every error line is kept, and the fail-safe asks the buyer.
  • An independent review (decision log, tests) of the near-final code found 16 issues; 11 were fixed, each with a test that failed before the fix, and the rest were reworded or documented as limits. It also found that three normal-shopping slots in the agent experiment ran twice, against our own plan; we disclose it.

Accomplishments that we're proud of

  • On 75 natural-language attacks that stay inside the spending limits: rules alone 0/75, rules + AI 71/75, with 0 of 42 good purchases blocked. Held-out set: 95/95 caught, 0/30 blocked.
  • A real AI agent (Strands, through our MCP server, plan fixed in advance): 0 harmful payments in 34 completed runs. When the agent lied about a price it was caught 5 of 5 times, and PayPal was never called.
  • Saying "no" to a held payment costs USD 0.00 (void) instead of the USD 1.53 lost on a USD 40 capture-then-refund in our sandbox test.
  • A final live check on the public site before code freeze: 21 of 21 checks behaved as expected, including a double approval (one succeeds, one is refused), a receipt that fails if the amount changes by 1 cent, and approve and reject clicked inside the AG Grid console.

What we learned

  • "Authorized" and "intended" are different questions; spending controls answer only the first.
  • Let the AI escalate, never relax: it makes model errors cheap.
  • Publishing misses (the 20% ask rate, the duplicated slots, the "repair" group that measured nothing) makes the numbers that did hold up believable.

What's next for AgentGuard

Durable storage (PostgreSQL), held payments that void themselves before PayPal's honour period, the buyer approving rules on PayPal's own page, a proxy in front of PayPal's agent toolkit, a cross-order "one pair" check, and AWS hosting with KMS-held signing keys. The full list is in docs/production-gaps.md.

Limitations

PayPal sandbox and synthetic test data, so results show the mechanism works, not real-world rates. AP2-style mandates, not the full AP2 protocol. One guard model, chosen by constraint. The Channel3 product check is unit-tested and live-checked once, but not in the measured results. Demo data lives in memory and resets on restart. The real-agent experiment is small: 34 runs, one agent framework (Strands with Gemini), one synthetic shop.

Links

Built With

  • ag-grid
  • apimatic
  • channel3
  • claude
  • fastapi
  • gemini
  • github-actions
  • javascript
  • mcp
  • oauth2
  • paypal
  • paypal-orders-api
  • paypal-payments-api
  • paypal-rest-api
  • paypal-server-sdk
  • paypal-vault
  • paypal-webhooks
  • pytest
  • python
  • render
  • sqlite
  • strands-agents
Share this project:

Updates

Submission history