x402 支付协议实战使用 x402/axios 客户端访问受保护端点【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402导读本篇文章基于 x402 仓库中的 Axios 客户端示例讲解如何用x402/axios包在 TypeScript 应用中自动处理 HTTP 402Payment Required支付流程。你将学会如何初始化 x402 客户端并注册 EVM/SVM 支付方案scheme、如何用wrapAxiosWithPayment一行接入 Axios 实例、如何配置密钥与 RPC 环境变量并运行示例以及支付拦截器的底层实现原理。读完本文你可以直接在自己的 Axios 项目中集成基于 HTTP 的 x402 支付能力。x402 与x402/axios把支付变成 HTTP 的一部分x402 是一个构建在 HTTP 之上的互联网支付协议项目自述为A payments protocol for the internet. Built on HTTP.。它的核心思路是当服务器端资源需要付费时返回 HTTP 402 状态码和一组支付要求Payment Requirements客户端解析这些要求构造并签署支付载荷随后携带支付签名重发请求服务器验证后放行资源。x402/axios是这一机制在 Axios 生态的官方实现包。它不要求你手写任何 402 处理逻辑——只需要把已配置好的x402Client与 Axios 实例组合起来之后所有可能触发付费的请求都会被自动处理。仓库中的示例位于 examples/typescript/clients/axios对应包的源码实现位于 typescript/packages/http/axios。最小可运行示例从代码开始示例 README 给出了一段极其精简的核心代码展示了 x402 Axios 的最小接入方式import { x402Client, wrapAxiosWithPayment } from x402/axios; import { registerExactEvmScheme } from x402/evm/exact/client; import { privateKeyToAccount } from viem/accounts; import axios from axios; const client new x402Client(); registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) }); const api wrapAxiosWithPayment(axios.create(), client); const response await api.get(http://localhost:4021/weather); console.log(response.data);这段代码完成了三件关键的事创建支付客户端new x402Client()是 x402 客户端的核心入口负责在支付方案scheme注册表中按网络匹配签名器注册 EVM 精确支付方案registerExactEvmScheme用viem的privateKeyToAccount把私钥转成签名器并注册到eip155网络这样遇到 EVM 网络的支付要求时就能自动签名包装 Axios 实例wrapAxiosWithPayment(axios.create(), client)返回一个懂支付的 Axios 实例后续的api.get(...)如果遇到 402 响应会自动完成解析支付要求 → 构造支付载荷 → 重发请求的全流程。更完整的 builder 模式版本仓库中的 index.ts 是示例的实际运行入口比 README 中的片段更完整同时注册了 EVM 与 SVM 两种链的三种支付方案import { config } from dotenv; import { x402Client, wrapAxiosWithPayment, x402HTTPClient } from x402/axios; import { ExactEvmScheme } from x402/evm/exact/client; import { UptoEvmScheme } from x402/evm/upto/client; import { ExactSvmScheme } from x402/svm/exact/client; import { privateKeyToAccount } from viem/accounts; import { createKeyPairSignerFromBytes } from solana/kit; import { base58 } from scure/base; import axios from axios; config(); const evmPrivateKey process.env.EVM_PRIVATE_KEY as 0x${string}; const svmPrivateKey process.env.SVM_PRIVATE_KEY as string; const evmRpcUrl process.env.EVM_RPC_URL; const baseURL process.env.RESOURCE_SERVER_URL || http://localhost:4021; const endpointPath process.env.ENDPOINT_PATH || /weather; const url ${baseURL}${endpointPath}; async function main(): Promisevoid { const evmSigner privateKeyToAccount(evmPrivateKey); const svmSigner await createKeyPairSignerFromBytes(base58.decode(svmPrivateKey)); const rpcOptions evmRpcUrl ? { rpcUrl: evmRpcUrl } : undefined; const client new x402Client(); client.register(eip155:*, new ExactEvmScheme(evmSigner, rpcOptions)); client.register(eip155:*, new UptoEvmScheme(evmSigner, rpcOptions)); client.register(solana:*, new ExactSvmScheme(svmSigner)); const api wrapAxiosWithPayment(axios.create(), client); console.log(Making request to: ${url}\n); const response await api.get(url); const body response.data; console.log(Response body:, body); const paymentResponse new x402HTTPClient(client).getPaymentSettleResponse( name response.headers[name.toLowerCase()], ); console.log(\nPayment response:, paymentResponse); } main().catch(error { console.error(error?.response?.data?.error ?? error); process.exit(1); });与最小示例相比这个版本有几个值得注意的差异使用 builder 模式的client.register()以网络通配符 → 方案实例的形式逐个注册。eip155:*匹配所有 EVM 链solana:*匹配所有 Solana 网络同时注册 Exact 与 Upto 两类方案ExactEvmScheme用于精确金额支付UptoEvmScheme用于上限金额Upto支付。它们都接收可选的rpcOptions内含rpcUrl供链上读取使用SVM 签名器构造Solana 私钥通过base58.decode解码后用solana/kit的createKeyPairSignerFromBytes创建签名器支付结算响应请求成功后通过x402HTTPClient(client).getPaymentSettleResponse(...)从响应头解析出支付结算信息如链上交易哈希等便于日志记录或后续对账。前置条件Prerequisites在运行示例之前需要满足以下环境要求前置条件说明Node.js v20可通过 nvm 安装pnpm v10示例与整个 TypeScript monorepo 统一使用 pnpm 管理依赖一个运行中的 x402 服务器可参考 express 服务器示例默认监听http://localhost:4021EVM 和/或 SVM 私钥用于签署支付EVM 为0x开头的十六进制私钥SVM 为 base58 编码的私钥注意仅当目标资源是付费端点时才需要真实私钥若想先跑通流程可以先用一个无支付保护的服务器验证请求链路再启动带 402 响应的付费端点。安装与构建示例依赖 TypeScript monorepo 中的x402/axios、x402/evm、x402/svm等 workspace 包因此需要从 examples 根目录统一安装并构建cd ../../ pnpm install pnpm build cd clients/axios在 monorepo 中安装完成后x402/axios会以 workspace 链接方式解析见 package.json 中的x402/axios: workspace:*。示例的start脚本使用tsx直接运行 TypeScriptscripts: { start: tsx index.ts, dev: tsx index.ts builder-pattern, dev:hooks: tsx index.ts hooks, dev:mechanism-helper-registration: tsx index.ts mechanism-helper-registration }除start外示例还预留了devbuilder 模式、dev:hooks支付生命周期钩子、dev:mechanism-helper-registration机制辅助注册等多个演示入口对应 高级示例 中讲解的各种进阶用法。环境变量配置复制示例自带的.env-local模板cp .env-local .env.env-local 的内容如下EVM_PRIVATE_KEY SVM_PRIVATE_KEY RESOURCE_SERVER_URLhttp://localhost:4021 ENDPOINT_PATH/weather按 README 说明环境变量分为两类必需环境变量EVM_PRIVATE_KEY— EVM 支付使用的以太坊私钥0x前缀十六进制字符串SVM_PRIVATE_KEY— SVMSolana支付使用的 base58 编码私钥。可选环境变量EVM_RPC_URL— 链上读取使用的 JSON-RPC 端点例如https://sepolia.base.org。设置后会在构造ExactEvmScheme/UptoEvmScheme时传入{ rpcUrl }对应 index.ts 中的rpcOptions从而启用汽油费赞助类扩展EIP-2612 与 ERC-20 授权。除此之外从.env-local模板可以看到还有两个可调整的运行参数RESOURCE_SERVER_URL— 目标 x402 服务器地址默认http://localhost:4021ENDPOINT_PATH— 请求的资源路径默认/weather。最终请求 URL 由二者拼接而成${baseURL}${endpointPath}。这意味着你可以不改代码仅通过环境变量把请求指向任意 x402 服务器和任意付费资源。运行客户端pnpm start运行后客户端会向配置的 URL默认http://localhost:4021/weather发起请求。若服务器是受 x402 保护的端点首次请求会收到 402 响应随后 Axios 拦截器自动完成支付并重发最终打印响应体Response body与支付结算响应Payment response。若出错如密钥缺失、网络不通错误会被main().catch(...)捕获优先输出服务器返回的error字段。底层原理wrapAxiosWithPayment如何工作wrapAxiosWithPayment的实现位于 typescript/packages/http/axios/src/index.ts。它本质上是一个Axios 响应拦截器核心流程如下拦截 402 响应对每个请求注册响应拦截器仅当error.response.status 402时才进入支付流程其他错误原样透传解析支付要求优先从响应头读取v2 协议其次从响应体PaymentRequired读取v1 兼容通过x402HTTPClient.getPaymentRequiredResponse(getHeader, body)完成其中getHeader做了大小写不敏感的头查找执行支付前钩子调用httpClient.handlePaymentRequired(paymentRequired)如果钩子返回了可用的头信息例如汽油费赞助扩展注入的授权头会先携带这些头重试一次仍返回 402 才继续走支付逻辑构造支付载荷调用client.createPaymentPayload(paymentRequired)生成签名后的支付载荷再经encodePaymentSignatureHeader编码为请求头防死循环重试重试前给请求配置打上__is402Retry标记。若再次拦截到的 402 请求已带此标记则直接拒绝避免402 → 支付 → 402 → 支付无限循环设置 CORS 暴露头自动添加Access-Control-Expose-Headers: PAYMENT-RESPONSE,X-PAYMENT-RESPONSE确保浏览器环境下客户端能读取支付响应头重发请求携带支付头重发原请求成功则返回最终响应。这个流程与typescript/packages/http/axios/src/index.test.ts中的单元测试一一对应——测试中构造了validPaymentRequired/validPaymentPayload夹具分别验证了非 402 错误透传、402 重试成功、已标记__is402Retry的请求不再重试、解析/创建支付失败时报错等路径是理解该拦截器行为的最佳参考。两种包装方式x402/axios包对外提供两个入口详见 包文档wrapAxiosWithPayment(axiosInstance, client)接收一个已注册好方案的x402Client实例或直接传入x402HTTPClient。适合需要精细控制注册顺序、网络通配符优先级、生命周期钩子的场景。wrapAxiosWithPaymentFromConfig(axiosInstance, config)基于配置对象便捷创建客户端配置项包括配置项说明schemes方案注册数组每项包含network网络标识如eip155:8453、solana:mainnet支持eip155:*通配符、client方案客户端实现如ExactEvmScheme、ExactSvmScheme、x402Version可选协议版本默认 2设为 1 兼容旧版paymentRequirementsSelector可选函数当服务器返回多个支付选项时由它挑选其中一个多链支持与自定义支付选择器同一个 Axios 实例可以同时注册 EVM 与 SVM 方案支付拦截器会根据 402 响应中的网络标识自动匹配const api wrapAxiosWithPaymentFromConfig(axios.create(), { schemes: [ { network: eip155:8453, client: new ExactEvmScheme(evmAccount) }, // Base 主网 { network: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1, client: new ExactSvmScheme(svmSigner) }, // Solana devnet ], });如果服务器对同一资源提供多种支付方式可以用paymentRequirementsSelector自定义选择策略例如选最便宜const selectCheapestOption: SelectPaymentRequirements (version, accepts) { if (!accepts || accepts.length 0) { throw new Error(No payment options available); } const sorted [...accepts].sort((a, b) BigInt(a.value) - BigInt(b.value)); return sorted[0]; };进阶方向当前示例仅覆盖了最基础的接入。想进一步了解以下能力可直接阅读 高级客户端示例Builder 模式细粒度注册client.register(eip155:*, ...)与client.register(eip155:1, ...)同时存在时更具体的网络模式优先于通配符可用于主网与测试网使用不同签名器的场景支付生命周期钩子onBeforePaymentCreation支付前校验可中止、onAfterPaymentCreation支付成功后打点/入库、onPaymentCreationFailure支付失败后的恢复逻辑客户端网络偏好通过自定义paymentRequirementsSelector实现优先用某条链支付、否则自动回退的策略适合钱包类 UI 的用户偏好设置。小结x402/axios示例展示了 x402 协议让支付成为 HTTP 原生能力的设计哲学客户端侧无需关心 402 状态码的底层细节只需注册签名器、包装一次 Axios 实例剩余的工作全部由拦截器完成。无论你是要保护自己的付费 API还是想在应用中消费这类 API本文所述的接入流程与源码实现都可以直接复用。更多示例fetch、httpx、Go、Python 等客户端可继续浏览 examples/typescript/clients 目录下的其他子项目。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
