spendctl SDK
Open-source clients for the spendctl sidecar.
spendctl is the spend-policy control plane for AI agents: budgets, approvals, receipts and chain tracing across every wallet and every HTTP 402 protocol — enforced in a sidecar you run, never by holding your keys or funds.
This repository holds the thin clients that talk to that sidecar. They are Apache-2.0 and expose only the wire protocol. The sidecar, CLI and MCP server themselves are proprietary and ship on npm as spendctl; their docs live at https://spendctl.dev/docs/.
Status: @spendctl/client is on npm (npm i @spendctl/client); spendctl-sdk for Python is on PyPI (pip install spendctl-sdk). The sidecar they talk to ships as spendctl on npm; the hosted control plane is in private beta (https://spendctl.dev).
Packages
| Package | Language | Registry | Status |
|---|
@spendctl/client | TypeScript, zero dependencies | npm | available |
spendctl-sdk | Python 3.10+, zero dependencies (optional httpx / requests integrations); import name spendctl_sdk | PyPI | available |
spendctl-sandbox, spendctl | Claude Code and Cursor plugins (MCP config + skill) | this repo is the marketplace | available |
Plugins
The repository is also a plugin marketplace for Claude Code and Cursor (plugins/): spendctl-sandbox connects to the login-free sandbox, spendctl to the sidecar you run.
claude plugin marketplace add miraistudio/spendctl-sdk
claude plugin install spendctl-sandbox@spendctl
How it fits together
- Run the spendctl sidecar next to your agents:
npx spendctl init && npx spendctl start.
- Point agents at it — the gateway URL from any language, this
fetch wrapper, or the MCP server.
- Every HTTP 402 is checked against your policy, held for approval above your thresholds, and written to the ledger.
import { wrapFetch, readRefusal } from "@spendctl/client";
const pay = wrapFetch({ agent: "researcher" }); // reads SPENDCTL_URL / SPENDCTL_AGENT by default
const res = await pay("https://api.example.com/paid");
const refusal = await readRefusal(res); // undefined when paid; otherwise why spendctl refused or is waiting for a human
from spendctl_sdk import httpx_client, read_refusal
with httpx_client(agent="researcher") as http: # same env vars; requests_session() and pay() also exist
res = http.get("https://api.example.com/paid")
refusal = read_refusal(res) # None when paid
Signing happens in the sidecar you run, against a wallet you own — a Coinbase CDP server wallet or your own key. spendctl never holds keys or funds.
Wire protocol
The clients are small because the protocol is small. Anyone can write one in another language from this table.
Gateway (agent → sidecar). Send the request you would have sent to the seller to the sidecar's base URL (default http://127.0.0.1:8402/) and put the real destination in a header.
| Header | Direction | Meaning |
|---|
x-spendctl-target | request | Absolute URL of the seller endpoint |
x-spendctl-agent | request | Agent name as defined in spendctl.yaml |
x-spendctl-token | request | Per-agent token, when the sidecar runs with agentAuth: token |
x-spendctl-approval | request | Approval id to attach to a retry after a human approved |
x-spendctl-decision | response | Outcome of the attempt: settled, denied, pending_approval, failed, expired or dry-run |
x-spendctl-attempt | response | Ledger id of the attempt |
x-spendctl-amount | response | Amount paid, formatted in USD |
When the sidecar refuses, needs approval, or is in dry-run it answers 402 with a JSON body { error, message, attempt?, decision?, amount?, approval?, reasons? } where error is one of spendctl_denied, spendctl_approval_required, spendctl_dry_run. A paid response is the seller's response with the x-spendctl-* headers added.
Agent API (read-only, identified by x-spendctl-agent / x-spendctl-token). GET /_spendctl/agent/budget, GET /_spendctl/agent/receipts?limit=, GET /_spendctl/agent/approvals/:id.
Admin API (Authorization: Bearer <admin token> from .spendctl/admin.token). GET /_spendctl/admin/pending, POST /_spendctl/admin/approvals/:id/approve|deny, GET /_spendctl/admin/ledger, GET /_spendctl/admin/export?format=csv|json, GET /_spendctl/admin/trace/:id, GET /_spendctl/admin/summary, POST /_spendctl/admin/ledger/:id/resolve.
The protocol is versioned with the sidecar; this README tracks sidecar v0.1.
Contributing and security
Issues and pull requests are welcome here — see CONTRIBUTING.md. Contributions are accepted under Apache-2.0 (inbound = outbound); no CLA.
Security reports for the clients or the sidecar: [email protected], not a public issue. See SECURITY.md.
Licence and trademark
Code in this repository is licensed under the Apache License 2.0. See NOTICE.
"spendctl" and the spendctl logo are trademarks of Mirai Studio, Inc. The licence does not grant permission to use the name for forks or derived services; call yours something else and say it is compatible with spendctl.
© Mirai Studio, Inc. (株式会社みらいスタジオ), Tokyo.
