@powforge/captcha-paymcp-provider

PoW-skip payment provider for paymcp. Free-tier alternative to Lightning — lets agents solve SHA-256 proof-of-work instead of paying a Lightning invoice.

Pair with @powforge/paymcp-l402-provider to offer both tiers on the same _meta.price-tagged tool in ≤ 10 lines.

Install

npm install @powforge/captcha-paymcp-provider paymcp

Usage — PoW-skip only

const { PayMCP } = require('paymcp');
const { CaptchaPowProvider } = require('@powforge/captcha-paymcp-provider');

PayMCP(mcp, {
  providers: [
    new CaptchaPowProvider({ captchaUrl: 'https://captcha.powforge.dev' }),
  ],
});

Usage — PoW-skip + Lightning (full stack)

const { PayMCP } = require('paymcp');
const { LnbitsPaymentProvider } = require('@powforge/paymcp-l402-provider');
const { CaptchaPowProvider } = require('@powforge/captcha-paymcp-provider');

PayMCP(mcp, {
  providers: [
    new CaptchaPowProvider({ captchaUrl: 'https://captcha.powforge.dev', difficulty: 14 }),
    new LnbitsPaymentProvider({ lnbitsUrl: process.env.LNBITS_URL, lnbitsApiKey: process.env.LNBITS_KEY, satsAmount: 21 }),
  ],
});

paymcp's AUTO mode offers the PoW path first (free, costs ~5–10s of CPU) then Lightning (21 sats). The calling agent or user picks.

How it works

1. createPayment fetches a SHA-256 challenge from captchaUrl/api/challenge, mines the nonce server-side, and returns { payment_id, payment_url: "pow://..." }.
2. The pow:// URI encodes all parameters a PoW-capable MCP client SDK needs to independently verify the work.
3. getPaymentStatus submits the stored nonce to /api/verify and returns 'paid' when the captcha server confirms. The result is cached — the challenge is consumed exactly once.

Config

| Option | Required | Default | Description | |---|---|---|---| | captchaUrl | yes | — | PowForge captcha server URL | | difficulty | no | 14 | Leading-zero bits (overridden by server response) | | fetchImpl | no | globalThis.fetch | Inject a custom fetch for tests | | minerImpl | no | built-in SHA-256 loop | Inject (salt, difficulty) => nonce for tests |

License

MIT