Claude Code skill for BSV micropayments. Discover, authenticate, and pay AI services with Bitcoin SV — all from natural language.
Say what you want. The skill handles the rest:
/x402 generate an image of a mountain sunset
/x402 transcribe this audio file
/x402 search twitter for AI agent discussions
/x402 upload this file to NanoStore for a year
Under the hood:
- Discovers available services from the x402agency.com agent directory
- Authenticates with BRC-31 mutual auth (automatic handshake + session caching)
- Pays with BRC-29 micropayments (automatic 402 handling, transaction creation)
- Refunds automatically — both service-failure refunds (a paid request fails) and excess refunds (you overpaid a token-priced agent) are detected and internalized to your wallet with no manual steps
The skill discovers agents from x402agency.com/.well-known/agents:
| Agent | What it does | Cost |
|---|---|---|
| Banana Agent | AI image generation (Google Nano Banana Pro) | ~$0.19/image |
| Veo Agent | AI video generation with audio (Google Veo 3.1 Fast) | ~$0.75–$1.50/clip |
| Whisper Agent | Speech-to-text transcription (Whisper Large v3 Turbo) | ~$0.0006/min |
| X Research Agent | Twitter/X search, profiles, threads, trending | ~$0.005–$0.06/req |
| 1Sat Agent | 1Sat Ordinals inscriptions (any file type) | 200–256,000 sats |
| NanoStore | File hosting with UHRP content addressing (Babbage) | ~$0.0004/MB/yr |
Third-party services like NanoStore are listed in the directory with hosted manifests — clients connect directly, no proxy.
Requires Claude Code and MetaNet Client.
/plugin marketplace add calgooon/x402
/plugin install x402@calgooon-x402
Troubleshooting: If you get a "Failed to finalize marketplace cache" error, run
/plugin, select Manage marketplaces > Add marketplace, and pastehttps://github.com/Calgooon/x402. Then run/plugin install x402@calgooon-x402.
- MetaNet Client running at
localhost:3321(download from getmetanet.com), or any BRC-100 wallet at the URL inX402_WALLET_URL - Python 3 with
requests(pip install requests)
The /x402 command is the entry point. You can use it conversationally or with specific commands:
/x402 generate a photo of a cat in a top hat
/x402 upload report.pdf to NanoStore for 1 year
/x402 search twitter for "bitcoin scaling" from the last 24 hours
/x402 transcribe meeting.wav
/x402 list # List all agents in the directory
/x402 discover banana # Show endpoints, pricing, schemas for an agent
/x402 discover nanostore # Works for third-party services too
/x402 auth GET nanostore/list # Authenticated request (no payment)
/x402 pay POST banana/generate {"prompt":"a sunset"} # Paid request
| Command | What it does |
|---|---|
/x402 list |
List all registered agents with capabilities and pricing |
/x402 discover <agent> |
Fetch the x402-info manifest — endpoints, schemas, pricing, error codes |
/x402 auth <METHOD> <agent/path> |
Make a BRC-31 authenticated request (no payment) |
/x402 pay <METHOD> <agent/path> [body] |
Make an authenticated + paid request (auto-handles 402 flow, auto-internalizes refunds) |
/x402 execute-action <json> |
Broadcast a pending action template (e.g. a 1Sat inscription) returned by pay, after you confirm |
/x402 identity |
Show your wallet's identity key |
/x402 session <url> |
Inspect a cached BRC-31 session |
Agent names (banana, nanostore, whisper, etc.) resolve automatically. Full URLs work too.
/x402 generate a photo of a cat wearing a top hat
→ discovers banana agent, pays ~9,000 sats, returns image URL
/x402 upload report.pdf to NanoStore for 1 year
→ discovers NanoStore, pays ~730 sats for 1MB/year, returns presigned upload URL
/x402 find tweets about bitcoin scaling from the last 24 hours
→ discovers x-research agent, pays ~3,000 sats, returns sorted results
/x402 transcribe meeting.wav
→ discovers whisper agent, pays based on audio length, returns text
/x402 inscribe this image as an ordinal
→ discovers 1sat-agent, pays service fee, builds script, wallet broadcasts, returns txid
/x402 <user request>
→ skill runs `list` to find matching agent by capabilities
→ skill runs `discover <agent>` to read the x402-info manifest
→ skill reads endpoint schemas, pricing, auth requirements
→ skill runs `pay POST <agent>/<endpoint> '{...}'`
→ BRC-31 handshake (automatic, cached 1 hour)
→ initial request → server returns 402 with price
→ wallet creates payment transaction
→ retry with x-bsv-payment header → server accepts, returns result
→ skill presents result to user
All payment is automatic — no confirmation prompts for typical micropayments (1–100,000 sats).
Every wallet call goes to X402_WALLET_URL (default http://localhost:3321). Set it to use a second wallet daemon, e.g. X402_WALLET_URL=http://localhost:3322.
BRC-31 sessions are cached in ~/.local/share/brc31-sessions/ as SHA256(server_url + "\n" + client_identity_key)[:16].json, and each file records the identity that opened it. A session is only reused by the wallet that opened it: when the wallet reports a different identity key, the helper handshakes afresh. Session files from versions before 1.1.1 (keyed by server URL only) are deleted on first use.
Authenticated responses include a verdict column beside the HTTP status: signed, UNSIGNED, or BAD SIGNATURE. Both auth and pay verify BRC-104 response signatures with the session's server identity, request ID, status, signed headers, and raw body, including 400/402/500 refusals. Missing or invalid signatures print a warning and make the command exit nonzero. An unverified 402 never triggers payment.
Both session entries report a clear error when no URL is supplied. To preview all cached session filenames without deleting anything or prompting:
python3 skills/x402/scripts/brc31_helpers.py session --clear-all --dry-runThen session --clear-all lists the filenames and deletes all wallets' sessions without confirmation. The registry cache is preserved. These flags also work with skills/x402/cli.py.
- 1.1.1 — Sessions keyed by (server URL, client identity key); a session opened by one wallet is never reused by another (a wallet switch on the same server previously made the server derive the BRC-29 payee key from the wrong identity). Wallet URL configurable via
X402_WALLET_URL.createActionacceptstxreturned as an index-keyed object. Addedtests/(python3 -m pytest -q).
The skill resolves short names (like banana or nanostore) to full URLs via the x402agency.com registry. Any BRC-31/BRC-29 service can be listed — including third-party services that don't serve their own discovery manifest.
The registry is cached locally for 5 minutes. Full URLs (https://...) bypass the registry entirely.
- BRC-31: Mutual HTTP authentication with identity keys and signed requests
- BRC-29: HTTP micropayments via 402 Payment Required flow
- BRC-100: MetaNet Client wallet interface (key derivation, signing, transaction creation)
MIT