Inspiration

Two problems kept coming up.

The cheapest price tag is often not the cheapest purchase. Buy a $13.99 bottle from a US shop for delivery to the UK and you add shipping, UK import VAT and a currency-conversion cost; a £15.00 UK listing ends up cheaper. Most comparison tools stop at the price tag.

AI agents are starting to get wallets. An agent that can pay needs what a person with a company card has: limits, an approval step for bigger spends, and an audit trail. And those limits have to hold even when a product listing contains text written to hijack the agent.

What it does

You set a spending mandate: a per-purchase cap, a monthly cap, an auto-buy limit, a maximum number of units, and which shop countries are allowed. You link a PayPal wallet once. Then you ask in plain English, for example "Get me a 1L insulated water bottle, delivered to the UK, under £40."

  1. Searches shops in the UK, US and Germany (Channel3 product data).
  2. Ranks every offer by true landed cost: price, shipping, estimated UK import VAT and duty (including the £135 low-value rule and removal of the origin country's VAT), and the estimated currency-conversion cost. In our demo search of 36 offers, the cheapest price tag (13.99 USD) ranks 5th: it lands at 26.75 GBP, against 18.99 GBP for the best purchase.
  3. Checks the mandate in code, not in the model. Each purchase is decided as auto-buy, needs your approval or denied, with plain-English reasons.
  4. Pays through PayPal with a vaulted wallet and a merchant-initiated order, so purchases within the auto-buy limit need no redirect. Bigger ones wait in an approval inbox, and approving pays exactly the cart you saw.
  5. Checks with PayPal. After paying, the agent asks PayPal itself, through PayPal's Agent Toolkit, for its record of the order and reports whether it agrees with TrueCart's ledger: order, status, amount, capture, fee and tracking. The same check is one click on the Ledger.
  6. Records and reconciles. PayPal webhooks confirm each capture, the ledger compares our fee model with PayPal's capture breakdown, and the (simulated) shop registers a PayPal tracking number. Simulated delivery progress flags overdue parcels and prepares the evidence for an "item not received" claim.

TrueCart is also an MCP server. Connect another AI assistant with a mandate token, and it shops under the same limits and approvals. It cannot change them, and you can revoke it.

The Red team page shows the core safety property. A deliberately hostile listing says the owner "pre-approved" 20 units and raised the limit. Run it through the agent, or skip the AI entirely and send the attacker's exact request to checkout: both are denied, and the budget is untouched.

How we built it

  • Next.js and TypeScript, one typeface, light and dark themes. AG Grid (Community) powers the offer ranking and the ledger:
    • market and mandate filters, quick search and "N of M shown";
    • cost-breakdown tooltips and best-offer row styles;
    • totals pinned under the ledger (computed on the server);
    • CSV export protected against formula injection.
  • PayPal (sandbox):
    • Vault v3: setup token, buyer approval, payment token;
    • Orders v2 merchant-initiated orders (vault_id plus stored_credential) in GBP, USD and EUR, with PayPal-Request-Id idempotency;
    • the capture's seller_receivable_breakdown for reconciliation;
    • webhooks with signature verification, de-duplicated by event id;
    • order tracking (/v2/checkout/orders/{id}/track);
    • PayPal Agent Toolkit (@paypal/agent-toolkit): its MCP server runs in-process with only two read-only tools enabled, get_order and get_shipment_tracking. It is forced to the sandbox, because the toolkit defaults to production.
  • Mandate policy engine: pure TypeScript with table tests and property-based tests (fast-check). The property tests throw random sequences of purchases at the engine and check that monthly spend never passes the cap. Approvals are single-use and bound to the exact cart.
  • One payment executor is the only code that can move money. It re-checks the mandate and reserves the worst case (including an FX buffer) in the same database transaction that consumes the approval. It retries timeouts with the same PayPal-Request-Id, so nothing is charged twice, and it never captures more than it reserved.
  • AI: Google Gemini (free tier) behind a provider-neutral agent loop with eight tools. The model can only pass a search query, an offer reference and a quantity; every price, total and limit comes from our code. Invented tools and smuggled fields are rejected, and a guard corrects any answer that claims a purchase the executor did not confirm.
  • Untrusted product text is stripped of hidden characters and handed to the model as labelled data, never as instructions.
  • Money is always integer minor units with exact rational FX rates: no floating point.
  • Hosting: Render. Each visitor gets a separate demo workspace.

Challenges we ran into

  • Same product, different IDs. Channel3 gives each market's listing its own ID, so matching "the same product" across countries needed brand plus title similarity, clearly labelled as a likely match.
  • Where does the shop ship from? Offers don't say, so it is inferred from the store domain or the search market and flagged when it's a guess.
  • Approvals without races. Re-checking the policy, consuming the approval and reserving the money had to be one atomic step.
  • PayPal's hosted sandbox MCP server listed its tools, but every call failed server-side when we tested it. Running PayPal's Agent Toolkit in-process gave us the same tools, working.
  • Free-tier model limits. When the live model is busy, the demo request falls back to a clearly labelled recorded run. This only happens if nothing has been bought yet, so a purchase is never repeated.

Accomplishments that we're proud of

  • The agent cannot overspend, even fully hijacked, because the limits live in the payment path, not in the prompt.
  • PayPal's own record matches our ledger field for field: order, status, amount, capture, invoice id, fee and tracking, read back through PayPal's Agent Toolkit.
  • Our merchant-fee model matched PayPal's actual fee exactly on 10.00 USD, GBP and EUR calibration charges, and came within 1p on an 18.99 GBP purchase (1.33 vs 1.34 GBP).
  • 326 unit and property tests, 9 end-to-end browser tests, and a smoke script that runs the judges' path against the live site.

What we learned

  • PayPal's vaulted, merchant-initiated orders make "an agent pays within limits" practical: one API call, no redirect, idempotent retries.
  • The landed-cost gap is real and explainable, and people get it immediately when they see the cost build-up.
  • Prompt rules are not a security boundary. The mandate has to be enforced where the money moves.

What's next for TrueCart

  • Real shipping quotes and product-specific duty rates instead of simulated shipping and a duty estimate.
  • More buyer countries.
  • Automatic "item not received" disputes once buyer-side dispute access is available.

Please note: what's simulated

  • PayPal sandbox only. No real money moves. Every payment goes to one sandbox business account acting as the merchant of record. Listings come from real product data, but the merchants are simulated.
  • Shipping costs and delivery progress are simulated. Import VAT, duty and the conversion cost are estimates and labelled as such.
  • Brand and store names are masked in the demo.

Built With

  • ag-grid
  • channel3
  • fast-check
  • frankfurter-api
  • gemini
  • github-actions
  • lucide
  • model-context-protocol
  • next.js
  • node.js
  • paypal
  • paypal-agent-toolkit
  • paypal-orders-api
  • paypal-vault
  • paypal-webhooks
  • playwright
  • react
  • render
  • sqlite
  • tailwindcss
  • typescript
  • vitest
  • zod
Share this project:

Updates

Submission history