Project Tollbooth: Paywalled MCP Server

Project Tollbooth is a Python-based FastAPI application acting as a Model Context Protocol (MCP) server over Streamable HTTP. It exposes pre-computed market regime data from a local Redis cache and monetizes access with two billing paths:

1. Pay-per-call via the official x402 payment protocol (USDC on Base) — zero-friction for anonymous agents.

2. Prepaid credit packs via API keys — fast repeat access for high-frequency bots (no facilitator round-trip per call).

Core Features

1. Granular Payment Gating (fail-closed): Discovery methods (initialize, ping, tools/list, resources/list, resources/templates/list, prompts/list, notifications/*) are free and public. Everything else on POST /mcp/ is billed. Unparseable bodies and unknown methods are gated, not bypassed.

2. Official x402 V2 Integration: The async x402 SDK (PaymentMiddlewareASGI) handles the full challenge / EIP-3009 verification / settlement flow via a facilitator.

3. Prepaid Credit Ledger: Atomic Redis-backed (Lua GET+DECRBY) per-call decrement. Responses include an x-tollbooth-credits-remaining header. Invalid keys or drained balances fall through to the x402 402 challenge.

4. Free Error Pre-check: Calls for missing or stale regime data are answered free of charge — buyers never pay for "no data".

5. Batch Protection: Batches containing more than one billable call are rejected (prevents batch underpricing on per-call payment).

6. Fail-safe Configuration: Fails hard at startup on missing/invalid BASE_WALLET_ADDRESS, and on Base Mainnet without an explicit facilitator URL.

Related MCP server: ThinChain

Environment Configuration

Installation & Setup

uv venv
uv pip install -r requirements.txt

export BASE_WALLET_ADDRESS="0xYourWalletAddress"
export X402_NETWORK="eip155:84532"   # Base Sepolia for testing

# Populate the cache with schema v1.0 format (resolved canonical symbol, e.g. QQQ for NQ)
redis-cli set current_regime:QQQ '{"schema_version":"1.0","ticker":"QQQ","requested_as":"NQ","timestamp":'"$(date +%s)"',"source":"flashalpha","spot":700.81,"regime":{"gamma":"negative","volatility":"expansion","tilt":"GEX negative","consensus":"bearish_trend","gamma_flip":717.36,"distance_to_flip_pct":-2.31,"zero_dte_gex_share_pct":25.4},"exposures_usd":{"gex":-5.52e9,"dex":1.9771e10,"vex":-4.704e9,"charm":5.121e6},"volatility":{"atm_iv":30.73,"hv20":24.14,"hv60":21.72,"vrp":6.59,"put_iv_25d":46.87,"call_iv_25d":38.4,"skew_25d":8.47,"smile_ratio":1.221},"levels":{"call_wall":720.0,"put_wall":700.0,"gamma_flip_eod":717.13,"max_pain":691.0},"key_strikes":[{"strike":700.0,"net_gex_usd":-1.027e9,"call_oi":108108,"put_oi":286899}]}'

.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000

Billing Flows

A. Pay-per-call (x402)

An agent without credentials calls the tool and receives a 402 with a base64 Payment-Required challenge header (scheme exact, network CAIP-2 id, USDC asset contract, atomic amount, payTo). It retries with a signed Payment-Signature header; the SDK verifies and settles via the facilitator.

curl -i -X POST http://127.0.0.1:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_market_regime","arguments":{"ticker":"NQ"}},"id":2}'
# -> HTTP/1.1 402 Payment Required + Payment-Required header

B. Prepaid credits (API key)

Buy a pack (this endpoint is itself x402-gated at the corresponding tier price):

• Starter Pack: $25.00 USDC for 1,500 credits. Query parameter: ?tier=starter

• Growth Pack: $95.00 USDC for 7,000 credits. Query parameter: ?tier=growth

• Pro Pack: $250.00 USDC for 25,000 credits. Query parameter: ?tier=pro

• Standard Pack: $150.00 USDC for 10,000 credits. Query parameter: ?tier=standard (or omit)

# Example: Purchase the Starter Pack
curl -i -X POST http://127.0.0.1:8000/credits/purchase?tier=starter
# -> 402 challenge at starter price ($25 USDC); pay via x402 client to receive:
# {"api_key": "tb_...", "credits": 1500, "price_paid_atomic_usdc": 25000000}

Then call the tool with the key — no payment round-trip, balance returned per response:

curl -i -X POST http://127.0.0.1:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer tb_yourkey..." \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_market_regime","arguments":{"ticker":"NQ"}},"id":2}'
# -> 200 OK + x-tollbooth-credits-remaining: 9999

Check balance (free):

curl -s http://127.0.0.1:8000/credits/balance -H "Authorization: Bearer tb_yourkey..."

Free discovery (no payment, no key)

curl -i -X POST http://127.0.0.1:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Testing

.venv/bin/python test_server.py

Covers: free discovery routes, 402 challenge schema, free-error pre-check, multi-paid batch rejection, gated credit purchase, unknown-key fall-through, and (when local Redis is running) funded-key decrement + drained-key fall-through.

Not yet covered: a real end-to-end paid call (signed Payment-Signature → verify → settle) — run one on Base Sepolia with a funded key before going to Mainnet.

Regulatory and Licensing Compliance