AIShop4U

The control plane that lets an AI agent spend at all: a spend-control layer with two ports — one to a merchant, one to a data provider — where every step the agent takes is visible, the purchase needs your approval, and the money it can move is capped at the total you approved and witnessed on-chain.

Every network shipped an agent-payment spec this year. Almost none of them answers the two questions that decide whether you'd actually let an agent loose with money: what stops it overspending, and who can verify what it did afterwards. AIShop4U is that layer. Shopping for a laptop is one instantiation; the market is anywhere delegated spend needs a hard cap and an audit trail — small-business procurement first, where finance teams block agent spend today precisely because there is neither.

Built for the Ripple challenge at Singhacks 2026: an AI-native business on XRPL with x402 agentic payments. Claude is the agent. AIShop4U is the MCP server and the inline widget between the agent and the money.

Product name: AIShop4U Team: BuffetClearers

The problem

Shopping asks you to do the boring work and then make the important decision at the worst moment. You already know you want a laptop. Everything after that is lookup: which of these nine are in stock, is this price real, is this seller real. Then, tired and eight tabs deep, you make the actual choice.

An agent could do the lookup in ninety seconds. Nobody lets one buy, because that means handing your card to software that makes decisions you never see, for reasons it will not show you.

AIShop4U moves the line. The agent takes the lookup. The human keeps intent at the start and judgment at the end. And the reason you can hand over the boring part is that you can see it was done properly.

Related MCP server: Allowance MCP

What happens in a session

1. You tell Claude what you want. Claude calls start_session; the AIShop4U monitor opens inline in the chat.

2. Claude asks for a price range. It cannot browse without one: the inventory endpoint refuses, below the model.

3. Claude browses AIShop4U's inventory (the only products that can be bought), picks up to five, and flags anything suspicious with the numbers it is citing. Flagged rows are struck through in the widget and labelled as the agent's claim, never hidden.

4. You select in the widget. Not in chat. The selection is a server record the model cannot forge.

5. You enter billing in the widget. It never enters the model's context; the server holds it for the session and deletes it after the invoice is sent.

6. Claude calls checkout. The approval card shows items, the flat fee, and the total. You approve in the widget. The approval is single-use, bound to the quote hash, and expires in five minutes.

7. Claude calls purchase. The server authorises your card for the total, draws a session wallet from a pre-provisioned pool, funds it from AIShop4U's treasury with exactly the item total in RLUSD, pays each shop over x402, and captures the card for what the ledger says left the wallet. The last payment carries the session's manifest hash in its memo.

8. The receipt shows what settled, the explorer links, what was charged, and the manifest. Nothing is kept: no balance, no wallet of yours, no stored value.

Two runs on the same server show it is not hardcoded to one category: a laptop, then a USB-C cable.

Why XRPL

Two jobs. It is the rail the purchase settles on — RLUSD from a session wallet funded to exactly the approved total, server-enforced and witnessed on-ledger — and it is the record: the hash of the session's append-only event log rides in the payment memo, so what the agent did and why is anchored somewhere neither we nor the shop can rewrite.

The session wallet is our answer to "why not just give the agent a card with a limit". A card credential is permission to pull: the limit lives with the issuer, and it is revocable and disputable only after the money has moved. A funded wallet is a balance, so the limit is arithmetic — the server funds it to exactly the approved total, below the model, and every payment out of it is proven on-chain rather than asserted. Payment Channels lock to one destination; Permission Delegation (XLS-75) scopes by transaction type, not amount. A funded-to-the-total wallet does both.

Architecture

User's card ──authorise / capture (mocked; Stripe test mode is the next step)──▶ AIShop4U   [fiat leg]
                                                                                  │
Claude (chat) ── MCP ──▶ AIShop4U MCP server                                        │ "card ok → fund session"
                          │                                                       ▼
                          ├── model-facing tools                   treasury wallet (RLUSD + XRP)
                          │     start_session, browse,                        │
                          │     propose, checkout, purchase                   │ fund / sweep
                          │                                                   ▼
                          ├── app-only tools (widget only)          session wallet pool
                          │     session_snapshot, session_events,             │
                          │     select_candidate, submit_billing,             │ x402 purchase, one per shop
                          │     approve_quote, abort_session                  ▼
                          │                                         merchant (mocked for the demo)
                          ├── session manager + event log            two shops, free browse,
                          │     append-only, hash-chained            x402-gated orders, invoice email
                          │                                                   │
                          └── payment layer                                   ▼
                                ├── wallet pool (pre-provisioned)        XRPL testnet
                                ├── policy: quoted == demanded,          t54 x402 facilitator
                                │   payTo == registered, RLUSD only
                                ├── signer, x402 client (x402-xrpl)
                                └── ledger verifier (recovery is checked on-chain)

          ui:// resource (MCP Apps widget)   ◀── polls app-only tools
          /dashboard?session=<id>            ◀── same bundle, read-only, over HTTP

Two rails, one bridge. The card never touches the ledger. The treasury holds RLUSD; on testnet it is bought from the XRP/RLUSD AMM. The only link between the legs is server code: card authorised, therefore fund the session; lines settled, therefore capture. AIShop4U is the merchant of record: you pay in fiat for a service with a price cap, and the on-chain spend is our treasury paying our suppliers. You never hold stablecoin and we never hold a balance for you.

The x402 flow

• The shop's order endpoint is gated by requireX402 from the x402-xrpl SDK (one middleware instance per product, since the SDK fixes the price per instance). A request without payment gets a 402 with PAYMENT-REQUIRED: scheme exact, network xrpl:1, asset RLUSD (40-hex code) with issuer, payTo, amount, and an invoice id.

• AIShop4U's client fetches the 402 first so the terms become an event, then pays through x402Purchase with our policy as the requirement selector: the demanded amount must equal the approved line, payTo must be the registered shop address, the issuer must be the RLUSD issuer, amounts must be canonical. A mismatch is refused before anything is signed and logged as payment.refused.

• The signed Payment carries the invoice id, which is <quote_id>:<line_id>:<manifest_hash>, in the Memo and InvoiceID field. The hosted t54 facilitator verifies and settles; the shop then creates the order and emails the invoice. The facilitator consumes the invoice once, and the shop is idempotent on the same reference, so a retry never pays twice.

• Anything uncertain after a payment header was sent is resolved by asking the shop for the order by reference and verifying the transaction on-ledger (payer, destination, exact amount, invoice binding) before the card is captured. The card is captured on what the ledger says left the wallet, never on what a response body claimed.

XRPL AI Starter Kit

We used three of its four parts. The XRPL Payments and Agent Wallet skills from XRPLF/xrpl-dev-portal were coding-time context for trustlines, RLUSD payments and agent transaction conventions (our payments carry the x402 SourceTag and a session memo, per the "track agent behaviour" guide). x402 via t54 is the runtime piece: the x402-xrpl SDK on both the shop and the client, and the hosted testnet facilitator. The XRPL Docs MCP server was used by the coding agents, not the product. We also vendored the challenge repo's xrpl-agentic-resources skill for live reserve and amendment values.

Governance, in one table

Transactions on XRPL testnet

From the first end-to-end run driven by a human inside Claude Desktop (session s_27aac348d068e8fd, 5 Sep 2026):

Earlier verified transactions:

Refusal events are first-class: every session in .sessions/ from the driver runs contains an approval.refused event where purchase was attempted before approval, and the unit suite covers payment.refused for a 402 that demands the wrong amount or the wrong destination. The judge-facing endpoints:

curl localhost:3001/sessions/<id>          # snapshot, never billing content
curl localhost:3001/sessions/<id>/events   # the chain
curl localhost:3001/sessions/<id>/verify   # re-hash from genesis

Setup

Requirements: Node 22, npm 10, Claude Desktop. Testnet only; no mainnet keys anywhere.

git clone --recurse-submodules https://github.com/decker757/BuffetClearerMCP.git
cd BuffetClearerMCP
npm install
cp .env.example .env            # defaults are fine for testnet

npm run spike:xrpl              # creates .wallets/spike.json: treasury + a shop wallet, sets RLUSD trustlines
npm run fund:treasury -- 1500   # buys RLUSD from the testnet XRP/RLUSD AMM (no web faucet needed)
npm run provision -- shops      # two shop wallets with trustlines -> .wallets/shops.json
npm run provision -- pool 2     # session wallet pool -> .wallets/pool.json

npm run build                   # all packages, including the widget bundle
npm test                        # 104 tests: money math, hash chain, shops, policy, settlement, session, tools, projection, failure modes
npm run eval                    # agent behaviour evals: real Claude over the real tool surface (needs ANTHROPIC_API_KEY)

docs/EVALUATION.md is the testing story in one page: what the four layers prove, the numbers (104 tests; 10/10 agent scenarios; the planted listing flagged 5/5 with numbers cited), how tracing works, and three curl commands to verify any session's hash chain yourself.

Run the mock merchant, then register the MCP server in Claude Desktop:

npm run dev -w @aishop4u/shops    # http://localhost:4002
npm run setup:claude              # writes the Claude Desktop config for your OS

setup:claude works on macOS, Windows and Linux: it finds the Claude Desktop config in the right place for your OS and registers the server with the absolute path to your node (process.execPath). That last part matters — Claude Desktop launches MCP servers with a minimal PATH that does not include Homebrew, nvm, etc., so a bare "command": "node" fails with "Server disconnected" whenever node is not on that PATH. If you prefer to edit the config by hand (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/… on macOS), use the absolute path to both node and dist/main.js, not a bare node:

{
  "mcpServers": {
    "aishop4u": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/main.js", "--stdio"]
    }
  }
}

Quit Claude Desktop from the tray and reopen. In a new chat with web search off: "Use AIShop4U: I want to buy a laptop." Give a range like 300 to 1300 so the planted too-good-to-be-true listing is in range.

Without Claude, the whole loop can be driven by script against the real shops and testnet:

npm run dev:mcp                          # http://localhost:3001 (MCP over HTTP + read endpoints + /dashboard)
npx tsx scripts/mcp-smoke.ts "laptop" 500 1300

Before a demo: npm run sweep:shops (the mock shops hand their RLUSD back to the treasury), npm run provision -- repair, then curl localhost:3001/health.

Repository

packages/shared      money math (integer cents), canonical JSON + hash chain, zod schemas
packages/payments    policy, wallet pool, mock card, XRPL ledger + verifier, x402 client, settlement
packages/shops       the mock merchant: seeded catalog, free browse, x402-gated orders, invoice stub
packages/mcp-server  event log, session manager, tool surface, HTTP reads, dashboard route
packages/widget      the MCP Apps monitor (single-file bundle), also the read-only dashboard
packages/evals       agent behaviour evals: real Claude over the real tool surface, scored from the event log
scripts/             provisioning, funding, sweeping, drivers
data/catalog.json    16 products across two shops, one planted bad listing
docs/EVALUATION.md   what we test and how, the numbers, and three curl commands to verify a session yourself
docs/FAILURE-MODES.md  every failure: what the user sees, where the money ends up, and the test that proves it
docs/REVIEW-LOG.md   every mistake the phase reviews caught, why it mattered, and the test that guards it
CLAUDE.md            the full design: invariants, build order, decisions, demo script, compliance posture

Testnet, and what changes on mainnet

Everything above runs on XRPL testnet with the hosted t54 testnet facilitator. On mainnet: the treasury is topped up from an exchange as a periodic operation rather than from the AMM; each pool wallet locks the base reserve plus one owner reserve for the trustline (live values are vendored under ripple/skills/.../xrpl-fee-settings.json); the card leg becomes Stripe with manual capture; seeds move from files to a KMS; and the merchant is a real shop that added one header.

Roadmap, not built

Per-query micropayments for comparison data (price history, spec databases) at fractions of a cent, from the same wallet and into the same log. Kept out of this build on purpose.