schwab-mcp

# schwab-mcp

![Open Positions — Options Risk Profile](assets/hero-banner.png)

**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](https://modelcontextprotocol.io/) server exposing Charles Schwab brokerage data to AI agents via [FastMCP](https://github.com/jlowin/fastmcp). Monetized via [Tollbooth DPYC](https://github.com/lonniev/tollbooth-dpyc)&trade; Lightning micropayments. Serves over **Streamable HTTP** with direct async httpx calls to `api.schwabapi.com`.

> Don't Pester Your Customer&trade; (DPYC&trade;) &mdash; API monetization for Entrepreneurial Bitcoin Advocates

*Inspired by [The Phantom Tollbooth](https://en.wikipedia.org/wiki/The_Phantom_Tollbooth) by Norton Juster, illustrated by Jules Feiffer (1961).*

**Version:** 0.12.2 &nbsp; ![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)

## The DPYC&trade; Economy

**DPYC&trade;** 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&trade; 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&trade;**: pre-funded Lightning balances, Authority-certified purchase orders, NeonVault (Postgres) for ledger persistence
- **Registry discovery**: OAuth2 collector URL resolved from DPYC&trade; 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&trade; 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](https://nostr.com/), 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:**

1. Install [Oxcart](https://github.com/nickkawai/Oxcart)