Meera gives her shopping agent her PayPal account and $60 a week for lunch. On Tuesday a shop's listing tells the agent to add a $100 gift card, and nobody is at the checkout to say no.
Praman is the signed permission between the agent and PayPal: Meera signs her limits once, the agent can only name an item and a quantity, and plain code answers allow, ask Meera, or refuse.
PayPal doesn't trust the browser with the price, and Praman doesn't trust the model with it. Every decision lands on a hash-chained ledger you can recheck link by link, and it becomes the evidence if the charge is disputed.
Meera is an example, not a real user. The $60 budget, the $100 gift card and the refusal are the hosted demo's own figures.
Inspiration
An agent that shops reads text a stranger wrote, a product listing, and then calls a payment API. PayPal's own engineers describe the gap. Their post on AP2 says that with agents "the traditional assumptions underlying human-driven payment flows begin to break down", and it plans to extend Seller Protection with "mandate IDs and signatures". Their MCP Gateway post says "Discovery never replaces the final authorization check."
Praman started in September 2026 on Razorpay test mode. In a recorded run with its prompt defences off, the model was fooled 2 times in 21 and called the injected item "mandatory". The PayPal work began on 4 Nov 2026: the same mandate, policy function and ledger, now governing a PayPal wallet in dollars.
What it does
The agent proposes a purchase as a SKU and a quantity. The proposal has no price field. Praman reads the price from the catalog, checks the cart against the limits a person signed, and gives one of three answers from a single pure function with no model in it:
- Allow. PayPal is called.
- Ask a person. A person approves the exact amount, and every check runs again before money moves.
- Refuse. One of 21 fixed reason codes says why, and PayPal is never called.
Every proposal, decision, PayPal call and outcome is a row on an append-only ledger, each carrying the hash of the one before. Spend is replayed from the ledger, never stored in an editable column. Each purchase opens as a trace page listing the model's tool calls, with Verify in my browser (WebCrypto recomputes the hashes without trusting the server) and a dispute bundle.
The hosted demo is eight steps on the PayPal sandbox with a live model:
- A signed mandate: $60 in total, $40 a purchase, ask a person at $20.
- A poisoned listing, no PayPal login. The live model reads it, and a fooled model's cart (a recorded run, labelled) is refused with
CATEGORY_OUT_OF_SCOPE. A panel shows the same cart with no gate: $109.00, arithmetic over catalog prices. - Connect PayPal, saved once through Vault.
- A first purchase, $12.50, held for a person, then charged with no buyer present.
- A $4.50 coffee, allowed by code, no buyer present.
- A $32.00 team lunch, approved, paid at PayPal's checkout, re-checked before capture.
- Twenty purchases at once against a $30 budget: 5 paid, 15 refused with
MANDATE_BUDGET_EXHAUSTED, $30 of $30 spent. - Revoke the mandate. The next purchase is refused with
MANDATE_REVOKED.
The ledger console shows your session in AG Grid with charts, including Who did what: the agent's proposals, Praman's decisions, the person's approvals and revocation, and the test harness's rows counted apart.
The shop (/demo/shop, inside a session) runs the same gate on real products. Press one of three fixed errands (a dotted notebook, a pour-over kettle, noise-cancelling headphones) and the live model searches a pinned Channel3 snapshot through the agent's tools, with every product description wrapped as untrusted text. The page shows its tool calls, the cart at the pinned prices, and Praman's decision: in a hosted run the headphones were refused (CATEGORY_OUT_OF_SCOPE, audio isn't in the mandate) and the notebook ($20.50) and kettle ($34.95) were held for a person. It stops there. Every errand is marked "Decided, not bought", and the shop's rail is a stand-in that can't reach PayPal. There is no text box, so nothing a visitor types reaches the model, and an errand stops after six model calls or a minute.
In AP2's words, the under-threshold charge is "human not present" and the checkout is "human present". docs/PROTOCOLS.md maps each mandate field onto AP2 v0.2 and ACP's payment allowance and lists the gaps. Praman is AP2-shaped. It does not implement AP2.
How we built it
TypeScript in strict mode, a pnpm monorepo, Postgres with Prisma. Amounts are integer minor units typed bigint, and the currency comes from the signed mandate. Mandates are Ed25519 signatures over canonical JSON. Payment runs in two phases, because a database transaction and an API call can't be made atomic: one transaction decides and commits a pending record, the PayPal call happens outside any transaction, and a second transaction appends the outcome. A sweep settles anything left unknown.
How Praman uses PayPal
All calls are direct REST calls to the sandbox, in packages/paypal-exec.
| PayPal API | Calls | What Praman does with it | File |
|---|---|---|---|
| OAuth 2.0 | POST /v1/oauth2/token |
Client-credentials token for every call | src/client.ts |
| Orders v2 | POST /v2/checkout/orders, GET /v2/checkout/orders/{id}, POST /v2/checkout/orders/{id}/capture |
Creates an order only after an allow or approval, and re-checks the mandate before capture. A PayPal-Request-Id derived from mandate and cart means a retry can't charge twice |
src/executor.ts |
| Vault v3 | POST /v3/vault/setup-tokens, POST /v3/vault/payment-tokens, DELETE /v3/vault/payment-tokens/{id} |
Saves the buyer's account once, charges it by vault_id under the signed threshold, deletes the token at session end |
src/vault.ts, src/saved-method.ts |
| Payments v2 | POST /v2/payments/captures/{id}/refund |
Full refund started by a person, two-phase. Gives no budget back | src/executor.ts |
| Webhooks | POST /v1/notifications/verify-webhook-signature |
Verifies each capture event with PayPal before it can settle a ledger row | src/webhook.ts |
PayPal's Agent Toolkit, read-only. pnpm audit:paypal <trace_id> checks one ledger trace against PayPal's own record through @paypal/agent-toolkit with four read tools switched on (get_order, get_refund, list_disputes, get_dispute). Code gives the verdict, not a model, and it runs from a terminal, never on the hosted server (D-92). On 10 Nov it matched a real MCP purchase on 6 of 6 fields (order 56V771175V884405F, capture 6MM390005X981152Y).
Disputes, read back. In a sandbox dispute the buyer opened, PayPal's invoice number equals the ledger's receipt and its seller transaction id equals the ledger's payment id, so a dispute ties to one trace from PayPal's own fields.
How Praman uses AI
- The shopping agent on the hosted demo is Gemini 3.1 Flash Lite with tool use (
packages/agent-core). It reads the catalog and proposes a cart. Merchant text reaches it inside<untrusted_merchant_content>tags. - Any MCP agent can shop through
apps/mcp-gateway, a local MCP server with six tools and no field for a price. On 10 Nov a real model, Claude Code with the gateway as its only tools, was asked to buy a Leuchtturm1917 notebook ($20.50) and Sony headphones ($298) from the pinned Channel3 catalog. Praman refused the headphones (CATEGORY_OUT_OF_SCOPE: audio is not in the mandate) and held the notebook, a first purchase at that shop. The builder approved in their own terminal (the command refuses to run without a real terminal, so the agent can't approve itself), paid as the sandbox buyer, and Praman re-checked and captured, 61 seconds after the proposal (tracetrc_mcp_3b4eeda2-2189-4f69-8ba8-6f39be499f8b). Approving twice returns the same PayPal order. - No model takes part in a payment decision. The model shops. Code decides.
Render
One Render web service on the free plan, defined as a Blueprint in render.yaml. The health check reads /healthz, and the reconcile and release sweeps run inside the web process. The rate limit reads the visitor's address through Render's proxy chain, measured, not guessed (TRUST_PROXY=3). The database is on Neon.
AG Grid
The ledger console at /demo/console and /sample uses AG Grid Community 36.2.0 and AG Charts Community 14.2.0, pinned and served under a strict content security policy: one row per ledger entry with a server-side hash check, and four charts (spend against budget, decisions by reason code, orders by rail, who did what). Selecting a bar filters the grid. No Enterprise feature or AG Studio.
Channel3
pnpm catalog:channel3 pins a snapshot of real products from Channel3's product search (15 in the hosted import), each with its price in integer cents, source and fetch time. The local MCP gateway sells from that snapshot, and decisions use the pinned price. The hosted shop page decides errands over the same snapshot, imported into the hosted database, and buys nothing. The snapshot is not committed: Channel3's terms bar redistributing its catalog, so it lives only in the databases it was imported into (D-93). The server never calls Channel3, and paying the MCP gateway's shop pays this project's sandbox account, not the retailer.
Built since 1 Oct 2026
The Razorpay entry ended on 5 Sep 2026 (tag v1.0-submission) with one rail and rupees only. Built after 1 Oct, in 386 commits:
PayPal as a second rail in dollars; capture with a mandate re-check; saved-account charges with no buyer present through Vault v3; verified webhooks and full refunds; the hosted eight-step demo and public sample on Render; the AG Grid console; trace pages with a browser-side hash check; the MCP gateway and Channel3 catalog; the hosted shop page; the read-only Toolkit auditor; dispute bundles; and the policy eval on both rails.
Compare: https://github.com/Adwaith-R-Nair/Praman/compare/51012ef...paypal-hackathon
Challenges we ran into
- Twenty purchases at once overspent a budget four times over. Calls in flight weren't counted. Now an attempted call holds its budget until its outcome is known.
- The refusals leaked the limits. Decisions now have an internal form and a redacted public one, and a cap on refusals stops slow probing.
- Twenty purchases queued behind one lock. On the hosted site the last hit the driver's default 2 second limit to start a transaction. Limits are now 15 and 10 seconds, held under the reconcile sweep's 60 second bound by a test (D-91). The next hosted run passed first time.
- Missing data read as permission.
new Date("garbage")isNaN, and every comparison with it is false, so a broken validity window would have read as always valid.
Accomplishments that we're proud of
- The model can't state a price. The intent has no field for one.
- 28 of 28 attack cases contained (17 on the dev split, 11 held out), and 0 of 16 honest purchases refused, in a 46-case policy eval that runs in CI. 42 of those cases run again on the other rail and give the same answer.
- Verified on the hosted site with a sandbox buyer: all eight steps, a verified webhook, refunds, and twenty concurrent purchases stopping at exactly $30.00.
- Honest statistics. Every rate has its count and a 95% interval, and the prompt-defence test came out not significant (p = 0.49).
- A real model, refused and held. The 10 Nov MCP run above, checked afterwards against PayPal's record by the auditor.
- 1273 automated tests and 94 written decision records.
What we learned
A database transaction can't wrap a payment API, so a committed record before the call and a reconciler after it protect the money. A perfect score on an eval its author wrote shows little beyond matching the spec. In an authorisation path, anything missing must mean no.
What's next for Praman
None of this is built: sending a dispute bundle to PayPal as evidence (at the inquiry stage PayPal offered the app no action), an SD-JWT export with agent key binding so a mandate can be read by an AP2 verifier, partial refunds, and anchoring the ledger's Merkle roots outside the database.
Try it in 60 seconds
- Open https://praman-demo.onrender.com/sample. No login. It is one full hosted session, 85 ledger rows, with the chain verified by the server and a button to recheck it in your browser. The limits withheld from public pages stay withheld (D-84).
- Open https://praman-demo.onrender.com/demo and press Start a session. You get a signed mandate.
- Run A poisoned listing. No PayPal login. The fooled cart is refused, nothing is charged, and the panel shows the $109.00 the same cart would have cost with no gate.
- Open its Ledger trace and press Verify in my browser.
No real money moves anywhere in the demo.
Known limits
- Sandbox and test mode only.
- Not AP2 or ACP: no SD-JWT, no agent key binding, no network tokens, no interop test.
- In the hosted demo the server signs the visitor's mandate with a demo key.
- The MCP gateway and the PayPal auditor run locally, not on the hosted site. The hosted shop decides Channel3 errands and buys nothing.
- The shop shares each session's 40 model calls with the eight steps, and which product the model picks varies between runs.
- The shared sandbox buyer (D-85) exists in code but is switched off on the hosted site. Judges get a sandbox login in the testing instructions.
- Step 7 can still show an error page if any of the twenty purchases throws for another reason.
- The free server sleeps, and a cold start takes up to a minute.
- The perfect policy score is weak evidence against attacks nobody anticipated.
TRUNCATEbypasses the ledger's triggers, and Merkle roots aren't anchored externally.- Refunds are full only, and a refund made in PayPal's dashboard doesn't reach the ledger.
Built With
- ag-charts
- ag-grid
- channel3
- claude-code
- ed25519
- gemini
- model-context-protocol
- neon
- node.js
- paypal
- paypal-agent-toolkit
- paypal-orders-api
- paypal-vault
- paypal-webhooks
- playwright
- pnpm
- postgresql
- prisma
- render
- typescript
- vitest
- webcrypto
