English Docs

@xpaylabs/x402 — HTTP 402 微支付买家 SDK

import { pay, signers } from '@xpaylabs/x402'

const signer = signers.fromPrivateKey(process.env.PRIVATE_KEY)
const result = await pay('https://api.example.com/paid-endpoint', { signer })

console.log(result.data)       // 响应数据
console.log(result.paymentId)  // 链上交易 ID（有则表示已结算）

适用人群

角色	使用方式
AI Agent 开发者	Agent 动态调用付费 LLM、数据源、工具 — 无需预配 API Key
Node.js 后端开发者	无需商户资质或 KYC，直接调用第三方付费 API
浏览器 dApp 开发者	用户通过 MetaMask 为高级功能或计算资源付费
自动化脚本开发者	爬虫、监控、CI/CD 按次付费调用
SaaS 平台	将 x402 作为 API 市场计费层集成
IoT / 机器对机器	传感器、边缘设备自动为数据中继或算力付费
游戏开发者	游戏内微支付、道具购买、跳过等待，用户无需 Gas
内容创作者	付费文章、视频、播客 — 按次查看，无订阅捆绑
研究者 / 学者	按数据集或 API 调用付费，无需走采购流程
自由职业者 / 平台工人	微任务结算、按小时赚取 USDC，即时到账

使用场景

AI / LLM：Agent 调用付费 LLM 端点，按 token 用量用 USDC 结算，无需管理 API Key
数据 API：金融数据、天气、地理位置、市场研究的按查询付费
计算资源：图片生成、视频处理、ML 模型推理的按次收费
内容付费：付费文章、报告、媒体文件的按次查看
基础设施：DNS、CDN、监控等 API 的按请求付费
IoT / DePIN：传感器数据上传、存储证明、网络带宽的机器对机器微支付
游戏内经济：购买道具、体力、跳过广告 — 即时链上结算，无需 Gas
Agent 间结算：AI Agent A 调用 Agent B 的服务，自动 USDC 转账
预测市场：每条预测投注几美分，链上即时开奖结算
实时数据流：按秒付费订阅实时价格、交易对、新闻流
API 编排：一次用户请求背后，自动调用多个付费微 API 并逐一结算
训练数据市场：每条标注样本付费，买多少付多少
去订阅制内容：零散阅读，无月费捆绑，按篇付费

为什么用 @xpaylabs/x402？

痛点	xpay 方案
传统支付要 KYC、签合同、对接银行	链上 USDC 即时结算，零门槛
x402 官方 SDK 要装 3 个包，手动注册 scheme	一个 `npm install`，一行 `pay()`
区块链签名流程复杂	`signers.*` 工厂一行创建签名器
多链适配麻烦	v0.1 EVM（Base / Polygon / Arbitrum / World），v0.2 扩展 Solana

快速开始

1. 创建签名器

import { signers } from '@xpaylabs/x402'

// 服务端：私钥签名（0x 前缀可选）
const signer = signers.fromPrivateKey(process.env.PRIVATE_KEY)

// 服务端：助记词签名
const signer = signers.fromMnemonic('test test test...', { chain: 'evm' })

// 浏览器：MetaMask 等 EIP-1193 钱包
const signer = await signers.browserWallet(window.ethereum)
console.log(signer.address)  // 0x...
console.log(signer.chain)    // 'evm'

2. 支付 API

单次支付：

const result = await pay('https://api.example.com/data', {
  signer,
  request: {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: 'hello' }),
  },
  hooks: {
    onBeforePayment: async ({ amount, network }) => {
      console.log(`支付 ${amount}，网络 ${network}`)
    },
    onAfterPayment: async ({ transaction }) => {
      console.log(`已结算: ${transaction}`)
    },
  },
})

复用客户端：

const api = new XPayClient({ signer })

await api.get('https://api.example.com/users')
await api.post('https://api.example.com/analyze', {
  request: { body: JSON.stringify({ text: 'hello' }) },
})
await api.put('https://api.example.com/resource/1')
await api.delete('https://api.example.com/resource/1')

3. 自定义 Fetch

适用于 Node 18 以下或需要代理的场景：

import { fetch } from 'undici'

await pay(url, { signer, fetchFn: fetch })

工作原理

pay(url, { signer })
  → GET /url
    ↓
  200? 直接返回数据，无支付
    ↓
  402 + PAYMENT-REQUIRED 头?
    → SDK 解析 price / network / scheme
    → signer 本地签名（私钥不离开进程）
    → 重试请求 + PAYMENT-SIGNATURE 头
    → 卖家验证 → Facilitator 上链结算
    → 返回 200 + x-payment-id

支付方案

x402 定义了三种支付方案，SDK 自动支持 exact 和 upto：

方案	名称	适用场景
`exact`	固定价格	已知成本的 API 调用、文件下载（EIP-3009，Gas 赞助）
`upto`	按用量计费	LLM token、带宽、计算时间（Permit2，按实际扣费）
`batch-settlement`	批量结算	高频微支付（v0.1 暂不支持）

支持链

链	状态	方案
EVM（Base / Polygon / Arbitrum / World）	✅ v0.1	EIP-3009 (exact) / Permit2 (upto)
Solana	🚧 v0.2	SPL Token
Algorand / Stellar / Aptos / TON / Hedera	🔮 后续	—

API 参考

pay()

async function pay<T = any>(
  url: string,
  options: PayOptions,
): Promise<PayResponse<T>>

signers

import { signers } from '@xpaylabs/x402'

signers.fromPrivateKey(key: string): Signer
signers.fromMnemonic(phrase: string, options?: { chain?: Chain }): Signer
signers.browserWallet(provider: EIP1193Provider): Promise<Signer>

XPayClient

new XPayClient({ signer, fetchFn?: typeof fetch })

client.pay<T>(url, opts?): Promise<PayResponse<T>>
client.get<T>(url, opts?): Promise<PayResponse<T>>
client.post<T>(url, opts?): Promise<PayResponse<T>>
client.put<T>(url, opts?): Promise<PayResponse<T>>
client.delete<T>(url, opts?): Promise<PayResponse<T>>

PayOptions

interface PayOptions {
  signer: Signer
  request?: {
    method?: string
    headers?: Record<string, string>
    body?: BodyInit | null
  }
  hooks?: {
    onBeforePayment?: (ctx: { amount: string; network: string }) =>
      Promise<{ abort?: boolean; reason?: string } | void>
    onAfterPayment?: (ctx: { transaction?: string }) => Promise<void>
  }
  fetchFn?: typeof fetch
}

PayResponse

{
  data: T | null,          // JSON 响应体（非 JSON 返回 null）
  response: Response,      // 原始 Response 对象
  paymentId?: string       // 链上交易 hash（有则表示已结算）
}

错误码

错误码	说明
`INVALID_SIGNER`	Signer address 为空
`UNSUPPORTED_CHAIN`	不支持的链
`PAYMENT_FAILED`	Facilitator 拒绝或链上交易失败
`NETWORK_ERROR`	网络请求失败
`HOOK_ABORTED`	被 onBeforePayment 拦截
`SIGNER_REQUIRED`	未提供 signer
`CHAIN_NOT_SUPPORTED`	卖家要求的链不支持
`NO_VALID_SCHEME`	卖家返回的 scheme 不支持

常见问题

需要理解 x402 协议吗？

不需要。SDK 自动处理 402 握手、签名、重试，开发者只需 pay(url, { signer })。

需要区块链开发经验吗？

不需要。signers.fromPrivateKey(key) 一行创建签名器，剩余流程 SDK 自动完成。

钱给了谁？

买家签名授权 USDC → Facilitator 验证上链 → USDC 到卖家钱包。Facilitator 由卖家配置，买家无需关心。

私钥安全吗？

签名器	签名位置
`fromPrivateKey(key)`	当前进程内（viem 本地签名）
`fromMnemonic(phrase)`	当前进程内（viem 本地签名）
`browserWallet(provider)`	浏览器插件钱包内（MetaMask 弹窗确认）

私钥永远不离开当前进程或钱包。

如何获取测试网 USDC？

CDP Faucet 领取 Base Sepolia 测试网 ETH + USDC。

如果 API 不需要支付怎么办？

服务端返回 200 时，SDK 直接返回数据，不触发支付流程。

环境要求

Node.js >= 18 或现代浏览器
Base Sepolia 测试网 USDC（CDP Faucet 领取）
一个 x402 兼容的卖家 API 端点

安装

npm install @xpaylabs/x402
# 或
yarn add @xpaylabs/x402

pnpm add @xpaylabs/x402

链接

仓库

GitHub: yan253319066/XPayLabs-x402 Gitee（镜像）: XPayLabs/XPayLabs-x402

许可证

MIT

FilesExpand file tree

README.zh-CN.md

Latest commit

History