tollbooth-sampletollbooth-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.paid_tool() 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 register_standard_tools().

Version: 0.2.0

The DPYC EconomyThe 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 worksHow it works

1. Pre-funded balances — Users buy credits via Bitcoin Lightning before using tools. Each tool call silently debits from their balance. No interruptions, no "please upgrade" modals.
2. Nostr keypair identity — Users are identified by a Nostr public key (npub), not an email or password. One keypair per role, managed by the user. No account creation forms.
3. UUID-keyed tool identity — Every tool is a ToolIdentity object with a deterministic UUID v5 derived from a capability name. Pricing hints come from the category field:

   Category	Pricing hint	Use case
   free	0 sats	Balance checks, status
   read	1 sat	Simple lookups
   write	5 sats	Multi-step operations
   heavy	10 sats	Expensive queries

   Actual prices are set dynamically by the operator's pricing model in Neon.
4. Rollback on failure — If the downstream API fails after a debit, credits are automatically rolled back via a compensating tranche. The user never pays for a failed call.
5. Honor Chain — The DPYC ecosystem is a voluntary community:
   • 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

website: https://tollbooth-dpyc.com