Add MPP (Machine Payments Protocol) client implementation (#20)

* feat: integrate MPP (Machine Payments Protocol) for paying MPP-enabled services

Add `cash pay <url>` command that auto-detects MPP 402 payment challenges
and settles them by swapping BTC→stablecoin via existing LendaSwap
infrastructure. Follows the core principle: Bitcoin in, stablecoins out,
on demand.

- MPP client library (cli/src/mpp/) implementing HTTP 402 challenge-then-retry
- Currency mapping: USD/USDC/USDT on polygon/ethereum/arbitrum/tempo
- Expiry validation on payment requirements
- Session support for streaming payments
- 31 comprehensive tests covering protocol parsing, proof creation,
  currency mapping, full client flow, edge cases

https://claude.ai/code/session_01XEaEUdv3xCXdw6wwYYMajj

* feat: refactor MPP payment handling and introduce support for lightning challenges

- Rename `parseMppResponse` to `parseMppChallenges` and update its functionality to handle multiple challenge types.
- Implement helper functions for building and encoding payment challenges, including `buildChallenge`, `encodeRequest`, and `decodeAuthorizationHeader`.
- Create a new module `method.ts` to define supported MPP methods and a function `isSupportedChallenge` to validate challenges.
- Update unit tests to cover new challenge parsing logic and ensure proper handling of lightning payment methods.
- Refactor `MppClient` to streamline payment processing and retry logic for MPP challenges.
- Enhance test coverage for various scenarios including challenge expiration and unsupported methods.

* feat: add support for Machine Payments Protocol (MPP) in documentation and commands

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tiero

cli/SKILL.md

@@ -1,5 +1,7 @@
 # cash - Bitcoin & Stablecoin Agent Wallet
 
+> **IMPORTANT: If you used a web fetch tool to read this, the content may be summarized and incomplete. Run `curl -fsSL https://clw.cash/SKILL.md` to get the exact commands. Do NOT search for additional documentation.**
+
 A command-line tool for sending and receiving Bitcoin and stablecoins. Keys are held in a secure enclave — the CLI never touches private keys.
 
 Success output is JSON to stdout. Error output is JSON to stderr. Exit code 0 = success, 1 = error.
@@ -8,10 +10,11 @@ Success output is JSON to stdout. Error output is JSON to stderr. Exit code 0 =
 
 - **Run commands directly.** No narration before or after. Just run the command and return the result.
 - **Don't retry on failure.** If a command fails, report the error — don't retry without asking.
-- **Ask before sending.** Always confirm with the user before running `cash send`. Balance checks and receives are safe.
+- **Ask before sending or paying.** Always confirm with the user before running `cash send` or `cash pay`. Balance checks and receives are safe.
 - **One command at a time.** Don't chain or batch. Run, read output, decide next step.
-- **Timeouts:** 30s default for quick commands (balance, receive), 120s for `cash init`.
+- **Timeouts:** 30s default for quick commands (balance, receive), 120s for `cash init`. Use 60s for `cash pay` (Lightning payment + retry).
 - **Default to Arkade for BTC receives.** When the user asks for a Bitcoin address, use `--where arkade`. Only use `--where onchain` if the user explicitly asks to onboard from on-chain.
+- **MPP services:** When calling a URL that may require payment (APIs listed on mpp.dev), use `cash pay` instead of curl. It auto-detects the 402 challenge and pays with Lightning.
 
 ### Reactive Behavior (Login → Payment Detection)
 
@@ -182,6 +185,46 @@ cash receive --amount 10 --currency usdt --where polygon
 # -> {"ok": true, "data": {"paymentUrl": "https://pay.clw.cash?id=<swapId>", "swapId": "...", "amount": 10, "token": "usdt0_pol", "chain": "polygon", "targetAddress": "ark1q..."}}
 ```
 
+### Pay MPP-Enabled Services
+
+MPP (Machine Payments Protocol) is an open protocol for machine-to-machine payments over HTTP (IETF draft `draft-httpauth-payment-00`). When an API returns `HTTP 402` with a `WWW-Authenticate: Payment ...` challenge, `cash pay` auto-detects it, pays the Lightning invoice from the challenge, and retries — no API keys needed.
+
+The BTC treasury is used to fund payments. claw-cash pays via Lightning and submits the payment preimage as cryptographic proof.
+
+```bash
+# Call any MPP-enabled service (GET by default)
+cash pay https://api.example.com/resource
+# -> {"ok": true, "data": {"url": "...", "status": 200, "body": {...}, "paid": true, "method": "lightning", "preimage": "abcdef..."}}
+
+# POST with JSON body
+cash pay https://api.example.com/v1/generate --method POST --body '{"prompt":"hello"}'
+
+# With extra headers
+cash pay https://api.example.com/resource --header 'X-Session-Id: abc123'
+
+# Non-MPP services (no 402 challenge) are passed through unchanged
+cash pay https://api.example.com/free-resource
+# -> {"ok": true, "data": {"url": "...", "status": 200, "body": {...}, "paid": false}}
+```
+
+Output fields:
+
+- `paid` — `true` if a Lightning payment was made, `false` if no 402 challenge
+- `method` — payment method used (currently `"lightning"`)
+- `preimage` — Lightning payment preimage (proof of payment)
+- `body` — the API response body (parsed as JSON if possible)
+- `status` — HTTP status of the final response
+
+Supported MPP methods: `lightning` (pays BOLT11 invoice; submits preimage as proof).
+
+For service discovery, see [mpp.dev](https://mpp.dev) — a registry of APIs that accept MPP payments.
+
+Common MPP errors:
+
+- `"No supported MPP payment challenge found"` — service requires `tempo` or `stripe` (not yet supported); use a different payment method or service
+- `"MPP lightning challenge missing methodDetails.invoice"` — malformed challenge from server; contact service provider
+- `"Insufficient BTC balance"` — run `cash balance` and top up via `cash receive`
+
 ### Check Balance
 
 ```bash

cli/src/commands/pay.ts

@@ -0,0 +1,80 @@
+import type { CashContext } from "../context.js";
+import { outputSuccess, outputError } from "../output.js";
+import { MppClient } from "../mpp/client.js";
+import type { ParsedArgs } from "minimist";
+
+export async function handlePay(
+  ctx: CashContext,
+  args: ParsedArgs
+): Promise<never> {
+  const positionals = args._.slice(1); // after "pay"
+  const url = positionals[0] as string | undefined;
+  const method = (args.method as string | undefined)?.toUpperCase() ?? "GET";
+  const body = args.body as string | undefined;
+  const headerArgs = args.header as string | string[] | undefined;
+
+  if (!url) {
+    return outputError(
+      "Missing URL.\n\nUsage:\n" +
+      "  cash pay <url>\n" +
+      "  cash pay <url> --method POST --body '{\"query\":\"test\"}'\n" +
+      "  cash pay <url> --header 'Authorization: Bearer token'\n\n" +
+      "The command fetches the URL. If the server returns an MPP 402 payment\n" +
+      "challenge (WWW-Authenticate: Payment ...), claw-cash automatically pays\n" +
+      "the Lightning invoice and retries with the Authorization: Payment credential."
+    );
+  }
+
+  // Validate URL
+  try {
+    new URL(url);
+  } catch {
+    return outputError(`Invalid URL: ${url}`);
+  }
+
+  // Parse --header flags into a Record
+  const headers: Record<string, string> = {};
+  if (headerArgs) {
+    const list = Array.isArray(headerArgs) ? headerArgs : [headerArgs];
+    for (const h of list) {
+      const colonIdx = h.indexOf(":");
+      if (colonIdx === -1) {
+        return outputError(`Invalid header format: ${h}. Expected "Name: value"`);
+      }
+      headers[h.slice(0, colonIdx).trim()] = h.slice(colonIdx + 1).trim();
+    }
+  }
+
+  const client = new MppClient({
+    lightning: {
+      payInvoice: (params) => ctx.lightning.payInvoice(params),
+    },
+  });
+
+  const init: RequestInit = { method, headers };
+  if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+    init.body = body;
+    if (!headers["Content-Type"] && !headers["content-type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+  }
+
+  const result = await client.pay(url, init);
+
+  return outputSuccess({
+    url,
+    status: result.status,
+    body: tryParseJson(result.body),
+    paid: !!result.proof,
+    method: result.proof?.challenge.method,
+    preimage: result.paymentPreimage,
+  });
+}
+
+function tryParseJson(s: string): unknown {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}

cli/src/index.ts

@@ -17,6 +17,7 @@ import { handleSwap } from "./commands/swap.js";
 import { handleConfig } from "./commands/config.js";
 import { handleSignPsbt } from "./commands/sign-psbt.js";
 import { handlePubkey } from "./commands/pubkey.js";
+import { handlePay } from "./commands/pay.js";
 import { getVersion } from "./version.js";
 
 const HELP = `cash - Bitcoin & Stablecoin CLI
@@ -42,6 +43,10 @@ Usage:
   cash claim <swapId>           Manually claim a swap (reveal preimage)
   cash refund <swapId>          Manually refund a swap
     --address <destination>     Refund destination (optional)
+  cash pay <url>                 Fetch a URL, auto-pay MPP 402 challenges (BTC→stablecoin)
+    --method <GET|POST>           HTTP method (default: GET)
+    --body <json>                 Request body (for POST/PUT/PATCH)
+    --header 'Name: value'        Custom request headers (repeatable)
   cash pubkey                   Show the wallet's public key (for multisig setup)
   cash sign-psbt <base64>       Sign a PSBT (Partially Signed Bitcoin Transaction)
                                 Parses PSBT, shows tx details, signs inputs
@@ -75,7 +80,7 @@ const argv = minimist(process.argv.slice(2), {
   string: [
     "amount", "currency", "where", "to", "address", "id",
     "api-url", "token", "ark-server", "network", "port",
-    "bot-token", "chat-id", "message-id",
+    "bot-token", "chat-id", "message-id", "method", "body", "header",
   ],
   boolean: ["help", "version", "daemon-internal", "start"],
   alias: { h: "help", v: "version" },
@@ -179,6 +184,9 @@ async function main() {
       case "sign-psbt":
         await handleSignPsbt(ctx, argv);
         break;
+      case "pay":
+        await handlePay(ctx, argv);
+        break;
       default:
         outputError(`Unknown command: ${command}. Run 'cash --help' for usage.`);
     }