在 Hono 中集成 x402 支付墙x402-hono 中间件实战指南【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402x402 是一个构建在 HTTP 之上的互联网支付协议而 Hono 以其轻量、跨运行时Node.js / Deno / Bun / Cloudflare Workers的特性成为构建 API 的热门框架。本指南以仓库中 e2e/legacy/servers/hono 的示例服务为主线完整讲解如何用x402-hono中间件为 Hono 端点接入支付墙paywall从环境准备、启动服务、用客户端完成先请求拿支付要求 → 处理支付 → 携带支付凭证再次请求的全流程到深入中间件源码理解 402 响应、支付验证与结算的内部机制最终你能在自己的 Hono 应用中独立部署一个按次付费的 HTTP API。注意本示例属于 x402v1时代的 legacy 示例x402-hono包已标记为 deprecated仅维护安全补丁新项目建议迁移到 v2 的x402/hono、x402/core、x402/evm等包参见仓库中的 migration-v1-to-v2 迁移指南。但 v1 的中间件设计与支付流程仍极具学习价值且本文涉及的示例代码与运行方式均以当前仓库实际内容为准。一、示例服务概览e2e/legacy/servers/hono目录是一个完整的 Hono 示例服务目录结构如下e2e/legacy/servers/hono/ ├── README.md # 本指南对应的原始文档 ├── index.ts # 服务入口定义支付中间件与业务路由 ├── package.json # 依赖与脚本dev / lint / format ├── tsconfig.json # TypeScript 编译配置 ├── install.sh # 安装脚本依赖由仓库根目录 pnpm 统一管理 ├── run.sh # 启动脚本pnpm dev ├── test.config.json # e2e 测试框架对端点的描述 ├── eslint.config.js # ESLint 配置服务本身极其精简只做三件事/protected需要支付 $0.001 才能访问的受保护端点/health健康检查端点/close优雅关闭服务的端点。这些端点在 test.config.json 中有对应的元数据描述例如/protected被标记为requiresPayment: true、protocolFamily: evm说明 e2e 测试框架会据此自动对它发起先 402、再带支付头请求的完整验证流程。二、前置条件在运行该示例之前需要准备以下环境以仓库内 README.md 为准Node.js v20可使用 nvm 安装pnpm v10仓库采用 pnpm workspace 管理多包依赖一个有效的以太坊收款地址用于接收支付Coinbase Developer PlatformCDPAPI Key 与 Secret仅在 Base 主网上收款时需要可在 CDP Portal 的项目页面创建。需要说明的是支付验证与结算并不依赖私钥签名——收款地址是公开信息验证签名与执行结算由 facilitator或内置默认实现完成因此服务端只需要配置地址本身。三、安装与启动1. 配置环境变量README 第一步是复制环境变量模板cp .env-local .env然后在.env中填写EVM_PAYEE_ADDRESS0xYourAddress EVM_NETWORKbase PORT4021 FACILITATOR_URL # 可选不填则使用默认 facilitator从 index.ts 源码可以看到实际读取的环境变量const payTo process.env.EVM_PAYEE_ADDRESS as 0x${string}; const network process.env.EVM_NETWORK as Network; const port parseInt(process.env.PORT || 4021); const facilitatorUrl process.env.FACILITATOR_URL;其中EVM_PAYEE_ADDRESS与EVM_NETWORK是必填项缺失时服务会打印Missing required environment variables并直接退出process.exit(1)PORT缺省为4021FACILITATOR_URL为可选——提供时使用远程 facilitator否则使用默认实现x402-hono 包在 testnet 场景下默认指向 x402.org/facilitator见 x402-hono README 的注释说明。2. 安装依赖并构建在 typescript examples 根目录安装并构建所有包cd ../../ pnpm install pnpm build cd servers/hono仓库使用 pnpm workspacex402-hono在 package.json 中被声明为x402-hono: workspace:*因此必须先在根目录统一安装并构建子目录才能拿到本地链接的依赖。install.sh也明确注明 TypeScript dependencies handled by pnpm install at root level本身为空操作。3. 运行服务pnpm install pnpm devpnpm dev实际执行tsx index.ts见 package.json 的 scripts 字段即用 tsx 直接运行 TypeScript 源码无需预先编译。启动成功后控制台会输出Server listening on port 4021端口以.env配置为准。四、服务入口源码解读入口文件 index.ts 展示了 x402 支付墙最核心的集成范式——先挂中间件再写普通业务路由import { paymentMiddleware, Network, Resource, FacilitatorConfig } from x402-hono; // 创建 facilitator 配置可选 const facilitatorConfig: FacilitatorConfig | undefined facilitatorUrl ? { url: facilitatorUrl as Resource } : undefined; const app new Hono(); // 对受保护端点应用支付中间件 app.use( paymentMiddleware( payTo, { /protected: { price: $0.001, network, }, }, facilitatorConfig, ), ); // 受保护端点只有支付成功后才能进入 app.get(/protected, c { return c.json({ message: Protected endpoint accessed successfully, timestamp: new Date().toISOString() }); }); // 健康检查 app.get(/health, c { return c.json({ status: healthy }); }); serve({ fetch: app.fetch, port, });paymentMiddleware(payTo, routes, facilitator?, paywall?)是x402-hono导出的核心工厂函数源码见 typescript/packages/legacy/x402-hono/src/index.ts它接收四个参数参数类型说明payToAddress \| SolanaAddress收款地址EVM 网络下为0x${string}routesRoutesConfig路由与价格的映射决定哪些路径需要支付、付多少facilitatorFacilitatorConfig可选facilitator 服务地址与鉴权头生成函数paywallPaywallConfig可选内置支付页的钱包选择弹窗、CDP 集成等配置五、用示例客户端完整走一遍支付流程README 建议用示例客户端验证服务。在e2e/legacy/clients/fetch或e2e/legacy/clients/axios目录下分别执行# Fetch 客户端 cd ../clients/fetch # 确保 .env 已配置 pnpm install pnpm dev # Axios 客户端 cd ../clients/axios # 确保 .env 已配置 pnpm install pnpm dev客户端会演示完整的支付三步曲首次请求获取支付要求不带X-PAYMENT头访问受保护端点得到402 Payment Required响应响应体携带paymentRequirements处理支付要求客户端解析支付要求用钱包对支付载荷支付给payTo、金额、资源 URL、超时等字段进行签名携带支付凭证再次请求把签名结果编码进X-PAYMENT请求头重新请求服务端验证通过后返回真实业务数据并在响应头中返回X-PAYMENT-RESPONSE结算凭证。这一流程对应中间件源码中的三段关键逻辑x402-hono/src/index.ts无支付头读取X-PAYMENT头为空时返回402及accepts支付要求数组与x402Version若请求来自浏览器Accept含text/html且User-Agent含Mozilla则返回内置 paywall HTML 页面而不是 JSON验证支付exact.evm.decodePayment(payment)解码支付头findMatchingPaymentRequirements匹配支付要求再调用verify验证签名结算支付路由处理完成后若响应状态码 400才执行settle结算并把结算结果编码为X-PAYMENT-RESPONSE响应头。中间件特意先清空响应再结算因为 Hono 中间件在响应发出后无法再设置请求头源码注释明确说明了这一点。六、响应格式详解1. 支付要求响应402未携带X-PAYMENT头访问受保护端点时服务返回{ error: X-PAYMENT header is required, paymentRequirements: { scheme: exact, network: base, maxAmountRequired: 1000, resource: http://localhost:4021/weather, description: , mimeType: , payTo: 0xYourAddress, maxTimeoutSeconds: 60, asset: 0x..., outputSchema: null, extra: null } }字段含义对照中间件源码x402-hono/src/index.ts字段含义来源scheme支付方案EVM 网络固定为exact常量network目标链如base/base-sepolia路由配置maxAmountRequired原子单位最小精度单位下的最大支付金额processPriceToAtomicAmount(price, network)转换结果resource被付费资源的 URL默认取请求 URL支持反向代理时根据X-Forwarded-Proto/X-Forwarded-Host重建description/mimeType资源描述与 MIME 类型config配置缺省为空串 /application/jsonpayTo收款地址getAddress(payTo)规范化后的地址maxTimeoutSeconds支付有效超时config.maxTimeoutSecondsEVM 缺省 300SVM 缺省 60asset支付资产合约地址EVM由价格解析得到outputSchema输出结构含输入方法、可发现性与响应 schemaconfig配置extra扩展字段EVM 下为资产的 EIP-712 元数据name/version资产配置价格与金额的换算由 typescript/packages/legacy/x402/src/types/shared/money.ts 中的moneySchema约束支持$0.001这类带货币符号的字符串自动剥离非数字字符或数字取值范围0.0001 ~ 999999999并经由processPriceToAtomicAmount按资产的decimals转为原子单位。这就是为什么 README 示例中$0.001会显示为maxAmountRequired: 1000。2. 支付成功后的响应支付验证与结算通过后业务端点正常返回同时响应头携带结算凭证// Body { report: { weather: sunny, temperature: 70 } } // Headers { X-PAYMENT-RESPONSE: ... // Encoded response object }X-PAYMENT-RESPONSE由settleResponseHeader(settlement)生成见中间件源码 x402-hono/src/index.ts客户端可以解码该头拿到结算结果作为支付凭证。注意示例 README 中的端点名为/weather而当前仓库入口源码实际定义的是/protected——两者都只是演示用途真实端点名以你部署的代码为准。3. 一个重要的结算细节中间件在业务路由执行之后才进行结算并且有一条保护规则x402-hono/src/index.ts如果受保护路由的响应状态码 400则不执行结算。这意味着请求失败不扣费由中间件内置保证。反之只有2xx/3xx类成功响应才会触发settle若结算失败则覆盖响应为 402 并在 body 中携带settlementFailed相关错误信息。七、扩展更多付费端点README 给出了扩展模式用路由通配符配置多个付费端点路由定义保持普通 Hono 写法。// 第一步配置支付中间件与各路由的支付要求 app.use( paymentMiddleware(payTo, { // 按路径配置价格 /your-endpoint: { price: $0.10, network, }, // 支持通配符路径并可用原子单位 资产对象精确指定 /premium/*: { price: { amount: 100000, asset: { address: 0xabc, decimals: 18, eip712: { name: WETH, version: 1, }, }, }, network, }, }), ); // 第二步业务路由照常定义 app.get(/your-endpoint, c { return c.json({ // Your response data }); }); app.get(/premium/content, c { return c.json({ content: This is premium content, }); });这里展示了price的两种形态对应RoutesConfig的类型设计见 x402-hono README简写price: $0.10或数字表示美元金额由中间件结合网络默认资产如 Base 上的 USDC自动换算完整对象{ amount, asset }显式指定原子单位金额、资产合约地址、decimals 与 EIP-712 元数据适合非默认资产或精确控制。路由匹配由中间件内部的computeRoutePatterns将路径编译为正则、findMatchingRoute按请求方法与路径匹配源码见 x402-hono/src/index.ts。未匹配到付费规则的路由会直接next()放行不影响服务其他端点。八、深入中间件一条请求的完整生命周期综合源码typescript/packages/legacy/x402-hono/src/index.ts一次带支付头的请求在中间件内部经历以下阶段路由匹配computeRoutePatterns(routes)预编译正则按method path查找匹配的付费规则不匹配则放行构建支付要求processPriceToAtomicAmount换算原子金额区分 EVM / SVM 网络构建PaymentRequirements——EVM 直接组装SVM 需先调用 facilitator 的supported()获取 fee payer缺失时抛错The facilitator did not provide a fee payer...读取支付头无X-PAYMENT时按客户端类型返回 HTML paywall402或 JSON 支付要求402Web 浏览器场景下还支持customPaywallHtml自定义页面与 CDP 入金Onramp集成解码与匹配exact.evm.decodePayment解码支付载荷findMatchingPaymentRequirements在多个支付要求中匹配对应项失败均返回 402验证签名verify(decodedPayment, selectedPaymentRequirements)校验支付有效性失败返回 402 并附带payer信息执行业务路由await next()结算状态码 400时调用settle成功则写入X-PAYMENT-RESPONSE响应头失败则整体改写为 402。这种验证通过才放行、响应成功才结算的顺序设计是 x402 支付墙能够安全地用于先付费后取货类资源的关键。九、常见问题与注意事项Missing required environment variables退出EVM_PAYEE_ADDRESS或EVM_NETWORK未配置或.env未被 dotenv 加载index.ts首行调用config()读取.env需确保.env位于服务根目录。依赖找不到x402-hono必须先在 typescript examples 根目录执行pnpm install pnpm build因为x402-hono是workspace:*本地包见 package.json。浏览器直接访问得到 HTML 而非 JSON中间件会检测Accept: text/html Mozilla User-Agent向浏览器返回内置 paywall 页面API 客户端应发送 JSON Accept 头。反向代理后资源 URL 不正确中间件优先使用X-Forwarded-Proto/X-Forwarded-Host重建resource请确保代理正确转发这两个头源码见 x402-hono/src/index.ts。版本定位本示例属于 legacy v1 生态。生产环境新项目应参照仓库 docs/guides/migration-v1-to-v2.mdx 迁移到 v2 包但 v1 中间件所演示的402 支付要求 X-PAYMENT 支付头 X-PAYMENT-RESPONSE 结算头协议语义与 v2 一脉相承。十、进一步探索阅读中间件完整源码typescript/packages/legacy/x402-hono/src/index.ts其中包含对 EVM 与 SVM 双协议族的完整处理对比同框架的 v1 实现typescript/packages/legacy/x402-express、typescript/packages/legacy/x402-fetch了解支付头签名与解码x402包 typescript/packages/legacy/x402/src/client 与 typescript/packages/legacy/x402/src/schemes/exact/evm通读协议规范specs/transports-v1/http.md 与 specs/x402-specification-v1.md若要用 e2e 框架自动验证本服务test.config.json 中已声明好端点的支付属性可直接接入 e2e 测试流程。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
