Inspiration
AI agents can already find what they need, but the moment they have to pay, a human steps back in — or the agent gets a raw card and unlimited trust. I wanted the middle ground: the owner sets a budget once, and the agent pays for each request on its own, but can never step outside those limits.
What it does
GRAM-402 puts payments into plain HTTP. A paid endpoint answers 402 Payment Required with a price. The agent's owner approves a spending mandate on PayPal once: total budget, cap per request, expiry, allowed endpoints. After that the agent pays every request by itself, through PayPal captures, and receives the answer with a signed receipt bound to the PayPal capture id. The server stops the agent the moment a limit would be exceeded, and the owner can watch spending and revoke the mandate at any time from a simple owner page. The same 402 endpoint also accepts NEAR and TON payments.
How we built it
Python/FastAPI server with a PayPal rail: PayPal Vault v3 setup tokens for the one-time mandate approval and Orders v2 for per-request captures, with idempotency, budget and per-call caps enforced on the server. Agent clients in Python and TypeScript with their own price cap, an MCP server so any MCP agent can pay through the mandate without seeing the secret, and an AI shopper demo where an LLM decides with tool calls what to buy from a small API marketplace. Ed25519-signed receipts, an offline verifier, and a fake PayPal API so the whole flow is tested offline; CI workflows run the same flow against the live PayPal sandbox.
Challenges we ran into
Making limits impossible to bypass by the model: every rule lives on the server, not in the prompt. Confirming the owner's approval with PayPal itself (setup-token status) so the redirect does not have to reach the server. Making a repeated payment header return the first settlement instead of charging twice.
Accomplishments that we're proud of
Live PayPal sandbox runs reproducible from the repository: real captures, a budget stop and a revoke (run 41516703950), and a real LLM that bought only the data it needed and skipped the rest (run 42435322820, capture 4X69679972565823N). One 402 endpoint that accepts PayPal, NEAR and TON; receipts anyone can verify offline.
What we learned
Agent payments are mostly about limits and proof, not about moving money: the owner needs a cap, an off switch and a receipt for every cent.
What's next
A hosted owner dashboard, more PayPal products (Venmo, payouts to sellers), and packaging the paywall as a one-line middleware for any API that wants to sell to agents.
Try it
No account needed: pip install -r server/requirements.txt && python3 demo/paypal_agent_demo.py (simulated PayPal: two payments, budget stop, revoke). Tests: cd server && python3 test_app.py && python3 test_paypal.py && python3 test_near.py. Live sandbox: see "Run it yourself" in the README.
Built With
- ed25519
- fastapi
- github-actions
- llm
- model-context-protocol
- near
- paypal
- paypal-rest-api
- python
- ton
- typescript
