Tollbooth Sample MCP server

tollbooth-sample

Educational Weather Stats MCP Service — the reference implementation for building Tollbooth DPYC monetized API services with Bitcoin Lightning micropayments.

This service wraps the free Open-Meteo weather API and gates paid tool calls through the Tollbooth credit system using the @runtime.paidtool() decorator. Domain tools contain only business logic; debit, rollback, balance warnings, and constraint evaluation are handled automatically by the OperatorRuntime. Standard DPYC tools (balance, purchase, Secure Courier, Oracle, pricing, constraints) are delegated to the wheel via registerstandard_tools().

Version: 0.4.2

Build your own operator — the bootstrap-dpyc-operator skill

This repo doubles as a Claude Code plugin. The bootstrap-dpyc-operator skill turns your existing REST API, stdio MCP, or HTTP MCP into a monetized DPYC Operator MCP: it clones this template live, wraps your domain logic, and generates a deploy-ready project. You keep writing business logic — the SDK handles payments, identity, vault, audit, and pricing.

Install it in Claude Code:

/plugin marketplace add lonniev/tollbooth-sample
/plugin install bootstrap-dpyc-operator@tollbooth-dpyc

Then ask Claude to "make my API a paid DPYC operator" — the skill activates automatically by its description. It never touches your original code (it emits a sibling -mcp/ project) and reads this repo's live wheel pin on every run, so it can't go stale.

See skills/bootstrap-dpyc-operator/ for the skill and its reference guides (canonical pattern, source adapters, sessions & vaults, onboarding checklist).

The DPYC Economy

DPYC stands for Don't Pester Your Customer. It's a philosophy and protocol for API monetization that eliminates mid-session payment popups, subscription nag screens, and KYC friction.

How it works

using tools. Each tool call silently debits from their balance. No interruptions, no "please upgrade" modals.

1. Pre-funded balances — Users buy credits via Bitcoin Lightning before

(npub), not an email or password. One keypair per role, managed by the user. No account creation forms.

1. Nostr keypair identity — Users are identified by a Nostr public key

a deterministic UUID v5 derived from a capability name. Pricing hints come from the category field:

1. UUID-keyed tool identity — Every tool is a ToolIdentity object with

Actual prices are set dynamically by the operator's pricing model in Neon.

credits are automatically rolled back via a compensating tranche. The user never pays for a failed call.

1. Rollback on failure — If the downstream API fails after a debit,

by transparent, auditable economic rules, with a Certification Chain that cascades trust from the root:

1. Social Contract — The DPYC ecosystem is a voluntary community bound

• Citizens — Users who consume API services
• Operators — Developers who run MCP services (like this one)
• Authorities — Certify operators and collect a small tax on purchases
• First Curator — The root of the chain, mints the initial cert-sat supply

How Tollbooth Monetization Works

ToolIdentity and the frozen tool_id

Shortened. The full README is on GitHub.