Skip to main content
BoltzPay is split into six packages with strict dependency boundaries. Dependencies flow inward: outer packages depend on inner ones, never the reverse. The core domain has zero external dependencies.

​
Package Dependency Graph

​
Package Responsibilities

​
@boltzpay/core (green)

The sovereign domain layer. Contains value objects, domain errors, chain types, and protocol interfaces. Zero runtime dependencies. Everything here is pure TypeScript with no imports from external packages.
  • Money — immutable value object for amounts (BigInt-based, currency-aware)
  • ProtocolAdapter — interface that x402, L402, and MPP adapters implement for one-shot payments
  • SessionAdapter and ManagedSession — interfaces for session-based payment protocols (payment channels, streaming)
  • ChainSelection — multi-chain negotiation logic (EVM vs SVM)
  • Domain errors — NegativeMoneyError, NoCompatibleChainError, etc.

​
@boltzpay/protocols (blue)

Protocol adapters that know how to detect, quote, sign, and deliver payments for each supported protocol. Currently ships with:
  • X402Adapter — handles x402 V1, V2, and V1-in-V2 hybrid formats. Uses Coinbase CDP for EIP-3009 signing.
  • L402Adapter — handles L402 (Lightning). Uses NWC for invoice payment.
  • MppAdapter — handles MPP (Micropayment Protocol). Uses mppx for one-shot charges (Tempo, Stripe) and session-based streaming via payment channels.
  • MppSessionManager — implements SessionAdapter for persistent payment channel sessions with streaming support.
Each adapter implements a shared interface: ProtocolAdapter for one-shot payments (detect(), quote(), execute()), and SessionAdapter for session-based protocols alongside it.

​
@boltzpay/sdk (blue)

The composition root. This is what users import. It wires together core domain logic and protocol adapters into the BoltzPay class. Exposes fetch(), quote(), diagnose(), discover(), openSession(), wrapMcpClient(), getBudget(), getHistory(), getCapabilities(), getWalletStatus(), and getBalances(). Registry integration via discover() queries the live BoltzPay Registry API for endpoint metadata, scores, and protocol information.

​
@boltzpay/cli (purple)

A terminal interface that wraps the SDK. Commands: quote, fetch, discover, diagnose, budget, history, wallet, demo. The discover command supports --protocol, --min-score, and --query flags for filtered searches. Also serves as a bridge for Python agents (LangChain, CrewAI) via subprocess calls.

​
@boltzpay/mcp (purple)

An MCP server exposing 7 tools for Claude Desktop and other MCP-compatible clients. Install with npx @boltzpay/mcp and point Claude Desktop at it. The discover tool supports protocol, minScore, and query filters.

​
@boltzpay/ai-sdk (purple)

A Vercel AI SDK integration exposing 7 tools via boltzpayTools(). Use with generateText() or streamText() from the Vercel AI SDK.

​
External Systems (gray)

  • Coinbase CDP — wallet management and EIP-3009 signing for x402 payments (USDC on Base)
  • x402 Facilitator — on-chain payment verification and settlement
  • Lightning / NWC — Nostr Wallet Connect for L402 invoice payments
  • Tempo Network — payment channel network for MPP streaming sessions
  • Stripe MPP — Stripe integration for MPP one-shot payments
  • BoltzPay Registry — live API endpoint registry at status.boltzpay.ai (scores, health, protocol metadata)

​
Design Principles

  • Inward dependencies — CLI, MCP, and AI-SDK depend on SDK. SDK depends on Protocols and Core. Core depends on nothing. No circular dependencies.
  • Protocol-agnostic core — Money, Budget, and BudgetTracker know nothing about x402, L402, or MPP. Adding a new protocol means adding a new adapter in packages/protocols, not touching core.
  • Session vs one-shot — ProtocolAdapter handles stateless one-shot payments. SessionAdapter handles stateful payment channel sessions. Both live in packages/protocols, share the same core types.
  • Registry as single source — discover() queries the live registry API. No static directory bundled with the SDK.
  • Lazy credentials — The SDK accepts wallet credentials optionally. Read-only operations (quote, discover, diagnose) work without any keys. Payment operations validate credentials at call time.

​
Next Steps