SDK API 参考

本参考文档覆盖 Avery SDK Agent 支付工具和直接 x402 付费 HTTP 调用背后的公开 API。

所有公开 SDK API 都从 @averyso/alpha 导出。不要从 packages/sdk/src/... 内部路径导入。

Framework-neutral payment runtime 类型同样由根入口导出。Express、Hono 和 Next.js adapter 使用独立 subpath，详见 Middleware API 参考。

支付功能不需要 Avery 账号。包仍通过 @averyso/alpha 安装和导入，但运行时支付 执行使用本地 x402 签名、你配置的钱包/私钥、RPC URL 和目标 x402 端点。Provider-side 结算可能在本地完成，也可能通过 provider 的 facilitator 完成，但 Avery SDK 不配置 这条路径。你不需要 Avery 账号、Avery API key、Avery 托管服务或注册。

import {
  AlipayAIPayClient,
  AlipayAIPayConfigError,
  AlipayAIPayMachinePayClient,
  X402Client,
  X402ConfigError,
  X402Error,
  X402Networks,
  X402PaymentError,
  WeiXinAIPayClient,
  WeiXinAIPayConfigError,
  buildAlipayAIPayPaymentNeededHeader,
  buildWeiXinAIPayPreorderRequest,
  encodeWeiXinAIPaymentRequired,
  parseAlipayAIPayPaymentProofHeader,
  resolveX402Network,
  signWeiXinAIPayPreorder,
  x402MastraTool,
  x402tool,
} from "@averyso/alpha";

WeiXinAIPayClient

用于在 server runtime 中构建并发送 WeiXinAI Pay preorder 请求。

const client = new WeiXinAIPayClient({
  developerId: process.env.WEIXIN_AI_DEVELOPER_ID!,
  publicKeyId: process.env.WEIXIN_AI_PUBLIC_KEY_ID!,
  privateKey: process.env.WEIXIN_AI_SM2_PRIVATE_KEY!,
});

构造函数签名：

new WeiXinAIPayClient(options);

privateKey 必须是 32 字节 SM2 私钥的 hex 字符串，可以带或不带 0x 前缀。该私钥应只保存在服务端。

WeiXinAIPayClientOptions

interface WeiXinAIPayClientOptions {
  developerId: string;
  publicKeyId: string;
  privateKey: string;
  developerPlatform?: string;
  fetch?: typeof fetch;
  endpoint?: string;
  logLevel?: LogLevel;
  logger?: Logger;
  signatureEncoding?: "der" | "raw";
}

• developerId：WeiXinAI Pay developer identifier，会作为 developer_id 发送。
• publicKeyId：WeiXinAI Pay public key identifier，会作为 pub_key_id 发送。
• privateKey：本地签名使用的 SM2 私钥。
• developerPlatform：会作为 developer_platform 发送，默认 "WXPAY"。
• fetch：自定义 fetch 实现。如果没有传入且 globalThis.fetch 不存在，构造 函数会抛出 WeiXinAIPayConfigError。
• endpoint：preorder 端点，默认 https://payapp.weixin.qq.com/palmpayminiapp/clawagentpay/preorder。
• logLevel：默认 logger 的最低输出级别，默认 "info"。
• logger：自定义诊断 logger，需要提供 debug、info、warn、error 方法。
• signatureEncoding：默认 "der"。设置为 "raw" 时会发送 raw r || s 签名。

preorder(paymentRequired, options?)

const result = await client.preorder(
  {
    appid: "wx-miniapp",
    mchid: "1900000109",
    out_trade_no: "order-1001",
    description: "AI agent request",
    amount: {
      total: 100,
      currency: "CNY",
    },
  },
  {
    signal: abortController.signal,
  },
);

result.paymentCode;
result.rawResponse.payment_code;

interface WeiXinAIPayPreorderOptions {
  signal?: AbortSignal;
  timestamp?: string;
  nonceStr?: string;
  developerPlatform?: string;
  endpoint?: string;
  signatureEncoding?: "der" | "raw";
}

interface WeiXinAIPayPreorderResult {
  paymentCode: string;
  rawResponse: {
    payment_code: string;
  };
}

timestamp 默认是 Unix seconds 字符串。nonceStr 默认是 crypto-secure random hex string。请求会以 POST JSON 发送，并带上 Content-Type: application/json。

Request Builder

如果由其他 HTTP 层负责发送请求，可以直接使用底层 builder：

const body = buildWeiXinAIPayPreorderRequest(paymentRequired, {
  developerId: process.env.WEIXIN_AI_DEVELOPER_ID!,
  publicKeyId: process.env.WEIXIN_AI_PUBLIC_KEY_ID!,
  privateKey: process.env.WEIXIN_AI_SM2_PRIVATE_KEY!,
  timestamp: "1735689600",
  nonceStr: "abcdef0123456789abcdef0123456789",
});

返回的 JSON body wire shape 如下：

interface WeiXinAIPayPreorderRequest {
  signature_type: "WEIXINAIPAY-SM2-WITH-SM3";
  developer_platform: string;
  developer_id: string;
  pub_key_id: string;
  nonce_str: string;
  timestamp: string;
  signature: string;
  payment_required: string;
}

encodeWeiXinAIPaymentRequired(value) 会执行 JSON.stringify(value)，并将 UTF-8 JSON bytes 做 Base64 编码。signWeiXinAIPayPreorder(input, options) 严格使用 WeiXinAI 签名规则：

const signString = `${timestamp}\n${nonceStr}\n${paymentRequired}\n`;

SDK 会计算该字符串的 SM3 digest，用 SM2 对 digest 签名，并将签名字节做 Base64 编码。

AlipayAIPayClient

实现支付宝 AI 按量付费（Alipay Agent 支付的基于 402 的 A2M 方案）的商家侧 流程：为 402 Payment Required 响应构建带签名的 Payment-Needed 账单、通过 支付宝 OpenAPI 网关验证 Payment-Proof 支付凭证，并在资源交付后发送履约 回执。

const client = new AlipayAIPayClient({
  appId: process.env.ALIPAY_APP_ID!,
  privateKey: process.env.ALIPAY_APP_PRIVATE_KEY!,
  alipayPublicKey: process.env.ALIPAY_PUBLIC_KEY,
});

privateKey 是支付宝应用 RSA 私钥，可以是 PEM 字符串，也可以是从支付宝 控制台复制的裸 Base64 PKCS#8/PKCS#1 内容（也接受 Node KeyObject）。该私钥 应只保存在服务端。

AlipayAIPayClientOptions

interface AlipayAIPayClientOptions {
  appId: string;
  privateKey: string | KeyObject;
  alipayPublicKey?: string | KeyObject;
  appAuthToken?: string;
  gatewayEndpoint?: string;
  fetch?: typeof fetch;
  logLevel?: LogLevel;
  logger?: Logger;
}

• appId：支付宝应用 ID。会作为 app_id 发送，同时是 Payment-Needed 账单中 seller_app_id 的默认值。
• privateKey：应用 RSA 私钥，用于账单和网关请求的 RSA2（SHA256withRSA） 签名。
• alipayPublicKey：支付宝公钥。提供后会验证网关响应签名，验签失败抛出 AlipayAIPayResponseError。
• appAuthToken：第三方代调用的授权 token，会作为 app_auth_token 发送。
• gatewayEndpoint：支付宝 OpenAPI 网关，默认 https://openapi.alipay.com/gateway.do。
• fetch、logLevel、logger：语义与其他 client 一致。

buildPaymentNeededHeader(input)

为 402 Payment Required 响应构建 Base64URL（无 padding）编码的 Payment-Needed header。账单中的 seller_signature 是对 amount、 currency、goods_name、out_trade_no、pay_before、resource_id、 seller_id、service_id 按 key 字典序拼接 key=value&... 后的 RSA2 签名。 加签只在本地完成，不会请求支付宝服务端。

const { header, paymentNeeded } = client.buildPaymentNeededHeader({
  outTradeNo: "ORDER_1739836600000_abc123",
  amount: "0.01",
  resourceId: "/market/antgroup/trend",
  payBefore: "2026-03-25T12:00:00+08:00",
  sellerId: "2088123456789012",
  sellerName: "测试商家",
  goodsName: "AI 生成内容服务",
  serviceId: "service_ai_content_001",
});

// 返回 HTTP 402，并设置 `Payment-Needed: ${header}`

currency 默认 "CNY"，seller_unique_id_key 固定为 "seller_id"， sellerAppId 默认使用 client 的 appId（第三方代调用时需显式传入三方应用的 app_id）。

parsePaymentProofHeader(header)

解码 Payment-Proof 请求头（标准 Base64 或 Base64URL，带不带 padding 均可） 并校验分层结构。

const proof = client.parsePaymentProofHeader(request.headers["payment-proof"]);

proof.paymentProof; // protocol.payment_proof
proof.tradeNo; // protocol.trade_no
proof.clientSession; // method.client_session，可选

格式非法时抛出 AlipayAIPayRequestError。

verifyPayment(input, options?)

发送签名后的网关请求调用 alipay.aipay.agent.payment.verify。可以直接传入 解析后的 Payment-Proof 对象。

const result = await client.verifyPayment(proof, {
  expect: {
    amount: "0.01",
    outTradeNo: order.outTradeNo,
    resourceId: "/market/antgroup/trend",
  },
});

if (!result.verified) {
  // 返回新的 402 Payment-Needed 账单
}

interface AlipayAIPayVerifyPaymentOptions {
  signal?: AbortSignal;
  timestamp?: string;
  gatewayEndpoint?: string;
  appAuthToken?: string;
  expect?: {
    amount?: string;
    outTradeNo?: string;
    resourceId?: string;
  };
}

interface AlipayAIPayPaymentVerifyResult {
  active: boolean;
  amount: string;
  outTradeNo: string;
  resourceId: string;
  tradeNo: string;
  verified: boolean;
  mismatches: string[];
  rawResponse: AlipayAIPayPaymentVerifyWireResponse;
}

只有当 active 为 true 且提供的每个 expect 字段都与网关响应一致时， verified 才为 true（expect 按字符串精确比较）。业务失败（例如 PAYMENT_PROOF_NOT_FOUND）会抛出 AlipayAIPayResponseError，details 中 带有 code、subCode、subMsg。trade_no 的防重复履约仍需由商家侧 持久化保证。

confirmFulfillment(tradeNo, options?)

资源交付后调用 alipay.aipay.agent.fulfillment.confirm。可以直接传交易号 字符串，也可以传 { tradeNo }。

await client.confirmFulfillment(result.tradeNo);

Request Builders

如果由其他 HTTP 层负责发送网关请求，可以使用底层 helper： buildAlipayAIPayGatewayRequest() 为任意 OpenAPI method 返回签名后的表单 参数、body 和 sign content；signAlipayAIPayBill() 和 alipayAIPayBillSignContent() 暴露账单加签； parseAlipayAIPayGatewayResponse() 解析并按需验签网关 Response； alipayAIPayGatewayTimestamp() 生成网关要求的 UTC+8 yyyy-MM-dd HH:mm:ss 时间戳。

错误类型与其他 client 保持同样的层级：AlipayAIPayError 是基类， AlipayAIPayConfigError 覆盖配置和密钥错误，AlipayAIPayRequestError 覆盖 请求构建和传输失败，AlipayAIPayResponseError 携带 HTTP status 以及网关 code/sub_code 详情。

AlipayAIPayMachinePayClient

实现支付宝 AI Pay 402 协议的买方出站重试。它与 AlipayAIPayClient 有意保持 独立：不会构建或解析支付宝账单、不会调用商家网关 API，也不会返回 x402 的 EndpointResult。

const client = new AlipayAIPayMachinePayClient({
  payer: {
    createPaymentProof: ({ paymentNeeded, request, signal }) =>
      buyerPaymentPolicy.authorize({ paymentNeeded, request, signal }),
  },
});

const response = await client.fetch("https://merchant.example.test/report", {
  method: "POST",
  body: JSON.stringify({ topic: "payments" }),
});

AlipayAIPayMachinePayClientOptions

interface AlipayAIPayMachinePayer {
  createPaymentProof(input: {
    paymentNeeded: string;
    request: { url: string; method: string };
    signal?: AbortSignal;
  }): Promise<{ paymentProofHeader: string }>;
}

interface AlipayAIPayMachinePayClientOptions {
  payer: AlipayAIPayMachinePayer;
  fetch?: typeof fetch;
  logLevel?: LogLevel;
  logger?: Logger;
}

payer 为必填项，也是宿主应用的 policy boundary：应校验 paymentNeeded 中 代表的商户和金额、按需取得用户确认，并返回这个请求已获授权的原始 Payment-Proof header 值。SDK 不提供默认 payer、不调用支付宝 CLI，也不会根据 商户凭据推导买方凭证。此出站 client 不需要商户 appId 或 RSA 私钥。

fetch 默认使用 globalThis.fetch。logger 和 logLevel 使用共享诊断契约。 日志仅包含 request method、URL、status 和 error type，不包含 Payment-Needed 或 Payment-Proof 值。

fetch(input, init?)

fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>

接受标准 Fetch API request input，返回原始 response。付款决策前请求会先执行一次：

1. 非 402 response 原样返回。
2. 402 缺少非空 Payment-Needed header 时原样返回。
3. 原始 request 已携带 Payment-Proof 时，402 原样返回，client 不会覆盖它。
4. 其他情况下，原始 challenge header 和有效 request URL、method、abort signal 会传给 payer.createPaymentProof()。
5. 非空 paymentProofHeader 会写入可重放 request 并仅发送一次。第二个 response 即使仍为 402 也会原样返回。

request 构造、proof 创建和重放失败会抛出 AlipayAIPayRequestError，error message 和日志都不会包含 payment header 值。Request body 会为这一次重试重放，普通 headers 与 HTTP method 会保持不变。

X402Client

用于支付并调用 x402-protected HTTP 端点。

const client = new X402Client(process.env.X402_PRIVATE_KEY!, {
  network: X402Networks.baseSepolia,
  rpcUrl: process.env.X402_RPC_URL,
});

构造函数签名：

new X402Client(privateKey, options);

EVM 网络的 privateKey 必须是 32 字节 hex 字符串，可以带或不带 0x 前缀。Solana 网络的 privateKey 必须是 base58 编码的 64 字节 Solana secret key。

X402ClientOptions

interface X402ClientOptions {
  network: X402NetworkInput;
  logLevel?: LogLevel;
  logger?: Logger;
  fetch?: typeof fetch;
  maxAmount?: bigint;
  rpcUrl?: string;
}

• network：必填 x402 网络。可传 X402Networks 常量、friendly name、primary slug，或原始 CAIP-2 Network 字符串。
• logLevel：默认 logger 的最低输出级别，默认 "info"。
• logger：自定义 logger，需要提供 debug、info、warn、error 方法。
• fetch：自定义 fetch 实现。如果没有传入且 globalThis.fetch 不存在，构造 函数会抛出 X402ConfigError。
• maxAmount：默认支付上限，默认 100000n。
• rpcUrl：可选 RPC URL，会传给 payment scheme。

这里有意没有 facilitator 选项。X402ClientOptions 配置 buyer-side wallet、 network、cap、fetch、logging 和 RPC 行为。Resource server 控制它接受的资产、 payment scheme、定价和 provider-side 结算路径。

maxAmount 是原子单位的支付上限，不是十进制字符串。

网络选择

new X402Client(process.env.X402_PRIVATE_KEY!, {
  network: "Base Sepolia",
});

new X402Client(process.env.X402_PRIVATE_KEY!, {
  network: X402Networks.baseSepolia,
});

resolveX402Network("base-sepolia"); // "eip155:84532"

client.network 始终返回标准化后的 CAIP-2，因此 new X402Client(key, { network: "Base Sepolia" }).network 是 "eip155:84532"。既有的原始 CAIP-2 输入，例如 "eip155:84532"，仍然可用。

friendly name、primary slug 和内置 alias 会先 trim、合并连续空白并忽略大小写后 匹配。原始 eip155:* CAIP-2 值会继续透传以保持兼容；原始 Solana CAIP-2 值 必须是下表中受支持的 Solana 条目之一。

const X402Networks: {
  solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
  base: "eip155:8453";
  polygon: "eip155:137";
  xLayer: "eip155:196";
  peaq: "eip155:3338";
  sei: "eip155:1329";
  skaleBase: "eip155:1187947933";
  kiteAI: "eip155:2366";
  arbitrum: "eip155:42161";
  solanaDevnet: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
  baseSepolia: "eip155:84532";
  avalancheFuji: "eip155:43113";
  polygonAmoy: "eip155:80002";
  xLayerTestnet: "eip155:1952";
  seiTestnet: "eip155:713715";
  skaleBaseSepolia: "eip155:324705682";
  arbitrumSepolia: "eip155:421614";
};

type X402NetworkInput = X402NetworkName | X402NetworkSlug | Network | string;

function resolveX402Network(input: X402NetworkInput): Network;

内置 friendly name 和 primary slug：

Friendly Name	Primary Slug	CAIP-2
Solana Mainnet	solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Base Mainnet	base	eip155:8453
Polygon Mainnet	polygon	eip155:137
xLayer Mainnet	xlayer	eip155:196
Peaq Mainnet	peaq	eip155:3338
Sei Mainnet	sei	eip155:1329
SKALE Base	skale-base	eip155:1187947933
KiteAI Mainnet	kiteai	eip155:2366
Arbitrum One	arbitrum	eip155:42161
Solana Devnet	solana-devnet	solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
Base Sepolia	base-sepolia	eip155:84532
Avalanche Fuji	avalanche-fuji	eip155:43113
Polygon Amoy	polygon-amoy	eip155:80002
xLayer Testnet	xlayer-testnet	eip155:1952
Sei Testnet	sei-testnet	eip155:713715
SKALE Base Sepolia	skale-base-sepolia	eip155:324705682
Arbitrum Sepolia	arbitrum-sepolia	eip155:421614

属性

client.network;
client.maxAmount;

• network：标准化后的 CAIP-2 Network。
• maxAmount：client 默认支付上限。

call(endpoint, init?, opts?)

const result = await client.call(
  "https://api.example.com/weather",
  { query: { city: "Tokyo" } },
  { maxAmount: 50_000n },
);

默认情况下，call() resolve 为 EndpointResult。设置 throwOnError: true 后，失败结果会抛出 X402PaymentError。

await client.call(
  "https://api.example.com/weather",
  { query: { city: "Tokyo" } },
  { throwOnError: true },
);

interface X402CallOptions {
  signal?: AbortSignal;
  maxAmount?: bigint;
  throwOnError?: boolean;
}

maxAmount 可以在 client、单次 call 或 x402tool() 上设置。越具体的配置优先级 越高。

x402tool(config)

创建一个兼容 Vercel AI SDK ToolSet 的 tool，底层调用 x402 端点。

import { jsonSchema } from "ai";
import { X402Client, X402Networks, x402tool } from "@averyso/alpha";

const client = new X402Client(process.env.X402_PRIVATE_KEY!, {
  network: X402Networks.baseSepolia,
  rpcUrl: process.env.X402_RPC_URL,
});

const tools = {
  getWeather: x402tool<{ city: string }>({
    client,
    description: "Get current weather for a city.",
    inputSchema: jsonSchema({
      type: "object",
      properties: {
        city: { type: "string" },
      },
      required: ["city"],
      additionalProperties: false,
    }),
    endpoint: "https://api.example.com/weather",
    maxAmount: 50_000n,
  }),
};

endpoint 可以是静态值：

x402tool({
  client,
  inputSchema,
  endpoint: "https://api.example.com/weather",
});

也可以根据输入动态生成：

x402tool<{ city: string }>({
  client,
  inputSchema,
  endpoint: (input) => ({
    url: "https://api.example.com/weather",
    query: { city: input.city },
  }),
});

没有提供 request 时，tool input 会自动映射：

• GET、HEAD、DELETE 的 plain object input 会加入 query string。
• POST、PUT、PATCH 的 input 会作为 JSON body 发送。

提供 request 后，自动 input mapping 会被禁用：

x402tool<{ prompt: string }>({
  client,
  inputSchema,
  endpoint: "https://api.example.com/summarize",
  request: (input) => ({
    method: "POST",
    body: { text: input.prompt },
  }),
});

没有 execute 时，tool 返回 EndpointResult。提供 execute 时，该函数接收 { endpoint, input }，可返回更适合模型消费的值：

x402tool<{ city: string }, { forecast: unknown }>({
  client,
  inputSchema,
  endpoint: "https://api.example.com/weather",
  execute: ({ endpoint }) => ({
    forecast: endpoint.kind === "success" ? endpoint.body : null,
  }),
});

X402ToolConfig

type X402ToolConfig<INPUT, OUTPUT = EndpointResult> = {
  client: X402Client;
  endpoint: EndpointInput | ((input: INPUT) => EndpointInput);
  request?: (
    input: INPUT,
  ) =>
    | EndpointRequestInit
    | EndpointConfig
    | undefined
    | PromiseLike<EndpointRequestInit | EndpointConfig | undefined>;
  maxAmount?: bigint;
  throwOnError?: boolean;
  execute?: (
    context: { endpoint: EndpointResult; input: INPUT },
    options: X402ToolExecutionOptions,
  ) => OUTPUT | PromiseLike<OUTPUT>;
};

配置还接受 X402Tool 实现的 AI SDK 风格字段，例如 description、title、 inputSchema、outputSchema、needsApproval、strict 和输入流回调。

X402ToolExecutionOptions

interface X402ToolExecutionOptions {
  toolCallId: string;
  messages: unknown[];
  abortSignal?: AbortSignal;
  experimental_context?: unknown;
}

这些选项来自 AI SDK tool 执行上下文，会透传给 tool。

x402MastraTool(config)

创建一个兼容 Mastra createTool() 的 tool，底层调用 x402 端点。Mastra agent 使用 这个 helper；Vercel AI SDK ToolSet 集成继续使用 x402tool()。

import { z } from "zod";
import { X402Client, X402Networks, x402MastraTool } from "@averyso/alpha";

const client = new X402Client(process.env.X402_PRIVATE_KEY!, {
  network: X402Networks.baseSepolia,
  rpcUrl: process.env.X402_RPC_URL,
});

const paidWeather = x402MastraTool({
  id: "paid-weather",
  client,
  description: "Get current weather for a city from a paid x402 endpoint.",
  inputSchema: z.object({
    city: z.string(),
  }),
  endpoint: "https://api.example.com/weather",
  maxAmount: 50_000n,
  execute: ({ endpoint }) => ({
    ok: endpoint.ok,
    weather: endpoint.ok ? endpoint.body : null,
  }),
});

x402MastraTool() 不会在运行时 import @mastra/core，也不会把 Mastra 加成 Avery SDK 的依赖。你的应用负责安装并运行 Mastra；helper 返回结构兼容的 Mastra tool object，并设置 Mastra tool marker。

X402MastraToolConfig

type X402MastraToolConfig<INPUT, OUTPUT = EndpointResult, ID extends string = string> = {
  id: ID;
  description: string;
  inputSchema: unknown;
  outputSchema?: unknown;
  client: X402Client;
  endpoint: EndpointInput | ((input: INPUT) => EndpointInput);
  request?: (
    input: INPUT,
  ) =>
    | EndpointRequestInit
    | EndpointConfig
    | undefined
    | PromiseLike<EndpointRequestInit | EndpointConfig | undefined>;
  maxAmount?: bigint;
  throwOnError?: boolean;
  execute?: (
    context: { endpoint: EndpointResult; input: INPUT },
    options: X402MastraToolExecutionContext,
  ) => OUTPUT | PromiseLike<OUTPUT>;
};

配置还接受 Mastra tool 字段，包括 requireApproval、strict、providerOptions、 toModelOutput、transform、inputExamples、mcp、mcpMetadata、 requestContextSchema、suspendSchema 和 resumeSchema。

endpoint、request override、自动 input mapping、maxAmount 和 throwOnError 行为与 x402tool() 一致。没有 execute 时，tool 返回 EndpointResult。提供 execute 时，建议返回更小、适合模型消费的结构，不要把完整 payment 和 HTTP 结果 暴露给模型。

X402MastraToolExecutionContext

interface X402MastraToolExecutionContext {
  abortSignal?: AbortSignal;
  toolCallId?: string;
  messages?: unknown[];
  requestContext?: unknown;
  workspace?: unknown;
  [key: string]: unknown;
}

Mastra 会把这个 context 传给 tool。Avery SDK 使用其中的 abortSignal 控制底层 x402 HTTP 请求，并把整个对象透传给你的 execute mapper。

在 Mastra Agent 中注册 tools 时，Mastra stream 的 toolName 来自 object key， 不是 tool 的 id：

tools: {
  paidWeather, // toolName: "paidWeather"
  [paidWeather.id]: paidWeather, // toolName: "paid-weather"
}

Endpoint 类型

EndpointConfig

interface EndpointConfig {
  url: string | URL;
  method?: EndpointMethod | Lowercase<EndpointMethod> | string;
  headers?: HeadersInput;
  query?: URLSearchParams | Record<string, unknown>;
  body?: RequestBody | JsonValue;
}

当端点本身需要携带 method、headers、query 或 body 默认值时使用 EndpointConfig。

EndpointInput

type EndpointInput = string | URL | EndpointConfig;

X402Client.call() 和 x402tool() 的 endpoint 配置都接受这个类型。

EndpointRequestInit

interface EndpointRequestInit extends Omit<RequestInit, "body" | "headers" | "method"> {
  method?: EndpointMethod | Lowercase<EndpointMethod> | string;
  headers?: HeadersInput;
  query?: URLSearchParams | Record<string, unknown>;
  body?: RequestBody | JsonValue;
}

可作为 client.call() 的第二个参数，也可作为 x402tool() 的 request 函数返回值。

EndpointResult

EndpointResult 是以 kind 为判别字段的联合类型。 关于每个 kind 在支付生命周期中的含义，见 核心概念。重试策略和面向用户的处理建议见 错误处理。

const result = await client.call("https://api.example.com/weather");

if (result.kind === "success") {
  console.log(result.paymentResponse, result.body);
}

kind 取值：

• success：端点已支付，并返回成功的 settled response。
• settle_failed：端点响应后，支付结算失败。
• payment_required：端点要求支付，但没有完成兼容支付。
• error：端点请求或 x402 支付流程失败。
• passthrough：响应不需要支付，直接透传返回。

每个变体都包含：

interface EndpointResultMetadata {
  url: string;
  method: string;
  status: number;
  statusText: string;
  headers: Record<string, string>;
}

联合类型还暴露 ok、paid、status、body、paymentResponse 和 metadata。读取支付相关字段前，建议先按 kind 收窄类型。

错误

生产环境错误处理、重试策略和安全的模型侧 tool 输出建议见 错误处理。

X402Error

x402 SDK 错误的基类。

try {
  await client.call("https://api.example.com/weather", undefined, {
    throwOnError: true,
  });
} catch (error) {
  if (error instanceof X402Error) {
    console.error(error.details);
  }
}

X402ConfigError

SDK 配置无效时抛出，包括私钥格式错误、不支持的网络输入、不支持的 Solana CAIP-2 网络，或缺少 fetch。

X402PaymentError

设置 throwOnError: true 后，付费端点失败时抛出。包含 status 和可选 details。

if (error instanceof X402PaymentError) {
  console.error(error.status, error.details);
}

X402ErrorDetails

interface X402ErrorDetails {
  cause?: unknown;
  [key: string]: unknown;
}

供 X402Error、X402ConfigError 和 X402PaymentError 使用。

日志

Logger

interface Logger {
  debug(message: string, details?: Record<string, unknown>): void;
  info(message: string, details?: Record<string, unknown>): void;
  warn(message: string, details?: Record<string, unknown>): void;
  error(message: string, details?: Record<string, unknown>): void;
}

LogLevel

type LogLevel = "debug" | "info" | "warn" | "error" | "silent";

通过 X402ClientOptions 的 logger 和 logLevel 传入。

x402 Core 类型

Network

从 @x402/core/types 重新导出。原始 CAIP-2 字符串仍然可用于向后兼容。未知 friendly name 和不支持的原始 Solana CAIP-2 值会抛出 X402ConfigError，并在 details.network 和 details.supportedNetworks 中提供上下文。

SettleResponse

从 @x402/core/types 重新导出。success 和 settle_failed 类型的结果会包含 paymentResponse: SettleResponse。

CommonJS

包也支持 CommonJS 使用方式：

const {
  AlipayAIPayClient,
  AlipayAIPayMachinePayClient,
  X402Client,
  x402tool,
} = require("@averyso/alpha");