@powforge/captcha-paymcp-provider

@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

• createPayment fetches a SHA-256 challenge from captchaUrl/api/challenge, mines the nonce server-side, and returns { payment_id, payment_url: "pow://..." }.
• The pow:// URI encodes all parameters a PoW-capable MCP client SDK needs to independently verify the work.
• 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