使用@x402-avm/core和@x402-avm/avm TypeScript包直接进行自定义x402支付集成。当构建自定义客户端、资源服务器或促进者与Algorand上的x402协议时，使用此技能，实现支付策略，创建AVM签名者接口，处理交易组，或集成费用抽象。强烈的触发词包括“使用x402核心包”、“创建x402客户端”、“实现促进者签名者”、“x402支付验证”、“Algorand上的费用抽象”、“注册AVM方案”、“交易组签名”、“x402ResourceServer”、“x402Client”、“x402Facilitator”、“ClientAvmSigner”、“FacilitatorAvmSigner”。

使用@x402-avm/core和@x402-avm/avm包

在Algorand上使用核心TypeScript SDK包直接构建自定义x402支付集成。这些包为HTTP 402支付协议提供了客户端、资源服务器和促进者原语。

先决条件

在使用此技能之前，请确保：

Node.js 18+ 已安装
TypeScript项目 已设置
Algorand账户 可用（用于签名交易）
algosdk 作为对等依赖项已安装

核心工作流程：x402支付流程

x402协议遵循标准HTTP 402流程，涉及三个参与者：

客户端                    资源服务器             促进者
  |                             |                           |
  |-- GET /resource ----------->|                           |
  |<-- 402 PaymentRequired -----|                           |
  |                             |                           |
  |  (签名支付交易)        |                           |
  |                             |                           |
  |-- GET /resource ----------->|                           |
  |   X-PAYMENT: <payload>      |<-- verify(payload) ------->|
  |                             |<-- { isValid: true } -----|
  |<-- 200 OK + content --------|                           |
  |                             |-- settle(payload) ------->|
  |                             |<-- { txId: "..." } -------|

如何进行

第1步：安装依赖项

npm install @x402-avm/core @x402-avm/avm algosdk

第2步：创建客户端

x402Client自动处理402响应，通过创建和签名支付，然后使用X-PAYMENT头重试请求。

import { x402Client } from "@x402-avm/core/client";
import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";
import type { ClientAvmSigner } from "@x402-avm/avm";
import algosdk from "algosdk";

const secretKey = Buffer.from(process.env.AVM_PRIVATE_KEY!, "base64");
const address = algosdk.encodeAddress(secretKey.slice(32));

const signer: ClientAvmSigner = {
  address,
  signTransactions: async (txns, indexesToSign) => {
    return txns.map((txn, i) => {
      if (indexesToSign && !indexesToSign.includes(i)) return null;
      const decoded = algosdk.decodeUnsignedTransaction(txn);
      return algosdk.signTransaction(decoded, secretKey).blob;
    });
  },
};

const client = new x402Client({ schemes: [] });
registerExactAvmScheme(client, { signer });

const response = await client.fetch("https://api.example.com/premium/data");

第3步：创建资源服务器

x402ResourceServer与传输无关。使用它与Express、Fastify、Hono或任何框架一起。

import { x402ResourceServer, HTTPFacilitatorClient } from "@x402-avm/core/server";
import { registerExactAvmScheme } from "@x402-avm/avm/exact/server";
import { ALGORAND_TESTNET_CAIP2, USDC_TESTNET_ASA_ID } from "@x402-avm/avm";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://facilitator.example.com",
});

const server = new x402ResourceServer(facilitatorClient);
registerExactAvmScheme(server);

第4步：创建促进者

x402Facilitator验证支付签名并在链上结算交易。

import { x402Facilitator } from "@x402-avm/core/facilitator";
import { registerExactAvmScheme } from "@x402-avm/avm/exact/facilitator";
import type { FacilitatorAvmSigner } from "@x402-avm/avm";

const facilitator = new x402Facilitator();
registerExactAvmScheme(facilitator, {
  signer: myFacilitatorSigner,
  networks: ALGORAND_TESTNET_CAIP2,
});

第5步：实现AVM签名者

存在两个签名者接口：

ClientAvmSigner：用于支付资源的客户端。与@txnlab/use-wallet兼容。
FacilitatorAvmSigner：用于验证和结算支付的促进者。管理Algod客户端、模拟和提交。

第6步：应用支付策略（可选）

策略在客户端选择之前过滤支付要求。

import { PaymentPolicy } from "@x402-avm/core/client";
import { ALGORAND_TESTNET_CAIP2 } from "@x402-avm/avm";

const preferTestnet: PaymentPolicy = (version, requirements) => {
  return requirements.filter(r => r.network === ALGORAND_TESTNET_CAIP2);
};

registerExactAvmScheme(client, {
  signer,
  policies: [preferTestnet],
});

重要规则/指南

在使用客户端、服务器或促进者之前始终注册AVM方案 - 在构造后调用registerExactAvmScheme()
在SDK代码中使用CAIP-2网络标识符 - 从@x402-avm/avm导入ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2
签名者分离 - 协议接口位于SDK中（@x402-avm/avm），使用algosdk的实现位于您的应用程序代码中
TypeScript algosdk使用原始Uint8Array - 不需要base64转换（与Python SDK不同）
费用抽象是自动的 - 当PaymentRequirements包括feePayer时，方案自动创建2个交易原子组
私钥格式 - AVM_PRIVATE_KEY是Base64编码的64字节密钥（32字节种子+32字节公钥），地址从secretKey.slice(32)派生
交易组 - 所有x402-avm支付使用Algorand原子交易组；payload中的paymentGroup数组包含base64编码的msgpack交易字节

常见错误/故障排除

错误	原因	解决方案
`No scheme registered for network`	未注册AVM方案	在客户端/服务器/促进者上调用`registerExactAvmScheme()`
`Invalid key length: expected 64`	错误的私钥格式	确保`AVM_PRIVATE_KEY`是64字节密钥的Base64
`Simulation failed`	交易在链上会失败	检查发送者余额，USDC选择加入，正确的接收者
`signer not found for address`	地址不匹配	验证签名者地址与支付账户匹配
`Group ID mismatch`	原子组不一致	在编码前使用`algosdk.assignGroupID()`
`Fee too high`	费用超过MAX_REASONABLE_FEE	检查费用计算；最大值是10 ALGO
`No payment requirements matched`	策略过滤了所有选项	审查策略逻辑；确保至少有一个要求通过
`Transaction rejected`	用户在钱包中取消	在UI中优雅地处理拒绝

参考资料/进一步阅读

REFERENCE.md - @x402-avm/core和@x402-avm/avm的完整API参考
EXAMPLES.md - 完整代码示例
x402-avm示例存储库
x402-avm文档