mppx

用途

mppx 是面向“Payment”HTTP 认证方案的 TypeScript SDK，用于实现完整的 HTTP 402 Payment Required 支付流程，涵盖挑战（challenge）→ 凭据（credential）→ 收据（receipt）三个阶段。它适用于需要让客户端自动完成付费请求、或让服务端按支付条件保护路由并回传收据的场景。

主要能力

客户端：通过 Fetch.polyfill 或 Fetch.from 为客户端添加 402 支付处理能力。
服务端：使用服务端的 MPP Challenges 与 Receipt 响应保护 HTTP 路由。
Tempo 一次性支付：使用 tempo.charge 接受一次性 Tempo 稳定币支付。
Tempo 按量支付：使用 tempo.session 接受按量计费的 Tempo 稳定币支付。
Stripe 卡支付：使用 stripe.charge 接受一次性卡支付。
直接验证：可对自定义传输或后台工作流直接验证 Credential。
MCP 集成：包装 MCP 客户端和服务端，使工具调用可以要求付费。
中间件与导出：提供 mppx/hono、mppx/express、mppx/nextjs、mppx/elysia 等中间件；导出核心原语（Challenge、Credential、Method、Receipt、PaymentRequest）、客户端（Mppx、tempo、stripe、session、Transport）、服务端（Mppx、tempo、stripe、Transport、Store、NodeListener）。
CLI：内置用于开发期间发起付费请求的命令行工具。

使用方式

客户端 Polyfill 全局 fetch：

import { Mppx, tempo } from 'mppx/client'

Mppx.create({
  methods: [tempo({ account })],
})

const res = await fetch('https://api.example.com/resource')

不 Polyfill 时：

const mppx = Mppx.create({
  methods: [tempo({ account })],
  polyfill: false,
})

const res = await mppx.fetch('https://api.example.com/resource')

服务端示例：

import { Mppx, Store, tempo } from 'mppx/server'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0x...')

const mppx = Mppx.create({
  methods: [
    tempo.charge({ recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266' }),
    tempo.session({
      account,
      chainId: 4217,
      recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
      store: Store.memory(),
    }),
  ],
  secretKey: process.env.MPP_SECRET_KEY,
})

async function handler(request: Request): Promise<Response> {
  const result = await mppx.charge({ amount: '1.00' })(request)
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

CLI 示例：

npx mppx account create        # create wallet
npx mppx mpp.dev/api/ping/paid # make paid request
npx mppx example.com -v        # verbose output

方法说明：

Method	Intent	Description
tempo.charge	charge	一次性稳定币支付（Tempo 上的 TIP-20 代币转账）
tempo.session	session	通过 Tempo 支付通道进行流式支付
stripe.charge	charge	通过 Stripe 进行一次性支付

服务端 tempo() 会按每个接受的货币返回 charge/session 组合；单独的 tempo.charge() 与 tempo.session() 工厂会为各自 intent 返回非空方法数组；Mppx.create 会将这些分组扁平化。主网默认依次为 OUSD、USDC.e；Moderato 默认依次为 OUSD、pathUSD。可通过 currencies 替换该列表，例如 currencies: ['0x20c0000000000000000000006a37DA5C996874BE'] 仅接受 OUSD。

所需输入

客户端集成：需要签名账户和一个或多个客户端支付方式。
服务端集成：需要收款方、金额和 MPP_SECRET_KEY；Tempo 货币列表可选。
Tempo 示例：除页面明确说明 Moderato 测试网外，使用链 ID 4217。
Stripe 示例：需要配置好的 Stripe 账户和 Shared Payment Token 流程。
MCP 集成：需要被包装的 MCP 客户端或服务端对象。

约束与限制

MPP_SECRET_KEY 必须保存在服务端，且不得出现在日志中。
切勿提交私钥或钱包种子。
运行时的 402 Challenge 应被视为当前支付条款的权威来源。
响应 Challenge 时，返回的 id 和 opaque 必须保持不变。
在单币种 Tempo 示例中使用 OUSD；省略 currencies 时会优先提供 OUSD，并附带特定网络的回退。
Factory currencies 配置可接受的代币；wire requests 和 per-handler overrides 保留单一货币。
使用完整的代币地址，保留各提供商特定的代币要求。

适用场景

需要在 HTTP API 上实现按请求付费（如付费接口、付费工具调用）、基于稳定币或卡支付的计费、按量计费会话、以及为 MCP 工具调用增加付费门槛的客户端与服务端应用。