Inspiration

AI agents can already pay. The usual way is to hand them a card with a spending limit. But a limit only answers how much, never for what. A $100 limit lets an agent spend $100 on anything, including something a product listing talked it into. When a charge looks wrong, all you have is a transaction line, not a reason.

People already solve this with each other through budgets: "here's money for groceries and the dog's food this week." I wanted an agent to work the same way. It asks for money for named reasons, gets approval, and is held to those reasons when it pays.

PayPal's authorization holds turned out to fit almost exactly. Approving a budget reserves money on your own PayPal account. Each purchase captures part of the hold, and whatever is left is released back to you.

Cards limit the spend. Remit limits the purpose.

What it does

Remit is a spending wallet for AI agents.

  1. The agent proposes a budget. Each line has an amount and a reason with evidence: what past weeks cost, when something was last bought, the prices it found. There's an optional shared buffer of about 10%.
  2. You approve it on PayPal. You can trim or remove lines first. Approving creates a PayPal order with intent AUTHORIZE, which places a hold on your own account. There's no new card, and the agent never sees payment details.
  3. The agent spends line by line. Each purchase is a partial capture from the hold. It can use its own line and then the shared buffer, never another line. Before any money moves, an independent purpose check (a separate Claude call that never sees the pages the agent read) compares the purchase with the line's approved reason.
  4. At the limit, it asks. The wallet refuses with a reason, the refusal goes in the ledger, and the agent asks for a top-up with its own reason. A top-up is a new PayPal approval and a new hold.
  5. The leftover comes back. At the end of the period, untouched holds are voided right away, and partly captured holds are released when the authorization expires.
  6. Any agent can use it. Remit exposes get_history, get_balance, request_budget, request_topup and spend over MCP, both remotely (Streamable HTTP at /mcp) and over stdio. Each agent gets its own token, which you can pause or revoke, and every agent is held to the same rules as the built-in one.
  7. It reaches you on your phone. Budget requests arrive as push notices with signed one-tap Approve and Decline links. Refusals and a weekly recap arrive the same way.

The spend rule, for a purchase of amount p on line:

$$ p \le r_\ell + r_{\text{buffer}}, \qquad p \le H - C, \qquad \text{purpose}(p, \ell) = \text{approve} $$

Here r is what's left on a line, H is the total held, and C is the amount already captured. All three must hold, and PayPal's own capture ceiling backs up the second one.

A real run on the PayPal sandbox

  • The agent asked for $132.49: groceries $88.00 ("two orders a week, $87 to $88 for the last four weeks"), dog food $32.49 ("last 12 kg bag Oct 16, three weeks ago") and a $12.00 buffer. I approved it on PayPal.
  • Dog food, $32.49: paid. The purpose check noted it was the same bag and price as the last order.
  • A birthday gift: no line. The agent didn't borrow from groceries or the buffer. It listed options and asked me which one, and how much.
  • Top-up, $104.50: approved as a second, separate hold, with the reason "$95.00, plus about 10% for shipping or a price change."
  • Headphones, $95.00: paid, from the hold that funds that line.

How I built it

  • Wallet (src/wallet/wallet.ts): every money rule lives in server code, not in a prompt. Per-line envelopes, a shared buffer, a check against the total held, and recorded refusals. Money-changing calls go through a queue, and each one is a single SQLite transaction, so two purchases can't both pass. Amounts are integer cents.
  • PayPal (Orders v2 and Payments v2, sandbox): orders with intent AUTHORIZE, partial captures with final_capture on the last one, reauthorization after the 3-day honor period, voids and refunds. Every write carries a PayPal-Request-Id, so a retry can't charge twice. The wallet records which hold funds each line and captures from that hold.
  • Webhooks: PayPal tells Remit about approvals, declines, voids and expiries. Each event's signature is verified with PayPal and its ID is stored, so a redelivered event is ignored. Asking PayPal directly stays on as a fallback.
  • Shopping agent: Claude Opus 5.5 (claude-opus-5-5) in a tool loop with the five wallet tools plus product search through Channel3.
  • Purpose check (src/wallet/reviewer.ts): a structured-output Claude call that gets only the line's approved reason and the purchase details, marked as untrusted data. It returns approve or reject with a one-sentence reason for the ledger. A missing verdict or an unreachable API counts as a rejection. You can overrule a refusal with Pay anyway, which is an owner-only action and never an agent tool.
  • One tool contract (src/wallet/tools.ts): zod schemas and descriptions shared by the built-in agent and the MCP server. The descriptions carry the planning rules: read the history first, cite evidence, add a buffer, ask instead of working around a refusal. The wallet rejects reasons too short to check.
  • MCP: the official TypeScript SDK, with a remote Streamable HTTP endpoint and a stdio server. The stdio server holds no PayPal keys. It forwards calls to the wallet's agent API with a bearer token.
  • Server and app: Hono on Node 22, with a plain-JavaScript web app (no build step). It has a balance meter, editable request cards, a ledger with a reason on every row, an agent registry and the demo chat.
  • Notices: ntfy push or a webhook, with signed 24-hour Approve and Decline links that work without the owner password.
  • Tests and checks: 153 offline tests (npm test) against a local PayPal simulator that enforces the same limits. npm run sandbox-check tests hold behavior against the real sandbox. npm run purpose-eval runs the purpose check over 28 cases, including prompt injection and mislabeled listings, and fails if a purchase that should be refused gets through.
  • Hosting: a Dockerfile and a Render Blueprint with a persistent disk for SQLite. The server refuses to start on a public URL without an owner password.

Challenges I ran into

  • Partial captures can't be voided. I planned to void the unspent part of a hold at the end of the week. The sandbox check showed PayPal refuses (PREVIOUSLY_CAPTURED). Close-out now voids untouched holds immediately and marks partly captured ones as lapsing, and the ledger tells you the leftover comes back when the hold expires.
  • Approval has to mean approval. Simply visiting the PayPal return URL must not open a budget. Only a successful authorization of the order creates spendable money. A request declined midway voids its hold.
  • Keeping the purpose check independent. If the checker reads the same store page as the agent, a page that fools the agent can fool the checker too. So it sees only the approved reason and the purchase details, treats purchase text as data, and refuses if it's unsure.
  • Concurrent spends. Two purchases could each see enough money left. Serializing money changes in single transactions fixed that, and PayPal's MAX_CAPTURE_AMOUNT_EXCEEDED backs it up.
  • Several holds per budget. Top-ups create new holds, so a purchase has to capture from the hold that funds its line. If one capture in a multi-hold purchase fails, the earlier ones are refunded.
  • No INR. PayPal returned CURRENCY_NOT_SUPPORTED for rupees, so everything runs in USD.
  • Refusals the agent can use. A bare "declined" leaves an agent guessing. Each refusal names the rule, the amount left and the next step, and that's what got the agent to ask for a top-up instead of trying another line.

Accomplishments that I'm proud of

  • The full flow runs on the real PayPal sandbox: budget, approval, partial capture, refusal, a top-up as a second hold, and a second capture.
  • When the gift had no line, the agent asked instead of borrowing from groceries.
  • Every dollar in the ledger has a reason, including the refused purchases.
  • The money rules live in one place, so the built-in agent and any outside MCP agent are held to exactly the same rules.
  • It runs with no keys at all. A clearly labelled "Simulated checkout" stands in for PayPal, so anyone can try it in a minute.

What I learned

  • Authorization holds are a natural budget primitive. Approving reserves the money, captures spend it, and expiry releases it. Their edge cases (the honor period, no void after a partial capture, the capture ceiling) shape the product, so test them on day one.
  • Agents follow guardrails better when a refusal explains itself and offers a legitimate next step.
  • Limiting purpose takes a second, independent judgment. Amount limits alone can't tell dog food from headphones charged to the dog-food line.
  • Money rules belong in server code, not prompts. That's what makes it safe to let an outside agent connect.

What's next for Remit

  • Accepting AP2 mandates, so Remit enforces what they record
  • Paying real merchants that accept PayPal, instead of a simulated store checkout
  • Recurring budgets that the agent re-plans from each week's recap
  • An API from PayPal to release the uncaptured remainder of a partly captured hold, which would make close-out instant

Built With

Share this project:

Updates

Submission history