schwab-mcp

Your brokerage data, conversationally. Ask your AI assistant about your positions, screen option spreads, audit today's trades against your strategy rules, and get end-of-day reports — all from natural language. The data cost? About 6 sats per session (~$0.005).

Why This Exists

The data in schwab-mcp is nothing you can't get from ThinkOrSwim, OptionAlpha, or Schwab's own web UI. What you can't get from those tools is a personal trading assistant that blends:

• Your live positions and account balances
• Real-time option chains with Greeks, IV, and OTM%
• Your trading strategy rules (credit floors, RWR targets, sector concentration limits)
• Market context (earnings calendars, VIX levels, sector rotation)
• All of the above in a single conversational turn

Ask "How would you judge my new trades for the day?" and get a structured audit against your criteria. Ask "What are three SPS candidates aligned with my strategy and balanced with my current book?" and get sector-aware, earnings-aware, IV-aware suggestions — grounded in your actual positions, not generic advice.

The AI does the synthesis. schwab-mcp provides the data bridge. You pay per-call in Bitcoin Lightning sats — no subscription, no KYC, no vendor lock-in. A full day of morning report + evening report + follow-up analysis costs about 6 sats (< $0.01).

---

Multi-tenant MCP server exposing Charles Schwab brokerage data to AI agents via FastMCP. Monetized via Tollbooth DPYC™ Lightning micropayments. Serves over Streamable HTTP with direct async httpx calls to api.schwabapi.com.

Don't Pester Your Customer™ (DPYC™) — API monetization for Entrepreneurial Bitcoin Advocates

Inspired by The Phantom Tollbooth by Norton Juster, illustrated by Jules Feiffer (1961).

Version: 0.12.2  

The DPYC™ Economy

DPYC™ stands for Don't Pester Your Customer. It is 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 (api_sats) via Bitcoin Lightning before using tools. Each tool call silently debits from their balance. No interruptions, no "please upgrade" modals. Credits expire after a tranche_lifetime window set by the operator's pricing model.

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. Poison-keyed proof -- Every paid tool call requires a dpop_token parameter carrying a poison phrase (e.g., bold-hawk-42) returned by request_npub_proof / receive_npub_proof. The calling application remembers this token and passes it on every subsequent call. The MCP stores only sha256(poison):npub in the vault -- never the raw phrase. Proofs are generated via a human-in-the-loop Secure Courier exchange: the patron consciously approves each proof request in their Nostr client. Duration is patron-chosen (up to 7 days). Proofs survive MCP restarts.

4. 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 (api_sats) are set dynamically by the operator's pricing model in Neon.

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

6. Social Contract -- 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

Tools

Brokerage (paid -- credit-gated)

All paid tools require npub and dpop_token parameters for identity verification.

Tool	Tier	Description
get_brokerage_positions	write	Portfolio positions with automatic options spread detection (bull put / bear call)
get_brokerage_balances	write	Cash, buying power, net liquidation value, day P&L
get_stock_quote	write	Real-time quotes for one or more symbols
get_market_movers	write	Top movers for a market index ($SPX, $DJI, $COMPX)
get_market_hours	write	Trading hours for equity, option, bond, future, forex markets
search_instruments	write	Search for instruments by symbol, name, or CUSIP
get_option_chain	heavy	Filtered option chain with Greeks, IV, OTM%, and OI threshold
get_price_history	heavy	Historical OHLCV candle data
get_brokerage_orders	heavy	Order history with multi-leg spread support (default 30 days)
get_brokerage_order	heavy	Single order detail by ID
get_brokerage_transactions	heavy	Transaction history -- trades, dividends, cash movements (default 30 days)
get_brokerage_transaction	heavy	Single transaction detail by ID

Free

Tool	Description
session_status	Check operator lifecycle state and readiness
service_status	Check health and configuration of this service
begin_oauth	Start OAuth2 flow -- returns Schwab authorization URL
check_oauth_status	Poll whether OAuth flow completed and session is active
get_account_numbers	List linked Schwab account numbers and hashes
request_credential_channel	Open a Secure Courier channel for credential delivery via Nostr DM
receive_credentials	Pick up credentials from the encrypted vault
forget_credentials	Delete vaulted credentials for re-delivery
update_patron_credential	Add or update a single patron credential field
delete_patron_credential	Remove a single patron credential field
get_patron_credential_fields	List stored patron credential field names
check_balance	View credit balance and usage
check_price	Preview tool cost before calling
purchase_credits	Create a Lightning invoice to buy credits
check_payment	Verify Lightning payment and credit the balance
restore_credits	Restore credits from a previously paid invoice
account_statement	View account statement summary
account_statement_infographic	Visual SVG infographic of account (1 sat)
check_authority_balance	Check operator's cert-sat balance at Authority
get_pricing_model	View the active pricing model
list_constraint_types	List available constraint types and schemas
request_npub_proof	Request poison-keyed ownership proof via Nostr DM
receive_npub_proof	Receive and cache proof; returns proof_token
get_operator_onboarding_status	Report operator configuration readiness
get_patron_onboarding_status	Report patron credential readiness
list_notarizations	List recent Bitcoin notarization records
get_notarization_proof	Generate a Merkle inclusion proof for a patron balance

All brokerage tools are read-only. No orders are placed.

Architecture

• Multi-tenant: operator delivers btcpay_host + btcpay_api_key + btcpay_store_id + app_key + secret via Secure Courier (service="schwab-operator"); each patron authenticates via OAuth2 browser flow. Sessions are keyed by npub. No Schwab credentials in env vars
• Direct httpx: thin SchwabClient wrapper with bearer auth and proactive token refresh (no third-party Schwab SDK)
• Tollbooth DPYC™: pre-funded Lightning balances, Authority-certified purchase orders, NeonVault (Postgres) for ledger persistence
• Registry discovery: OAuth2 collector URL resolved from DPYC™ registry at runtime (no OAUTH_COLLECTOR_URL env var needed)
• Credential validation: operator credentials are validated at receive time -- btcpay_host, app_key, and secret must all be present before vaulting
• Poison-keyed proof: all paid tools require a dpop_token parameter -- a poison phrase from request_npub_proof / receive_npub_proof that the calling application remembers. The MCP stores only the hash. Survives restarts; patron-chosen TTL up to 7 days. Restricted tools (operator-only) still use kind-27235 Schnorr signatures.

---

Getting Started

This guide covers the full Tollbooth onboarding path -- from generating a Nostr identity to making your first brokerage data call. It applies to both Operators (who deploy schwab-mcp) and Patrons (who consume it through Claude.ai or another MCP client).

1. Get a Nostr Identity (npub)

Every participant in the DPYC™ ecosystem is identified by a Nostr keypair -- no email, no password, no vendor lock-in.

What is an npub? It is a public key in the Nostr protocol, encoded as a bech32 string starting with npub1.... Your corresponding private key (nsec1...) stays on your device. The npub is safe to share -- it is how the system knows who you are.

How to generate one: