How I built it

AgentPay Guard has a React + Vite + TypeScript frontend and a FastAPI backend with SQLite. The core idea is a strict trust boundary: AI proposes, deterministic rules decide, a human approves, and the backend verifies.

  1. The user describes what they want in plain English, by typing or by voice.
  2. The AI model receives the request and the catalogue, and can only return a product_id with a rationale.
  3. The server looks up the authoritative price and merchant from the database. Nothing about money ever comes from the browser or the model.
  4. A deterministic policy engine checks the per-order cap, total budget and merchant allowlist, and returns ALLOWED or BLOCKED with machine-readable reason codes.
  5. The user must explicitly click Approve & Pay. The backend re-checks policy at that moment, then creates the PayPal Sandbox order.
  6. After buyer approval in PayPal Sandbox, the server captures the order, verifies status, amount and currency, and only then updates the budget.

How PayPal is central

  • Orders v2 API (Sandbox): Server-side order creation with intent=CAPTURE, using prices computed on the server in integer cents.
  • OAuth 2.0 client credentials: Tokens are fetched and cached on the backend, and no secrets reach the browser.
  • Idempotency: Every create and capture call carries a unique PayPal-Request-Id, so retries never double-charge or double-spend the budget.
  • Server-side verification: A payment is marked captured only after the backend confirms COMPLETED with the matching amount and currency, never from a redirect or URL parameter.
  • Webhook signature verification: Incoming notifications are validated through PayPal's verify-webhook-signature endpoint.
  • Clean cancellation: Cancelling in PayPal marks the transaction cancelled without touching the budget.

How AI is used

  • Gemini (with OpenAI support) turns natural-language requests like "a wireless mouse for work under $35" into a catalogue-constrained recommendation.
  • The model never sees or sets prices, and it cannot approve anything. Even a manipulated or hallucinated answer still has to pass the policy engine and a human click.
  • When no API key is configured, a deterministic keyword matcher takes over and is clearly labelled Demo Fallback Mode, so judges can test every flow without paid keys.
  • A voice assistant (Web Speech API, en-IN / en-US) lets users make requests by speaking, using the same guarded pipeline.

Inspiration & Purpose

I was inspired by the growing use of AI agents to make decisions and perform tasks on behalf of users. While AI can make online shopping faster and smarter, allowing an AI agent to spend money without proper controls creates risks such as unauthorized purchases, budget overruns, and untrusted recommendations.

I wanted to explore how AI-powered commerce could become safer and more trustworthy. This led me to build AgentPay Guard, where AI assists with product recommendations while deterministic rules, human approval, and PayPal's secure payment infrastructure control the actual transaction.

My goal was to demonstrate that AI agents can be useful in financial workflows without giving them unrestricted authority over money.

Challenges I ran into

  • Making the LLM not the security boundary: I designed every check so it holds even if the model output is wrong or adversarial.
  • Budget accuracy: I used integer cents end to end and made capture idempotent so retries cannot overspend.
  • Concurrent orders: Limits had to count in-flight orders as well as captured ones, so two pending orders cannot together exceed the budget.
  • Binding approval to the exact proposal: The user's approval is tied to a specific product, price and merchant, so it cannot be reused for a different purchase.
  • Reliable demos with live AI: Model availability and API quirks made live AI flaky, which is why the deterministic fallback mode exists.

What I learned

  • Keep the generative layer strictly separate from the financial layer: the LLM suggests, code validates, humans decide.
  • Never trust client-supplied prices or merchants. Server-side truth is the only truth.
  • A mandatory approval gate plus an audit trail makes AI commerce something users can actually trust.

Accomplishments I'm proud of

  • A full automated test suite covering the policy engine, payments, idempotency, webhooks and voice, with a clean TypeScript build.
  • A real PayPal Sandbox purchase captured and verified end to end.
  • An immutable audit trail of every proposal, verdict, approval, capture and cancellation.
  • One-click demo reset so judges can repeat every scenario.

What's next for AgentPay Guard

  • Multi-tenant accounts with role-based budgets (employee vs. manager limits).
  • PayPal Subscriptions and Vault for recurring agent allowances.
  • Native mobile SDKs for embedding the guard in other agents.

Built With

Share this project:

Updates

Submission history