@hit-pay/mpp

Protocol + service client + framework-agnostic protect middleware for the HitPay Machine Payments Protocol.

⚠️ Early preview · sandbox only. APIs will change. Don't use in production yet.

Monetise any HTTP route with a one-line middleware. Agents pay via HTTP 402; your users never have to sign up or set up keys.

Install

npm i @hit-pay/mpp@beta

For Next.js App Router, use @hit-pay/mpp-next instead. For agent runtimes, use @hit-pay/mpp-client.

Usage

import { createMpp } from '@hit-pay/mpp'

const mpp = createMpp({
  apiKey: process.env.HITPAY_API_KEY!,         // test_... sandbox key
  webhookSalt: process.env.HITPAY_WEBHOOK_SALT, // from HitPay dashboard
  endpoint: 'https://sandbox.mpp.hitpay.dev',   // sandbox for now
})

// Wrap any handler taking (Request, ctx) → Response
export const GET = mpp.protect(
  { amount: '1.00', currency: 'sgd', description: 'Forecast' },
  async (_req, ctx) => new Response(JSON.stringify({ forecast: 'sunny' }))
)

No Authorization: Payment <credential> header → 402 Payment Required with a HitPay-hosted checkout URL. Credential present → mpp-service verifies the charge against HitPay, signs a JWS receipt, and your handler runs.

API

createMpp(opts)

• apiKey: string — HitPay API key, pass-through only (never persisted)
• webhookSalt?: string — per-merchant HitPay webhook HMAC salt; required for sandbox/prod
• endpoint?: string — MPP service URL (default: https://mpp.hitpay.dev)
• jwksUrl?: string — receipt JWKS URL (default: {endpoint}/.well-known/jwks.json)

mpp.protect(priceOrFn, handler)

Wraps a (req, ctx) => Response handler, adding 402 gating + receipt attach.

Lower-level exports

MppServiceClient, buildWwwAuthenticate, parseWwwAuthenticate, encodeCredential, parseAuthorization, verifyReceipt, canonicalRequestHash.

Spec

See draft-hitpay-charge-00.

License

MIT