Shotoku
Local-first spend controls for AI agents that enforce budgets, human approvals, and a tamper-evident audit trail before a payment happens.
At a Glance
Everything you need to authorize, approve, and audit agent actions on your machine. MIT-licensed core.
Engagement
Available On
Listed Nov 2026
About Shotoku
Shotoku is an open-source, MIT-licensed authorization layer for AI agent spending, built by Julius and Issa, two developers from France. It evaluates each agent action against a YAML policy on the user's own machine, then records the decision in a local ledger. The project describes itself as beta, with a stable, tested core authorization path.
What It Is
Shotoku sits between an AI agent and the thing it wants to do, such as a purchase, a paid API call, an MCP tool call, or code execution. Each request returns a structured decision: approved, denied, or pending human approval, with reasons and a decision ID. It holds no funds, stores no credentials or private keys, and never signs or settles a payment; the agent's own wallet or payment rail does the executing. It runs without an account, cloud, or telemetry.
How Policies and Approvals Work
A policy.yaml file defines rules per resource, with per-transaction limits (maxAmount), rolling 24-hour limits (maxDailyAmount), and per-agent daily budgets. A rule can use overLimit: pending_approval so small amounts pass and large ones wait for a human. If the policy is missing or invalid, the ledger cannot be trusted, or an amount is unknown, the agent is not approved. A human approval lets through one identical retry within 15 minutes, and agents cannot approve their own decisions.
Pending decisions can be answered from the terminal, a TUI, a local dashboard (shotoku ui), or Telegram buttons on a phone.
MCP Wrapping and Payment Rails
Shotoku ships an MCP server with two modes. In wrapping mode it sits in front of the MCP servers an agent already uses, exposing each tool as server__tool and deciding every call before forwarding it. Money-moving tools are priced, and PayPal's MCP server is priced out of the box, including looking up a capture so a refund with no amount is priced at the full amount. In advisory mode the agent calls authorize_action itself. The README also describes x402 payment authorization after the price is known and before the wallet signs.
Audit and Verification
Every decision and human answer is written to a local, append-only, hash-chained JSONL ledger at data/decisions.jsonl. Editing a past record breaks the chain on later reads. Signed snapshots of the policy and ledger head can be created and verified, and approved decisions can carry short-lived HMAC-signed receipts that a payment proxy or CI job verifies before executing.
Setup Path
Install the CLI with npm install -g shotoku-cli, run shotoku demo for four simulated decisions, then shotoku init and shotoku authorize to evaluate a spend. A TypeScript function, authorize, is available from @shotoku/core. The README's own comparison, run on one model against an offline PayPal stand-in, reports that an unguarded agent refunded a $480 item in 5 of 5 runs while the same agent behind Shotoku was held for a human each time; the authors call it a small sample.
Community Discussions
Be the first to start a conversation about Shotoku
Share your experience with Shotoku, ask questions, or help others learn from your insights.
Pricing
Open Source
Everything you need to authorize, approve, and audit agent actions on your machine. MIT-licensed core.
- authorize() core and policy engine
- Hash-chained decision ledger
- CLI and terminal UI
- MCP server for Claude, Cursor, and more
- x402 payment authorization
Enterprise
Governance, enforcement, and compliance for organizations where agents act at scale.
- Signed decision receipts and enforcement integration
- RBAC on approvals
- Compliance export packs (EU AI Act, SOC 2)
- SSO / SAML / SCIM
- Support SLA
Capabilities
Key Features
- Per-transaction and rolling 24-hour spend limits per vendor
- Per-agent daily budgets across all vendors
- Human approval queue with pending_approval verdicts and overLimit rules
- Approve or deny via terminal, TUI, local dashboard, or Telegram
- MCP server with wrapping mode that gates every tool call
- Built-in pricing for PayPal's MCP server
- x402 payment authorization before the wallet signs
- Append-only hash-chained local audit ledger
- Signed snapshots and HMAC-signed receipts
- Fails closed when policy or ledger is invalid
- YAML policy configuration
- Local-first with no account, cloud, or telemetry
Integrations
Demo Video

