Tollbooth Sample

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.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().

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

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.

1. 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.

1. 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:

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

1. 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.

1. Social Contract — The DPYC ecosystem is a voluntary community bound by transparent, auditable economic rules, with a Certification Chain that cascades trust from the root:

• 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

Each domain tool is registered as a ToolIdentity with a frozen `tool_id` (an opaque UUID), a capability name, a category (pricing hint), and an intent description. Mint the UUID once at the tool's birth — run capability_uuid("get_current_weather") at a REPL (or uuid.uuid4()), then paste the result as a literal constant and never change it again. Freezing the literal is what lets you rename a capability later without orphaning its pricing rows in Neon. Do not call capability_uuid(...) at runtime; the identity must live in exactly one place:

from tollbooth.tool_identity import ToolIdentity, STANDARD_IDENTITIES

from tollbooth.runtime import OperatorRuntime, register_standard_tools from tollbooth.credential_templates import CredentialTemplate, FieldSpec from tollbooth.credential_validators import validate_btcpay_creds

Frozen UUIDs — minted once at tool birth, never recomputed.

GET_CURRENT_WEATHER_UUID = "b7327eb8-92b4-5252-84e0-ba3f437a16ed" GET_WEATHER_FORECAST_UUID = "b6d0e596-3aec-5a62-980b-7875aa04d079" GET_HISTORICAL_WEATHER_UUID = "5608f3e9-44c4-5b28-9744-704af6d701f0"

1. Define domain tool identities

_DOMAIN_TOOLS = [ ToolIdentity( tool_id=GET_CURRENT_WEATHER_UUID, capability="get_current_weather", category="read", intent="Get current weather conditions", ), ToolIdentity( tool_id=GET_WEATHER_FORECAST_UUID, capability="get_weather_forecast", category="write", intent="Get weather forecast", ), ToolIdentity( tool_id=GET_HISTORICAL_WEATHER_UUID, capability="get_historical_weather", category="heavy", intent="Get historical weather data", ), ]

TOOL_REGISTRY: dict[str, ToolIdentity] = {ti.tool_id: ti for ti in _DOMAIN_TOOLS}

The @runtime.paid_tool() decorator

Every paid tool is a single decorator away from full DPYC monetization. The decorator takes the tool's frozen tool_id constant and handles debit, balance checks, constraint evaluation, rollback on failure, and low-balance warnings automatically. Your tool function contains only domain logic:

from typing import Any

from fastmcp import FastMCP from tollbooth.params import PatronNpub

mcp = FastMCP("tollbooth-sample", ...)

Create the runtime with merged standard + domain identities

runtime = OperatorRuntime( tool_registry={STANDARD_IDENTITIES, TOOL_REGISTRY}, operator_credential_template=CredentialTemplate( service="tollbooth-sample-operator", version=2, description="Operator credentials for BTCPay Lightning payments", fields={ "btcpay_host": FieldSpec(required=True, sensitive=True, ...), "btcpay_api_key": FieldSpec(required=True, sensitive=True, ...), "btcpay_store_id": FieldSpec(required=True, sensitive=True, ...), }, ), credential_validator=validate_btcpay_creds,

Connections prove the patron's npub (NIP-98 signed requests or an

OAuth holder connection) against this host.

holder_auth_url="https://tollbooth-sample.fastmcp.app", ... )

Delegate all standard DPYC tools to the wheel.

register_standard_tools returns the slug-prefixed @tool decorator —

use it for the operator's own paid tools below.

tool = register_standard_tools(mcp, "weather", runtime, ...)

Decorate each paid domain tool

@tool @runtime.paid_tool(GET_CURRENT_WEATHER_UUID) async def current( latitude: float, longitude: float, npub: PatronNpub = "", ) -> dict[str, Any]: """Get current weather conditions for a location.

Returns temperature, wind speed, and weather code from Open-Meteo. """ return await weather.get_current(latitude, longitude)

That is the complete paid tool. No manual debit calls, no try/except rollback blocks, no balance-warning plumbing. The decorator:

• Looks up the tool's pricing from the ToolIdentity registry by UUID
• Extracts npub from the function arguments for billing
• Checks that the connection proves that npub (a signed request, or an OAuth connection that holds it)
• Debits before calling your function (walking the tool's constraint chain from the pricing model)
• Rolls back automatically if your function raises an exception
• Appends a low-balance warning to the response when funds are running low

Key patterns

`register_standard_tools(mcp, "weather", runtime, …)` — Registers all standard DPYC tools (balance, purchase, payment, pricing, Secure Courier, Oracle, constraints) from the tollbooth-dpyc wheel, mounts oracle delegations under _oracle_*, and returns the slug-prefixed @tool decorator. Capture the return so you can use the same decorator for your own paid tools — every wire-exposed name on this operator then shares one slug prefix.

`validate_btcpay_creds` — Credential validator that checks BTCPay credentials at receive time, not at first use. Invalid credentials are rejected immediately during the Secure Courier exchange.

`CredentialTemplate` — Declares the operator's required secrets (BTCPay host, API key, store ID) so the Secure Courier flow can prompt for the right fields and validate them on delivery.

The npub parameter

Every paid tool must accept an npub keyword argument. It tells the runtime which patron to bill; the connection proves the caller holds it. Use the SDK's PatronNpub type so every operator describes it the same way:

from tollbooth.params import PatronNpub

npub: PatronNpub = ""

A paid tool called with an empty or invalid npub is refused (npub is required) before your function runs.

What the runtime handles under the hood

Tool call arrives

| v @runtime.paid_tool(GET_CURRENT_WEATHER_UUID) | +-- UUID lookup in tool_registry -> ToolIdentity + pricing +-- npub extraction from kwargs; the connection proves it | +-- Constraint chain from the pricing model (discounts, surge, supply caps, coupons) +-- Balance check + debit | | | insufficient --> Return error (no function call) | +-- Call your function | | | exception --> Automatic rollback, return error | +-- Append low-balance warning if needed | v Return result to caller

Constraint Engine

Constraints are dynamic pricing steps that live in the operator's pricing model: each tool's chain in the model lists the steps the ConstraintGate walks on every call, and coupons bound to the tool are added after them. Author them in Pricing Studio or with weather_set_pricing_model; nothing is switched on by environment variable.

Common constraint types (the SDK registry holds more — weather_list_constraint_types enumerates the full set live):

Use weather_check_price to preview constraint effects without spending credits — it walks exactly the chain the debit will.

Becoming an Operator

New to Tollbooth? See [GETTING-STARTED.md](GETTING-STARTED.md) for a step-by-step guide covering Nostr keypair setup, Authority enrollment, BTCPay configuration, and deploying your first monetized MCP service.

Quick Start

Local development

git clone https://github.com/lonniev/tollbooth-sample.git

cd tollbooth-sample pip install -e ".[dev]" python -m tollbooth_sample.server

This serves over STDIO. There is no development bypass: paid tools are gated exactly as in production, and the patron's npub is proven by the HTTP connection (a NIP-98 signed request or an OAuth holder bearer), s