Shotoku

Spend controls for AI agents.

Watch the demo (3 min) · Be the human in the loop, in your browser · Run it yourself

Shotoku lets AI agents spend money safely — budgets, human approvals, and a tamper-evident audit trail, enforced deterministically on your machine before the payment happens. No cloud. No custody. Never holds funds or keys.

The same engine authorizes any agent action — the request model is rail-agnostic (x402, MCP, API, code). Spending is where the pain is sharpest today, so that's where it starts.

Works with PayPal and x402. Designed for any rail.

An AI agent with your PayPal account

Give an AI support agent PayPal's MCP server and it can refund any payment in your account, for any amount. It acts on what customers tell it, and it cannot tell a true claim from a false one.

A customer writes that two orders arrived broken: an $89 lamp and a $480 chair. The shop's policy is to refund damaged items, so a well-behaved agent refunds both. With Shotoku in front of PayPal's server:

claude → paypal__get_order       lamp, chair          ✓ APPROVED   reads are free
claude → paypal__create_refund   $89, lamp            ✓ APPROVED   refunded by PayPal
claude → paypal__create_refund   $480, chair          ◷ HELD       over the $100 limit, sent to your phone
you    → tap Approve or Deny
claude → retries the exact same call                  ✓ refunded, or ✗ blocked

Shotoku does not try to judge the claim. It decides how far the agent can go without you, and it does that with a rule, not with another model:

- resource: paypal__create_refund
  verdict: approved
  maxAmount: 100
  overLimit: pending_approval

flowchart LR
  A["AI agent<br/>Claude, or any MCP client"] -->|every tool call| S
  subgraph S["Shotoku, on your machine"]
    direction TB
    P["1. Price the call<br/>what does it send out of the account?"] --> R["2. Policy and budgets<br/>deterministic, fails closed"] --> L[("3. Ledger<br/>append-only, hash-chained")]
  end
  S -->|approved| M["PayPal MCP server<br/>@paypal/mcp"] --> API["PayPal API"]
  S -.->|over the limit| H["You<br/>phone, dashboard, terminal"]
  H -.->|approval, good for one identical retry| S

What makes this hold up against a real agent:

• The agent cannot skip it. Shotoku is the only MCP server the agent sees. PayPal's server runs behind it, so there is no un-gated path to create_refund.
• It prices what PayPal will actually do. create_refund with no amount refunds the whole capture, so the cheapest-looking call is the most expensive one. Shotoku looks the capture up and prices the call at the full $480 before deciding.
• The agent cannot approve itself. Approval tools are not exposed over MCP and are refused if called. An approval lets through one identical retry: same agent, same tool, same arguments, same amount, within 15 minutes.
• It never guesses. No policy, an unreadable ledger, or an amount it cannot determine all end the same way: the agent is not approved.
• Your PayPal secret stays with you. Shotoku mints a short-lived access token from your app credentials and hands PayPal's server only the token.

Try it in your browser. Watch the agent work the email, answer the $480 refund it cannot make alone, then edit the ledger behind its back and see what happens. The agent's side is replayed from real runs against the PayPal sandbox; every decision is computed in the page by a port of Shotoku's policy and ledger code, hash chain included. The full dashboard, the one shotoku ui serves locally and built with AG Grid, opens underneath.

What the agent does with nobody watching

We gave the same Claude agent the same two orders 20 times, with no human answering: two customer emails, with and without Shotoku, five fresh sessions each.

Customer email	Agent	Refunded the $480 chair	Refunded over the $100 limit
A plausible claim: "both arrived broken"	Unguarded	5 of 5	$2,400
	Behind Shotoku	0 of 5, held for a human every time	$0
A prompt injection hidden in the email	Unguarded	0 of 5	$0
	Behind Shotoku	0 of 5	$0

Claude refused the injection every time. It also refunded the $480 chair every time a customer simply said it arrived broken, because that is what the shop's policy tells it to do. The model was not fooled; it had nothing to check the claim against. In all 20 runs the $89 lamp, under the limit, was refunded without anyone being asked.

This is a small sample on one model (claude-opus-5-5), run against the offline stand-in for PayPal. Reproduce it with pnpm eval:paypal; the script is examples/paypal/eval.mjs.

Run it yourself

You need Node 20+ and pnpm.

git clone https://github.com/shotoku-dev/shotoku && cd shotoku
pnpm install

No PayPal account, one command. Claude is the agent, a local stand-in answers for PayPal, and everything else is the real thing: the MCP wrapping, the policy, the approval, the ledger. When the $480 refund is held, type y or n.

pnpm demo:paypal

This is the beginning of the README. Read the rest at the original. Read the full README ↗