拓冰网站定制 
x402-express 实战用 Express 中间件为 API 端点搭建加密货币付费墙【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文以 x402 项目仓库中的 Express 示例服务器e2e/legacy/servers/express为蓝本完整讲解如何基于x402-express中间件在 Express.js 应用中接入 x402 支付协议将普通 API 端点变成付费后才能访问的资源客户端首次请求会收到携带paymentRequirements的 402 响应支付完成后再携带付款凭证访问即可通过验证并自动触发链上结算。读完本文你将掌握从环境准备、服务启动、客户端联调到多路由付费墙配置的完整落地路径并能对照源码理解支付校验与结算的内部流程。背景legacy 示例与当前仓库的关系x402-express是 x402 协议v1时代的 Express 集成包本文对应的示例服务器位于 e2e/legacy/servers/express被仓库标记为 legacy已弃用仅接收安全修复。协议已演进到 v2x402/express、x402/core、x402/evm等包官方迁移说明见 docs/guides/migration-v1-to-v2.mdx文中最后也会给出两代 API 的对照。即便如此这个示例服务器仍是理解用 HTTP 中间件实现付费墙这一核心交互模式最直观的入口它的代码极短只依赖 Express 与x402-express两个核心依赖见 package.json却完整覆盖了声明受保护路由 → 返回支付要求 → 验证支付 → 结算的全链路。运行环境准备Prerequisites示例服务器对环境的要求如下依赖说明Node.js v20建议通过 nvm 安装保证版本可切换pnpm v10仓库使用 pnpm workspace 管理依赖一个有效的 EVM 收款地址接收付款的payTo地址如0x...Coinbase Developer Platform API Key Secret仅在 Base 主网接受付款时需要在 CDP 项目门户创建其中 CDP API Key 的作用是当FACILITATOR_URL指向 Base 主网 facilitator 时服务端需要用该密钥完成结算签名与身份认证如果只在测试网base-sepolia / solana-devnet上验证流程可以留空。环境变量与.env配置仓库在 .env-local 提供了环境变量模板按 README 的指引复制为.env后填写cp .env-local .env模板内容如下FACILITATOR_URLhttps://x402.org/facilitator EVM_NETWORKbase-sepolia SVM_NETWORKsolana-devnet EVM_ADDRESS SVM_ADDRESS # required if using the Base mainnet facilitator CDP_API_KEY_IDCoinbase Developer Platform Key CDP_API_KEY_SECRETCoinbase Developer Platform Key Secret结合 test.config.json 中的environment声明变量可以分为两类必填项PORT默认4021、EVM_NETWORK、SVM_NETWORK、EVM_PAYEE_ADDRESS、SVM_PAYEE_ADDRESS可选项FACILITATOR_URL不配置时使用默认 facilitator。需要注意一个仓库内的命名细节.env-local模板仍保留了旧命名EVM_ADDRESS/SVM_ADDRESS而 index.ts 实际读取的是EVM_PAYEE_ADDRESS与SVM_PAYEE_ADDRESS且缺少任一 EVM 相关变量都会直接process.exit(1)退出见 index.ts。实际部署时请以index.ts读取的变量名为准与 test.config.json 保持一致。安装与启动按照 README 的步骤从 typescript 示例根目录安装并构建全部包再进入 express 示例目录运行cd ../../ pnpm install pnpm build cd servers/expresspnpm install pnpm dev其中pnpm dev对应 package.json 中的tsx index.ts即以 tsx 直接执行 TypeScript 入口无需单独编译。服务启动后监听在http://localhost:4021PORT默认值控制台输出Server listening at http://localhost:4021。除了文档化的启动方式该示例还配套了 e2e 运行脚本 run.sh 执行pnpm devinstall.sh 说明 TS 依赖由根级pnpm install统一处理。示例端点与付费墙效果README 以一个返回天气报告的/weather端点作为教学示例要求支付$0.001才能访问。当前仓库的 index.ts 则注册了更贴近联调场景的两条受保护路由路由支付要求协议族GET /protected$0.001网络由EVM_NETWORK决定EVM默认 base-sepoliaGET /protected-svm$0.001网络由SVM_NETWORK决定SVM默认 solana-devnet这两条路由分别通过两次独立的paymentMiddleware调用挂载index.ts演示了同一应用中同时保护 EVM 与 SVM 两条链上的资源。此外还提供了联调用端点GET /health返回{ status: ok }POST /close用于优雅关闭服务见 test.config.json 中的health与close声明。未携带付款凭证访问受保护端点时服务返回 HTTP 402正文为支付要求README 原始示例{ 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 } }paymentRequirements各字段含义如下scheme支付方案此处为exact精确金额另一常见方案为uptonetwork结算网络标识如base、base-sepolia、solana-devnetmaxAmountRequired要求的最大金额按资产最小单位表示resource受保护资源的完整 URL客户端用它回放请求payTo收款地址maxTimeoutSeconds支付有效期默认 60 秒asset支付资产地址outputSchema/extra扩展字段此处为null。支付成功后的响应包含业务数据与结算凭证头// Body { report: { weather: sunny, temperature: 70 } } // Headers { X-PAYMENT-RESPONSE: ... // Encoded response object }其中X-PAYMENT-RESPONSE携带编码后的结算响应对象供客户端或后续审计方确认本次付款已入账。用示例客户端端到端联调服务端就绪后README 推荐用仓库自带的 fetch 或 axios 客户端验证完整流程Fetch 客户端cd ../clients/fetch # Ensure .env is setup pnpm install pnpm devAxios 客户端cd ../clients/axios # Ensure .env is setup pnpm install pnpm dev两个客户端对应的实现分别位于 e2e/legacy/clients/fetch/index.ts 与 e2e/legacy/clients/axios/index.ts它们都会演示三步联调首次请求不带支付头访问受保护端点拿到 402 与paymentRequirements处理支付要求根据paymentRequirements构造并签署支付凭证接入钱包/签名器带凭证二次请求在请求头中携带支付凭证得到 200 与真实业务数据。这一步验证的是 x402 的核心契约未支付先 402支付后放行整个过程中服务端不需要预存任何客户端会话状态。扩展付费端点路由配置详解README 给出了为应用增加更多付费端点的标准写法——把路由与价格统一配置进paymentMiddleware的第一参在 v1 API 中这是第二个参数// First, configure the payment middleware with your routes app.use( paymentMiddleware( payTo, { // Define your routes and their payment requirements GET /your-endpoint: { price: $0.10, network: base-sepolia, }, /premium/*: { price: { amount: 100000, asset: { address: 0xabc, decimals: 18, eip712: { name: WETH, version: 1, }, }, }, network: base-sepolia, }, }, ), ); // Then define your routes as normal app.get(/your-endpoint, (req, res) { res.json({ // Your response data }); }); app.get(/premium/content, (req, res) { res.json({ content: This is premium content, }); });这段示例揭示了 v1 路由配置的三种能力字符串价格price: $0.10表示按美元计价facilitator 会在结算时换算为网络原生资产如 USDC通配符路由/premium/*可以一次性保护/premium下的所有子路径指定代币资产当price改为对象时可通过amount最小单位数量与asset含address、decimals以及 EIP-712 域信息name/version精确指定收款代币例如 WETH。对应的 v1 类型定义可在 typescript/packages/legacy/x402-express/README.md 中查看RoutesConfig Recordstring, Price | RouteConfig其中RouteConfig由price、network与可选的configdescription、mimeType、maxTimeoutSeconds等组成。从源码看中间件的处理流程示例服务器虽然只有约 80 行代码但中间件内部做了大量工作。v1 的x402-express中间件职责可以概括为对照 v2 重构版 typescript/packages/http/express/src/index.ts 中的paymentMiddlewareFromHTTPServer理解路由匹配根据请求的path与method判断是否命中受保护路由未命中直接next()放行读取支付凭证从请求头中读取x-payment或payment-signature头校验与响应支付缺失或非法时返回 402 与paymentRequirements校验通过则进入路由处理缓冲响应并结算中间件会拦截res.writeHead/res.write/res.end/res.flushHeaders等待路由处理完毕后若业务响应状态码 400不执行结算原样回放缓冲的响应见 index.ts否则调用processSettlement完成链上结算并把结算结果写入响应头X-PAYMENT-RESPONSE后回放给客户端结算失败时丢弃缓冲内容并返回 402 或 502facilitator 边界错误归一化为 502见 sendFacilitatorError。另外中间件还支持setSettlementOverrides(res, { amount: 500 })这类部分结算覆盖partial settlement能力以及为浏览器请求自动渲染付费墙 UIx402/paywall可配置appName、appLogo、testnet等参数——这正是本文第一张配图中输入钱包、显示金额、Pay now界面的来源。从 v1 到 v2API 迁移要点由于x402-express已弃用官方建议迁移到 v2 的x402/express详见 docs/guides/migration-v1-to-v2.mdx 与 typescript/packages/http/express/README.md。两代 API 的核心差异如下维度v1x402-express本文v2x402/express中间件参数(payTo, routes, facilitator?, paywall?)(routes, resourceServer, paywallConfig?, paywall?, syncFacilitatorOnStart?)收款地址独立参数payTo移入每个路由的accepts.payTo支付方案内置 exact显式注册 scheme如new ExactEvmScheme()网络标识base-sepolia等短名CAIP-2 风格如eip155:84532v2 的迁移示例const facilitator new HTTPFacilitatorClient({ url: facilitatorUrl }); const resourceServer new x402ResourceServer(facilitator) .register(eip155:84532, new ExactEvmScheme()); app.use( paymentMiddleware( routes, // payTo 已在路由的 accepts 中声明 resourceServer, paywallConfig, // 可选 ), );如果你正从本文的 legacy 示例起步建议直接在 v2 架构上编写新代码本文示例的价值在于它以最小可运行形态完整展示了402 协商 → 支付 → 结算这一始终未变的协议内核。小结通过本示例服务器你可以零门槛跑通 x402 付费墙的完整闭环配置环境变量 → 启动 Express 服务 → 用 fetch/axios 客户端联调 → 观察 402 支付要求与结算响应头 → 按需扩展更多付费路由。从源码看中间件内部完成了路由匹配、凭证校验、响应缓冲、条件结算与失败兜底等关键逻辑这为理解 v2 中x402ResourceServerx402HTTPResourceServer的分层设计提供了很好的对照起点。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 x402-express 实战：用 Express 中间件为 API 端点搭建加密货币付费墙
x402-express 实战用 Express 中间件为 API 端点搭建加密货币付费墙【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文以 x402 项目仓库中的 Express 示例服务器e2e/legacy/servers/express为蓝本完整讲解如何基于x402-express中间件在 Express.js 应用中接入 x402 支付协议将普通 API 端点变成付费后才能访问的资源客户端首次请求会收到携带paymentRequirements的 402 响应支付完成后再携带付款凭证访问即可通过验证并自动触发链上结算。读完本文你将掌握从环境准备、服务启动、客户端联调到多路由付费墙配置的完整落地路径并能对照源码理解支付校验与结算的内部流程。背景legacy 示例与当前仓库的关系x402-express是 x402 协议v1时代的 Express 集成包本文对应的示例服务器位于 e2e/legacy/servers/express被仓库标记为 legacy已弃用仅接收安全修复。协议已演进到 v2x402/express、x402/core、x402/evm等包官方迁移说明见 docs/guides/migration-v1-to-v2.mdx文中最后也会给出两代 API 的对照。即便如此这个示例服务器仍是理解用 HTTP 中间件实现付费墙这一核心交互模式最直观的入口它的代码极短只依赖 Express 与x402-express两个核心依赖见 package.json却完整覆盖了声明受保护路由 → 返回支付要求 → 验证支付 → 结算的全链路。运行环境准备Prerequisites示例服务器对环境的要求如下依赖说明Node.js v20建议通过 nvm 安装保证版本可切换pnpm v10仓库使用 pnpm workspace 管理依赖一个有效的 EVM 收款地址接收付款的payTo地址如0x...Coinbase Developer Platform API Key Secret仅在 Base 主网接受付款时需要在 CDP 项目门户创建其中 CDP API Key 的作用是当FACILITATOR_URL指向 Base 主网 facilitator 时服务端需要用该密钥完成结算签名与身份认证如果只在测试网base-sepolia / solana-devnet上验证流程可以留空。环境变量与.env配置仓库在 .env-local 提供了环境变量模板按 README 的指引复制为.env后填写cp .env-local .env模板内容如下FACILITATOR_URLhttps://x402.org/facilitator EVM_NETWORKbase-sepolia SVM_NETWORKsolana-devnet EVM_ADDRESS SVM_ADDRESS # required if using the Base mainnet facilitator CDP_API_KEY_IDCoinbase Developer Platform Key CDP_API_KEY_SECRETCoinbase Developer Platform Key Secret结合 test.config.json 中的environment声明变量可以分为两类必填项PORT默认4021、EVM_NETWORK、SVM_NETWORK、EVM_PAYEE_ADDRESS、SVM_PAYEE_ADDRESS可选项FACILITATOR_URL不配置时使用默认 facilitator。需要注意一个仓库内的命名细节.env-local模板仍保留了旧命名EVM_ADDRESS/SVM_ADDRESS而 index.ts 实际读取的是EVM_PAYEE_ADDRESS与SVM_PAYEE_ADDRESS且缺少任一 EVM 相关变量都会直接process.exit(1)退出见 index.ts。实际部署时请以index.ts读取的变量名为准与 test.config.json 保持一致。安装与启动按照 README 的步骤从 typescript 示例根目录安装并构建全部包再进入 express 示例目录运行cd ../../ pnpm install pnpm build cd servers/expresspnpm install pnpm dev其中pnpm dev对应 package.json 中的tsx index.ts即以 tsx 直接执行 TypeScript 入口无需单独编译。服务启动后监听在http://localhost:4021PORT默认值控制台输出Server listening at http://localhost:4021。除了文档化的启动方式该示例还配套了 e2e 运行脚本 run.sh 执行pnpm devinstall.sh 说明 TS 依赖由根级pnpm install统一处理。示例端点与付费墙效果README 以一个返回天气报告的/weather端点作为教学示例要求支付$0.001才能访问。当前仓库的 index.ts 则注册了更贴近联调场景的两条受保护路由路由支付要求协议族GET /protected$0.001网络由EVM_NETWORK决定EVM默认 base-sepoliaGET /protected-svm$0.001网络由SVM_NETWORK决定SVM默认 solana-devnet这两条路由分别通过两次独立的paymentMiddleware调用挂载index.ts演示了同一应用中同时保护 EVM 与 SVM 两条链上的资源。此外还提供了联调用端点GET /health返回{ status: ok }POST /close用于优雅关闭服务见 test.config.json 中的health与close声明。未携带付款凭证访问受保护端点时服务返回 HTTP 402正文为支付要求README 原始示例{ 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 } }paymentRequirements各字段含义如下scheme支付方案此处为exact精确金额另一常见方案为uptonetwork结算网络标识如base、base-sepolia、solana-devnetmaxAmountRequired要求的最大金额按资产最小单位表示resource受保护资源的完整 URL客户端用它回放请求payTo收款地址maxTimeoutSeconds支付有效期默认 60 秒asset支付资产地址outputSchema/extra扩展字段此处为null。支付成功后的响应包含业务数据与结算凭证头// Body { report: { weather: sunny, temperature: 70 } } // Headers { X-PAYMENT-RESPONSE: ... // Encoded response object }其中X-PAYMENT-RESPONSE携带编码后的结算响应对象供客户端或后续审计方确认本次付款已入账。用示例客户端端到端联调服务端就绪后README 推荐用仓库自带的 fetch 或 axios 客户端验证完整流程Fetch 客户端cd ../clients/fetch # Ensure .env is setup pnpm install pnpm devAxios 客户端cd ../clients/axios # Ensure .env is setup pnpm install pnpm dev两个客户端对应的实现分别位于 e2e/legacy/clients/fetch/index.ts 与 e2e/legacy/clients/axios/index.ts它们都会演示三步联调首次请求不带支付头访问受保护端点拿到 402 与paymentRequirements处理支付要求根据paymentRequirements构造并签署支付凭证接入钱包/签名器带凭证二次请求在请求头中携带支付凭证得到 200 与真实业务数据。这一步验证的是 x402 的核心契约未支付先 402支付后放行整个过程中服务端不需要预存任何客户端会话状态。扩展付费端点路由配置详解README 给出了为应用增加更多付费端点的标准写法——把路由与价格统一配置进paymentMiddleware的第一参在 v1 API 中这是第二个参数// First, configure the payment middleware with your routes app.use( paymentMiddleware( payTo, { // Define your routes and their payment requirements GET /your-endpoint: { price: $0.10, network: base-sepolia, }, /premium/*: { price: { amount: 100000, asset: { address: 0xabc, decimals: 18, eip712: { name: WETH, version: 1, }, }, }, network: base-sepolia, }, }, ), ); // Then define your routes as normal app.get(/your-endpoint, (req, res) { res.json({ // Your response data }); }); app.get(/premium/content, (req, res) { res.json({ content: This is premium content, }); });这段示例揭示了 v1 路由配置的三种能力字符串价格price: $0.10表示按美元计价facilitator 会在结算时换算为网络原生资产如 USDC通配符路由/premium/*可以一次性保护/premium下的所有子路径指定代币资产当price改为对象时可通过amount最小单位数量与asset含address、decimals以及 EIP-712 域信息name/version精确指定收款代币例如 WETH。对应的 v1 类型定义可在 typescript/packages/legacy/x402-express/README.md 中查看RoutesConfig Recordstring, Price | RouteConfig其中RouteConfig由price、network与可选的configdescription、mimeType、maxTimeoutSeconds等组成。从源码看中间件的处理流程示例服务器虽然只有约 80 行代码但中间件内部做了大量工作。v1 的x402-express中间件职责可以概括为对照 v2 重构版 typescript/packages/http/express/src/index.ts 中的paymentMiddlewareFromHTTPServer理解路由匹配根据请求的path与method判断是否命中受保护路由未命中直接next()放行读取支付凭证从请求头中读取x-payment或payment-signature头校验与响应支付缺失或非法时返回 402 与paymentRequirements校验通过则进入路由处理缓冲响应并结算中间件会拦截res.writeHead/res.write/res.end/res.flushHeaders等待路由处理完毕后若业务响应状态码 400不执行结算原样回放缓冲的响应见 index.ts否则调用processSettlement完成链上结算并把结算结果写入响应头X-PAYMENT-RESPONSE后回放给客户端结算失败时丢弃缓冲内容并返回 402 或 502facilitator 边界错误归一化为 502见 sendFacilitatorError。另外中间件还支持setSettlementOverrides(res, { amount: 500 })这类部分结算覆盖partial settlement能力以及为浏览器请求自动渲染付费墙 UIx402/paywall可配置appName、appLogo、testnet等参数——这正是本文第一张配图中输入钱包、显示金额、Pay now界面的来源。从 v1 到 v2API 迁移要点由于x402-express已弃用官方建议迁移到 v2 的x402/express详见 docs/guides/migration-v1-to-v2.mdx 与 typescript/packages/http/express/README.md。两代 API 的核心差异如下维度v1x402-express本文v2x402/express中间件参数(payTo, routes, facilitator?, paywall?)(routes, resourceServer, paywallConfig?, paywall?, syncFacilitatorOnStart?)收款地址独立参数payTo移入每个路由的accepts.payTo支付方案内置 exact显式注册 scheme如new ExactEvmScheme()网络标识base-sepolia等短名CAIP-2 风格如eip155:84532v2 的迁移示例const facilitator new HTTPFacilitatorClient({ url: facilitatorUrl }); const resourceServer new x402ResourceServer(facilitator) .register(eip155:84532, new ExactEvmScheme()); app.use( paymentMiddleware( routes, // payTo 已在路由的 accepts 中声明 resourceServer, paywallConfig, // 可选 ), );如果你正从本文的 legacy 示例起步建议直接在 v2 架构上编写新代码本文示例的价值在于它以最小可运行形态完整展示了402 协商 → 支付 → 结算这一始终未变的协议内核。小结通过本示例服务器你可以零门槛跑通 x402 付费墙的完整闭环配置环境变量 → 启动 Express 服务 → 用 fetch/axios 客户端联调 → 观察 402 支付要求与结算响应头 → 按需扩展更多付费路由。从源码看中间件内部完成了路由匹配、凭证校验、响应缓冲、条件结算与失败兜底等关键逻辑这为理解 v2 中x402ResourceServerx402HTTPResourceServer的分层设计提供了很好的对照起点。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考