io.github.lonniev/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 <slug>-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.
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. 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 <slug>_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 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), so over STDIO a paid tool is refused. Exercise paid tools against a deployed instance.

Deploy on Prefect Horizon

The hosting platform is Prefect Horizon (FastMCP is the runtime/framework the server is built on).

1. Push to GitHub
2. Connect the repo on Prefect Horizon
3. Set environment variables:
   • TOLLBOOTH_NOSTR_OPERATOR_NSEC — Nostr key for identity bootstrap (the only env var the operator needs; the Neon database URL arrives from your Authority over Nostr, the relay set comes from the shared dpyc-community registry, and all other secrets are delivered via Secure Courier credential templates)

Horizon reads the entrypoint and dependencies from fastmcp.json.

Heads-up for operators with long-running tools. By default, claim-check / async jobs run in-memory (async_jobs.backend: "memory (default)"), which means they do not survive a Horizon recycle (durable_across_recycles: false). That's fine for this reference sample, which has no long-runners — but if you add a tool that defers work to a background job, pin the tollbooth-dpyc [modal] extra, spread LONGRUNNER_CREDENTIAL_FIELDS into your operator credential template, and deliver the durable-executor secrets (modal_token_id / modal_token_secret / modal_app_name) via Secure Courier so jobs settle across redeploys. Check your live state anytime with service_status.async_jobs.

Run tests

pip install -e ".[dev]"
pytest -v

Tool Reference

The three weather tools are this operator's own; the rest come from register_standard_tools() and include identity (weather_request_npub_proof, weather_receive_npub_proof), Secure Courier, pricing, coupons, and notarization tools. weather_get_operator_onboarding_status reports what is still missing.

DPYC Ecosystem

Core

• tollbooth-dpyc — Python SDK (vault, auth, pricing, Lightning, Nostr identity)
• dpyc-community — Governance registry: membership, advisories, threat model
• dpyc-oracle — Community concierge (free onboarding + member lookup)
• tollbooth-authority — Certification backbone (Schnorr-signed certificates)
• tollbooth-sample — Sample Operator (this canonical template)
• tollbooth-pricing-studio — iOS pricing-model editor / operator console

Operators

• cypher-mcp — Monetized graph answers: named Cypher templates over Neo4j/AuraDB
• schwab-mcp — Charles Schwab brokerage data
• thebrain-mcp — TheBrain personal knowledge graph
• excalibur-mcp — X/Twitter posting
• taxsort-mcp — Tax classification + Cloudflare Pages UI
• optionality-mcp — Options analytics (brokerage-data operator)
• goodearth-mcp — Climate analytics for small specialty-crop farms
• beesknees-mcp — The Bee's Knees, a monetized multiplayer race game
• roastify-mcp — Roastify coffee catalog and packaging artwork
• ChartRemotely-mcp — Puts a security on a desktop chart, by voice or tool call

Advocates & utilities

• tollbooth-oauth2-collector — OAuth2 callback handler (advocate service)
• tollbooth-shortlinks — URL shortener utility
• tollbooth-web — Shared browser SDK for operator front ends

License

Apache-2.0