\n\n# lightning-mppx\n\nA Lightning Network payment method for [MPP](https://mpp.dev).\n\n> **Note for Lightning developers:** In the Lightning Network, \"MPP\" refers to [Multi-Path Payments](https://bitcoinops.org/en/topics/multipath-payments/) (BOLT #4). This is unrelated - [MPP](https://mpp.dev) here stands for **Machine Payments Protocol**, an open HTTP payment standard.\n\n[MPP](https://mpp.dev) (Machine Payments Protocol) is an open protocol that lets any HTTP API accept payments using the standard `402 Payment Required` flow. `@buildonspark/lightning-mpp-sdk` extends the [`mppx`](https://github.com/tempoxyz/mpp) SDK with Lightning Network support via [Spark](https://spark.money), sitting alongside built-in methods like [Stripe](https://stripe.com) and [Tempo](https://tempo.xyz).\n\nThe protocol supports two intents - **charge** for one-time payments and **session** for prepaid metered access - defined in implementation-agnostic [IETF-style specifications](https://paymentauth.org) that any Lightning node or wallet can implement.\n\n## Why Lightning\n\nMPP is payment-method agnostic by design - the right payment method depends on the context. Lightning brings something unique to the table.\n\n**No one controls it.** Bitcoin is an open network. Anyone can run a node, verify transactions, and move money without depending on a third party. A payment layer for the open internet should be just as open as the network it runs on.\n\n**Private by default.** Lightning payments are onion-routed. When an agent pays for an API call, the only parties who know are the payer and the payee.\n\n**Unmatched network effects.** Bitcoin has more liquidity than all stablecoins combined by an order of magnitude. Cash App, Coinbase, Binance, Strike, Kraken, and most major fintechs already support Lightning.\n\n## How it works\n\n1. Client requests a resource.\n2. Server returns `402 Payment Required` with a fresh [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) invoice.\n3. Client pays the invoice over the Lightning Network.\n4. Client retries with the payment preimage as proof.\n5. Server verifies `sha256(preimage) == paymentHash` locally and returns the resource with a receipt.\n\nNo external payment processor. No polling. No webhooks. The preimage _is_ the proof of payment.\n\n## Getting started\n\n### Installation\n\n```bash\nnpm install @buildonspark/lightning-mpp-sdk mppx\n```\n\n### Server\n\nUses the Web-standard `Request`/`Response` API - works with Node.js, Cloudflare Workers, Next.js, and any other runtime.\n\n```ts\nimport { Mppx, spark } from '@buildonspark/lightning-mpp-sdk/server'\n\nconst mppx = Mppx.create({\n methods: [spark.charge({ mnemonic: process.env.MNEMONIC! })],\n secretKey: process.env.MPP_SECRET_KEY!,\n})\n\nexport async function handler(request: Request): Promise {\n const result = await mppx.charge({\n amount: '100',\n currency: 'sat',\n description: 'Premium API access',\n })(request)\n\n if (result.status === 402) return result.challenge\n\n return result.withReceipt(Response.json({ data: '...' }))\n}\n```\n\n### Client\n\nThe MPP client intercepts 402 responses automatically - paying invoices and retrying with credentials before returning the final response to your code.\n\n```ts\nimport { Mppx, spark } from '@buildonspark/lightning-mpp-sdk/client'\n\nconst method = spark.charge({ mnemonic: process.env.MNEMONIC! })\nconst mppx = Mppx.create({ polyfill: false, methods: [method] })\n\ntry {\n const response = await mppx.fetch('https://api.example.com/weather')\n console.log(await response.json())\n} finally {\n await method.cleanup()\n}\n```\n\nOr patch `globalThis.fetch` so all requests are payment-aware:\n\n```ts\nimport { Mppx, spark } from '@buildonspark/lightning-mpp-sdk/client'\n\nMppx.create({ methods: [spark.charge({ mnemonic: process.env.MNEMONIC! })] })\n\nconst response = await fetch('https://api.example.com/weather')\n```\n## Configuration\n\n### Server - `spark.charge()`\n\n| Parameter | Type | Required | Default |\n| ---------- | ---------------------------------------- | -------- | ----------- |\n| `mnemonic` | `string` | Yes | |\n| `network` | `'mainnet'` \\| `'regtest'` \\| `'signet'` | No | `'mainnet'` |\n\n### Server - `mppx.charge()`\n\n| Parameter | Type | Required | Default |\n| ------------- | -------- | -------- | ------- |\n| `amount` | `string` | Yes | |\n| `currency` | `string` | No | `'sat'` |\n| `description` | `string` | No | |\n\n### Client - `spark.charge()`\n\n| Parameter | Type | Required | Default |\n| ------------ | ---------------------------------------- | -------- | ----------- |\n| `mnemonic` | `string` | Yes | |\n| `network` | `'mainnet'` \\| `'regtest'` \\| `'signet'` | No | `'mainnet'` |\n| `maxFeeSats` | `number` | No | `100` |\n\n## Examples\n\nThe `examples/` directory contains a weather API demo - a server that charges 100 sats per request and a client that pays automatically. Both run on regtest using Spark wallets.\n\n```bash\n# Terminal 1\nnpm run example:server\n\n# Terminal 2\nnpm run example:client\n```\n\n## Wallet funding\n\nOn **mainnet**, fund your client wallet by depositing sats via Spark, Lightning, or L1:\n\n```ts\nimport { SparkWallet } from '@buildonspark/spark-sdk'\n\nconst { wallet } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic })\n\n// Spark\nconsole.log(await wallet.getSparkAddress())\n// sprt1pqqqqq2yuzewtxcnuswt8xnz6gdwmspk5ln3gl4wfar4stc7qa9xscvflqe\n\n// L1 (Bitcoin on-chain)\nconsole.log(await wallet.getStaticDepositAddress())\n// bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh\n```\n\nFor Lightning, generate a deposit invoice with `wallet.createLightningInvoice({ amountSats, memo })`.\n\nOn **regtest**, use the [Spark faucet](https://docs.spark.money/tools/faucet).\n\n## Specifications\n\nThe Lightning payment method is defined in two IETF-formatted specifications within the [HTTP Payment Authentication](https://paymentauth.org) framework:\n\n- [`draft-lightning-charge-00`](https://paymentauth.org/draft-lightning-charge-00.html) - One-time BOLT11 invoice payments\n- [`draft-lightning-session-00`](https://paymentauth.org/draft-lightning-session-00.html) - Prepaid sessions with per-unit billing and refund on close\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"@buildonspark/lightning-mpp-sdk\"](\"./assets/banner.png\")
![\"@buildonspark/lightning-mpp-sdk\"](\"https://raw.githubusercontent.com/buildonspark/lightning-mpp-sdk/main/assets/banner.png\")