Inspiration
AI agents can now shop online. They search a catalog, compare items, and start a checkout. This power creates a risk: an agent can spend more money than the owner allows.
Most projects express a spending limit as text in a prompt. A line that says "only spend $40" is a suggestion. The model can ignore it. The payment layer never sees the limit.
I wanted a stronger design. The human signs a spend mandate before the agent runs. The mandate states a cap, a category scope, and an expiry time. A server checks the mandate before any money moves. Prompt text is never permission.
I built this idea for the PayPal AI Hackathon 2026. The project is greenfield and solo.
This is my first hackathon at this level. I am 18 years old. I am really happy to take part, and proud to submit a working project.
How I built it
The stack: React + Vite client, Node server, TypeScript everywhere, Playwright for end-to-end tests.
1. The mandate. The server stores the mandate as canonical JSON signed with HMAC-SHA256. It compares signatures with a timing-safe function. Eight unit tests cover tamper, expiry, over-cap, out-of-scope category, foreign secret, and partial-spend edges.
2. The guard. Before the server creates an order, it checks a single-use cart fingerprint:
$$\text{fp} = \mathrm{SHA256}(\text{run} \,|\, \text{mandate} \,|\, \text{SKU} \,|\, \text{amount} \,|\, \text{category})$$
The server verifies fp in the same run that creates the order. A cart from an
old run fails the check. The client cannot skip this step.
3. The money path. PayPal Orders v2. A mock state machine runs by default. A sandbox facade (OAuth, create, poll, capture) runs when credentials exist. Any error degrades the flow back to mock mode.
4. The agent. Two modes share one tool layer. A deterministic scripted core runs the demo of record. An optional live LLM loop adds free-text goals, a 10-second timeout, and automatic fallback to the script.
5. The audit. Every tool call, verdict, and block streams over SSE into an AG Grid log in real time.
6. The human. The agent can never capture a payment. Only the payer approves.
Build order: scaffold and audit bus, then storefront and mandate with tests, then agent loop and guard, then PayPal facade and live LLM, then hardening. The last step added a Docker path for judges.
Challenges I faced
The grid hid the key moment. My demo rehearsal showed the problem. AG Grid used virtualization and an oldest-first order. After about 11 events, the BLOCKED row fell below the fold. A judge would never see the best part of the demo. I fixed it with log-tail behavior: the grid scrolls to new events only when the reader sits at the bottom.
AG Grid error #239. The old theming approach failed. I moved to the v36 Theming API and set the theme parameters to match the design.
A Node version trap. The scripts use
--env-file-if-exists, which needs Node 22.9 or newer. The README claimed Node 20+. I setenginesto>=22.9, corrected the README, and documented Docker as the no-Node path.Nothing loaded
.env. The project had no dotenv dependency. I added the Node-native--env-file-if-exists=.envflag to the dev and start scripts.A secret almost shipped. A signing secret sat in the tracked
.env.examplefile. I caught it before the commit. It never reached the remote. I moved the secret to.env, restored the placeholder, and rotated the key.Live LLM runs varied. I tested four free models against the exact tool schema. One returned rate-limit errors. Another router gave nondeterministic results. I picked the model that returned valid tool calls at 394 ms, and I kept the scripted fallback for every other case.
No image credits for the UI. The first design direction failed review. Image generation had no credits left. I built five real-CSS design flavors, took screenshots with Playwright, and let the choice happen on real pixels. The pick: neo-brutalist. Cream paper, 3px black borders, hard offset shadows, acid yellow and signal red.
What I learned
- Prompt text is not permission. A signed artifact checked on the server is.
- A deterministic path makes a reliable demo. Judges see the same result every run.
- Rehearse the demo before you record it. The rehearsal found the bug that would have hidden the best moment.
- Keep secrets out of tracked files. Check before every commit.
- Show every degraded state as a visible status chip. Never show a dead screen.
Built With
- ag
- agent
- ai
- api
- grid
- llm
- openai-compatible
- orders
- paypal
- server-sent
- tool
- zod