Integrations

Gateway URL (any language)

curl -H "X-Spendctl-Agent: researcher" "http://127.0.0.1:8402/https://api.example.com/report?id=42"

Or send the target in X-Spendctl-Target and request http://127.0.0.1:8402/. spendctl adds x-spendctl-attempt, x-spendctl-decision and x-spendctl-amount to responses.

wrapFetch (TypeScript / JavaScript)

import { wrapFetch, readRefusal, AgentClient } from "@spendctl/client";

const pay = wrapFetch({ agent: "researcher" });
const res = await pay("https://api.example.com/report");
const refusal = await readRefusal(res);   // undefined when paid or free
const budget = await new AgentClient({ agent: "researcher" }).budget();

Python (spendctl-sdk)

pip install "spendctl-sdk[httpx]"   # or [requests]; the package itself has no dependencies

from spendctl_sdk import httpx_client, read_refusal, AgentClient

with httpx_client(agent="researcher") as http:      # reads SPENDCTL_URL / SPENDCTL_AGENT by default
    res = http.get("https://api.example.com/report")
    refusal = read_refusal(res)                     # None when paid or free
budget = AgentClient(agent="researcher").budget()

requests_session(agent=...) does the same for requests; pay(url, agent=...) needs no HTTP library at all. The import name is spendctl_sdk. Source and the full API: github.com/miraistudio/spendctl-sdk.

MCP

claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcp

Tools: pay (fetch a URL that may cost money), check_budget, list_receipts. The MCP server is a thin client: no keys, no approvals.

Claude Code and Cursor plugins

The public SDK repository is a plugin marketplace with two plugins: spendctl wraps the MCP server above (it asks for the agent name and the sidecar URL on install) and adds a skill that tells the agent how to handle budgets, refusals and approvals; spendctl-sandbox connects to the sandbox instead, with nothing to run.

claude plugin marketplace add miraistudio/spendctl-sdk
claude plugin install spendctl@spendctl            # against the sidecar you run
claude plugin install spendctl-sandbox@spendctl    # the hosted sandbox, no install

In Cursor, import https://github.com/miraistudio/spendctl-sdk as a marketplace (Dashboard → Plugins & MCPs → Add Marketplace → Import from Repo) and install either plugin; the spendctl plugin takes SPENDCTL_AGENT and SPENDCTL_URL as variables. Both plugins are Apache-2.0: github.com/miraistudio/spendctl-sdk/tree/main/plugins.

HTTP_PROXY

spendctl run --agent researcher -- python agent.py

Sets HTTP_PROXY (with the agent name in the proxy credentials). Plain http:// requests are governed; https:// is tunnelled without inspection, so paid HTTPS APIs should use the gateway URL.

Framework examples

• Claude Agent SDK — pass the MCP server through mcpServers.
• OpenAI Agents SDK — a function tool over wrapFetch.
• LangGraph — tool() + createReactAgent over wrapFetch.

Runnable examples for these three are planned for the public client SDK repository, github.com/miraistudio/spendctl-sdk.

Agent → agent chains

spendctl reads and forwards W3C baggage entries spend.root, spend.parent, spend.depth. If your agent is itself a paid service, propagate incoming baggage to outgoing calls (OpenTelemetry does this for you). spendctl trace <attempt-id> prints the tree.