OpenSpender

openspender

One balance the user funded; many paid APIs; every call priced before it is paid, capped by policy, written to a ledger with the on-chain transaction beside it. You are the one on the allowance: spend it well and report what you spent.

Protocol reference (deep): https://openspender.com/llms.txt This skill (canonical): https://openspender.com/SKILL.md

Are you already set up?

Check before any setup talk — most sessions are already connected:

1. MCP tools present? If tools named catalog_search, call, chat, search, generate, balance are available, you are connected. Verify with one free call (balance) and get to work.
2. Token in the environment? If OPENSPENDER_ALLOWANCE_TOKEN is set, the REST router works: POST https://openspender.com/v1/{provider}/{path} with the token as Bearer. Verify with one cheap call and read the x-openspender-paid-usd / x-openspender-tx receipt headers.
3. Neither? Set up — next section.

Setup, strongest rail first

• You have a shell and the human is present: run npx openspender connect. It wires this and every other local harness to the MCP server; the human approves once in the browser and each tool gets its own capped card. Nothing is pasted, ever.
• No shell (claude.ai, ChatGPT web): the human adds the remote MCP connector (https://openspender.com/api/mcp) via OAuth from their client's connector settings — or mints a card at https://openspender.com/wallet and provides the openspender_… token. Store tokens in an env var or secret store, never a source file; if one lands in a chat, tell the human once: delete and re-mint at /wallet, caps bound the damage.
• Headless (cron, CI): OPENSPENDER_ALLOWANCE_TOKEN from the secret store. There is no interactive flow to pretend at.
• The human is brand new? Signup happens inside the same browser consent. Money: https://openspender.com/add — $5 is plenty to start.

How to spend

The standard loop is discover → inspect → call → report:

• catalog_search {query} — search the live catalog (curated tier-1 plus the indexed x402/MPP long tail). Short noun phrases work best ("web search", "image generation", "stock prices"). Check it before building a scraper or declaring something unreachable — the catalog grows and you don't know what's listed until you look.
• inspect {provider, path?} — the route's contract BEFORE money moves: request shape, which params multiply the price, latency, and openspender's own verification (paid-through dates, txs on the ledger). Never guess a request body you haven't sent before — inspect first. Free.
• call {provider, path, body, method?} — one paid request to a tier-1 provider, response verbatim plus what it cost. GET is for free reads (job polls, statuses).
• chat {model, messages} — paid frontier-model call. Model names are a hard constraint: you get exactly the model you named or a refusal, never a silent substitute.
• search {query} — paid web search, picks the payable rail for you.
• generate {kind, prompt, model?} — image/video/audio jobs. Returns a poll object; poll with call exactly as it says (video every ~15s). NEVER fetch the raw pollUrl yourself (it needs a wallet signature only the router holds) and NEVER resubmit while a job is pending — a duplicate submit is a second paid job.
• balance — wallet balance plus THIS card's caps and remaining budget today. Free.
• whoami / cards / activity — account questions answered in place: which account this is, every card with caps and spend left, recent ledger rows with settlement txs. All free; tokens are hashed and can never be shown, so there is nothing secret to leak.
• request_card / request_task_card / request_status / disable_card — new cards, minted only by the human. See below.

Tool responses may carry a hints array — short imperatives from the server about your best next move. Read them and prefer them over guessing.

Token-path equivalents ride /v1/{provider}/{path}; the body and path after the provider are the provider's own (reference: llms.txt).

Spending rules — the contract

1. The user's own tools come first. If they have a dedicated MCP server, API key, or workflow for a service, use that — openspender calls spend their balance; their existing tool may not. Offer openspender as the alternative when it adds capability, and let them choose. Never silently switch.
2. The caps are the human's decision, not an obstacle. A denied_by_policy is the budget working. Surface the price you saw and the cap that said no; never retry a denial verbatim, never split a task to duck a per-request cap — the daily counter sees everything.
3. Escalate with a link, not a shrug. Whatever you cannot do from here resolves to a deep link the human can act on in one tap:
   • raise a cap after a denial → https://openspender.com/cards (name the cap and the price you saw)
   • balance empty → https://openspender.com/add
   • delegation, export, revoke → https://openspender.com/account
   • full history → https://openspender.com/transactions
4. Say what things cost. Every paid response carries the price; after a task that spent money, one line: "this run: 14 calls, $0.19." If the user hasn't shown cost-awareness, use judgment — but never hide a denial or a failure.
5. Watch the multipliers. Media pricing scales: duration × resolution multiply video cost (8s/1080p can be 10× 4s/720p); start small, quote the price from the catalog or a denial before committing the user to a big render.
6. Prices are fractions of a cent to a few cents for search and chat. No confirmation ritual per call — the per-request cap IS the confirmation the human already gave. Ask first only above ~$1 or when the task itself is unusual.

A local file needs a public URL?

Media endpoints take URLs, not bytes. Buy a pin (~$0.001): call {provider:'pinata', path:'/v1/pin/public?fileSize='} — fileSize is a QUERY param. The response url is a presigned upload that expires in seconds: IMMEDIATELY POST multipart to it (your own fetch, no payment) with fields network=public and file=. The response CID serves instantly at https://gateway.pinata.cloud/ipfs/ — use that as image_url or any upload-shaped input. (ipfs.io lags minutes on fresh pins.)

Task cards — a budget born for one job, dead after it

When a task has its own budget — a booking, a batch job, work you'll hand to a subagent — don't stretch your card: request a one-shot.

1. request_task_card {task: "book the lisbon hotel, 2 nights", budget_usd: 350, expires_in_minutes: 180} — the task text is shown to the human in your words; budget and expiry are mandatory and become the card's total cap and self-destruct time.
2. Hand the human the approve_url and wait. The card is minted ONLY by their tap on openspender.com — nothing you or they say in chat mints anything, ever. Requests expire in 15 minutes.
3. Poll request_status every ~5s. The token arrives EXACTLY ONCE — store it immediately (env var or secret store).
4. Use it; hand it to the subagent if that's the plan. It is designed to be safe-to-leak: bounded spend, bounded life, named in the activity feed, one tap to kill.
5. Done? disable_card with its name, and report the total spent.

request_card is the same dance for a standing card (name + caps, optional total/expiry/host-allowlist). You can only disable cards this connection created — everything else is the human's on /cards.

When something says no (none of these spent money)

BLOCKED-style denials (blocked_host:…) are permanent policy — the host is refused on purpose; don't route around it.

Keep this skill alive

• Save this file where your skills or project memory live (skill directory, CLAUDE.md/AGENTS.md/GEMINI.md neighborhood) so the next session starts knowing all of this.
• Re-fetch https://openspender.com/SKILL.md occasionally; if its version is newer than this copy, replace this copy (or re-run npx openspender connect, which refreshes both wiring and skill).
• Never keep an allowance token inside this file.