llms.txt
Compare with other sites' llms.txt files →# Shotoku
> Local-first spend controls for AI agents.
Before an agent spends money — an x402 payment, a paid API call, a purchase — Shotoku evaluates the request against budgets and policy, applies limits or human approval, and records the decision locally. Deterministic. No custody, ever. Nothing leaves the machine.
The same engine authorizes any agent action — MCP tools, code execution, email — because the request model is rail-agnostic. Spending is where the pain is sharpest today, so that is where it starts.
Last updated: 2026-11-06
---
## What Shotoku is
Shotoku is spend controls for AI agents. It authorizes payments; it never moves them. Not a wallet, not a payment processor, not a custody provider.
Before an agent acts, call `authorize()`. Shotoku reads your policy file and the local ledger (for rolling budget totals), evaluates the request, writes the decision, and returns a verdict with structured reasons. If the policy file is missing or the request is malformed, Shotoku denies — it never defaults to approved.
Three outcomes are possible:
- **approved** — the action passed all policy checks. The agent can proceed.
- **denied** — a policy rule blocked the action. The agent should stop.
- **pending_approval** — no rule automatically decided this. A human must approve or deny via `shotoku approve <id>`.
---
## Key concepts
### AI agent authorization
AI agent authorization is the practice of requiring an explicit policy check before an autonomous agent takes an action — spending money, calling an API, executing code, sending a message, or using a tool. Without authorization, agents act on behalf of users with no record, no limits, and no approval step.
Shotoku implements this as a local-first gate: your policy lives on your machine, evaluation happens on your machine, and decisions are stored on your machine. Nothing is sent to a remote service.
### AI agent approval workflow
When an agent requests an action that no rule automatically approves, Shotoku records it as `pending_approval` and stops. A human reviews it with `shotoku status`, approves with `shotoku approve <id>`, or denies with `shotoku deny <id>` -- or answers in the TUI (`shotoku tui`), the local dashboard (`shotoku ui`), or with a tap on their phone (`shotoku telegram`). The answer is appended to the ledger with the channel it came through, and the agent can re-run.
### Hash-chained audit log for AI agents
Every decision Shotoku records includes an integrity block linking it to the hash of the previous entry. This makes the ledger tamper-evident: altering a past record breaks every hash that follows it. The ledger is a plain JSONL file — one JSON object per line — readable in any text editor. `shotoku snapshot verify` checks it against a signed snapshot.
### x402 authorization
x402 is an HTTP payment protocol (HTTP 402 Payment Required) for agent-to-service micropayments, settled in stablecoins. Shotoku authorizes the payment intent before execution: when an agent encounters a 402 response, it calls `authorize()` with `action: "purchase"` and `rail: "x402"` before signing. If denied or pending, the payment never fires.
---
## Core API
### authorize(request, options)
```typescript
import { authorize } from "@shotoku/core";
const response = await authorize(
{
actor: "agent-001",
action: "api_call",
resource: "api.openai.com",
amount: 0.04,
},
{
policyPath: "./policy.yaml",
ledgerPath: "./data/decisions.jsonl",
},
);
if (response.approved) {
await callOpenAI(prompt);
}
```
### AuthorizeRequest
```typescript
interface AuthorizeRequest {
readonly actor: string; // agent name or ID
readonly action: AgentAction; // what the agent wants to do
readonly resource: string; // target domain or service
readonly rail?: ExecutionRail; // optional: x402 | mcp | api | code | custom
readonly amount?: number; // optional: USD cost of the action
readonly context?: Record<string, unknown>; // optional: extra fields recorded with the decision
}
```
### AuthorizeResponse
```typescript
interface AuthorizeResponse {
readonly approved: boolean;
readonly status: "approved" | "denied" | "pending_approval";
readonly reasons: readonly ReasonItem[];
readonly explanation: Explanation;
readonly decisionId: string; // e.g. dec_abc123
readonly timestamp: string; // ISO 8601
}
```
### AgentAction
```
purchase | api_call | execute_code | send_email | mcp_tool | custom
```
### ExecutionRail
```
x402 | mcp | api | code | custom
```
---
## Policy format
A policy file is a YAML file on your machine. Rules are evaluated top-to-bottom — the first match wins. Unknown fields are rejected to prevent typos from silently weakening authorization.
```yaml
defaultVerdict: pending_approval
rules:
- resource: "api.openai.com"
actions: ["api_call"]
verdict: approved
maxAmount: 5.00
maxDailyAmount: 50.00
- resource: "api.anthropic.com"
actions: ["api_call"]
verdict: approved
maxAmount: 2.00
maxDailyAmount: 20.00
- resource: "*"
actions: ["purchase"]
verdict: denied
```
`maxDailyAmount` is checked against a rolling 24-hour window per actor+resource pair, computed from the local ledger.
Over a rule's limit, a request is denied, or held for a human when the rule sets `overLimit: pending_approval`. A request with no amount against a rule with a limit is held for a human, never counted as zero. `budgets` cap what one agent spends per day across every resource; over a budget is always a denial, even after a human approves.
```yaml
rules:
- resource: paypal__create_refund
verdict: approved
maxAmount: 100
maxDailyAmount: 1000
overLimit: pending_approval
budgets:
- actor: support-agent
maxDailyAmount: 1000
```
A rule may also carry an optional `actor` pattern (`*` wildcard, e.g. `actor: team-*`) to scope it
to specific agents. Omit it and the rule matches every agent.
---
## CLI commands
```
shotoku init # scaffold policy.yaml and data/ directory
shotoku authorize --actor --action --resource [--amount]
shotoku status # pending approvals, and grants awaiting use
shotoku where # which policy and ledger resolve here, and why
shotoku approve <decisionId> # approve a pending decision
shotoku deny <decisionId> # deny a pending decision
shotoku history [--actor] [--since] [--status]
shotoku decision <id> # show full decision detail
shotoku snapshot create # sign a snapshot of policy + ledger state
shotoku snapshot verify --snapshot # verify a snapshot against the ledger
shotoku tui # interactive approval queue
shotoku ui # local dashboard on 127.0.0.1: approvals, budgets, history
shotoku telegram # approve or deny pending decisions from your phone
```
Exit codes: `0` if approved, `1` if denied or pending.
---
## MCP server
Shotoku exposes an MCP (Model Context Protocol) server so agent hosts — Claude, Cursor, Windsurf — can call authorization tools inline, without custom integration code.
```json
{
"mcpServers": {
"shotoku": {
"command": "node",
"args": ["/path/to/shotoku/mcp/dist/index.js"],
"env": {
"SHOTOKU_POLICY": "./policy.yaml",
"SHOTOKU_LEDGER": "./data/decisions.jsonl"
}
}
}
}
```
MCP tools exposed by default: `authorize_action`, `get_decision`, `get_pending_approvals`.
`approve_decision` and `deny_decision` exist but are withheld and refused unless
SHOTOKU_MCP_ALLOW_APPROVALS=1, because an agent must not approve its own decisions.
## Wrapping other MCP servers
Set SHOTOKU_MCP_UPSTREAMS to a file containing an `mcpServers` object (the same shape agent
hosts use). Shotoku connects to those servers and re-exposes each of their tools as
`<server>__<tool>`, gating every call. Remove the wrapped servers from the host config, or
the agent keeps a direct route around the gate.
The wrapped tool name IS the policy `resource`:
```yaml
rules:
- resource: obsidian__get_*
verdict: approved
- resource: obsidian__delete_*
verdict: pending_approval
defaultVerdict: pending_approval
```
Wrapped calls are recorded as `action: mcp_tool` on the `mcp` rail. Argument names are
recorded; argument values never are.
A wrapped call has no amount of its own. An upstream entry with `"pricing": "paypal"` prices
PayPal's MCP server (`@paypal/mcp`): `create_refund` at its amount, or at the full capture
when it has none; `accept_dispute_claim` at the disputed amount; every other tool at $0.
Given `PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET` in that entry's env, Shotoku mints the
PayPal access token at startup and passes the upstream only the token.
## Approvals
A human approving a pending decision creates a one-shot grant. The next call matching that
exact request -- same actor, action, rail, resource, amount and arguments -- is approved,
and the grant is spent. A second identical call is pending again: approving an action is not
approving it permanently, which is what policy rules are for. Grants expire after
`grantTtlSeconds`, default 900.
Approve out-of-band with `shotoku approve <id>`, the TUI, the dashboard (`shotoku ui`), or
your phone (`shotoku telegram`) -- never from the agent.
## Where files live
Resolution is identical in every Shotoku process, highest priority first:
1. `--policy` / `--ledger` flags, or SHOTOKU_POLICY / SHOTOKU_LEDGER
2. a `shotoku.config.json` found by walking up from the working directory
3. an existing `./data/decisions.jsonl` beside the working directory
4. `$SHOTOKU_HOME`, otherwise `~/.shotoku`
`shotoku where` prints the resolved paths and what decided each one.
`authorize_action` takes `action`, `resource`, and optionally `amount` and `context`. It does
NOT take an `actor`: identity comes from the connected MCP client, which announces its name
during the initialize handshake, so the agent cannot choose the name its own decision is
recorded under. Override it per server with `SHOTOKU_MCP_ACTOR`.
---
## What Shotoku is not
- Not a wallet. Shotoku does not hold funds.
- Not a payment processor. It does not move money.
- Not a custody provider. It never touches private keys.
- Not a cloud service. The authorization path requires no network.
- Not an enterprise compliance suite. It is built for agent developers.
---
## Documentation
- [Quickstart](https://shotoku.dev/docs/quickstart): Install to first decision in five minutes
- [API reference](https://shotoku.dev/docs/api): authorize(), types, request/response shape
- [Policies](https://shotoku.dev/docs/policies): Policy YAML format, rules, limits, wildcards
- [CLI reference](https://shotoku.dev/docs/cli): Every command, flag, and exit code
- [MCP server](https://shotoku.dev/docs/mcp): Connect Shotoku to Claude, Cursor, and any MCP client
- [x402](https://shotoku.dev/docs/x402): Authorize HTTP 402 payment intents before they execute
- [PayPal](https://shotoku.dev/docs/paypal): Put PayPal's MCP server behind Shotoku, with priced refunds and disputes
- [Dashboard](https://shotoku.dev/docs/dashboard): Local dashboard for approvals, budgets and history
- [Phone](https://shotoku.dev/docs/phone): Approve or deny from Telegram
- [TUI](https://shotoku.dev/docs/tui): Interactive terminal UI for reviewing pending approvals
- [Snapshots](https://shotoku.dev/docs/snapshots): Sign and verify policy and ledger state
## Blog
- [How to set a hard spending limit on an AI agent](https://shotoku.dev/blog/how-to-set-a-spending-limit-on-an-ai-agent): Per-call and daily caps enforced in code, with tested results
- [How to require human approval before an MCP tool call](https://shotoku.dev/blog/require-human-approval-mcp-tool-calls): Put a proxy in front of MCP servers so the agent can't skip the check
- [How to stop an AI agent from deleting your production database](https://shotoku.dev/blog/stop-ai-agent-deleting-production-database): Lessons from real incidents, and what a tool policy can and can't prevent
- [How to let an AI support agent issue refunds safely](https://shotoku.dev/blog/ai-support-agent-refund-limits): Dollar limits and human approval on PayPal's MCP server
- [How to stop an AI agent from emailing the wrong people](https://shotoku.dev/blog/stop-ai-agent-emailing-wrong-people): Check every recipient domain before a message is sent
- [How to prove what your AI agent did](https://shotoku.dev/blog/audit-log-for-ai-agents): Tamper tests on a hash-chained audit log, and why signed snapshots matter
- [What are spend controls for AI agents?](https://shotoku.dev/blog/what-are-spend-controls-for-ai-agents): Definition, the five core controls and how they differ from alerts and gateways
- [x402 spend controls compared](https://shotoku.dev/blog/x402-spend-controls-compared): Shotoku, AgentPay MCP, x402-cfo and PolicyLayer side by side, including where Shotoku falls short
## Source
- GitHub: https://github.com/shotoku-dev/shotoku
- npm (CLI): https://www.npmjs.com/package/shotoku-cli
- npm (core): https://www.npmjs.com/package/@shotoku/core