TypeScript SDK 参考

@agentwallex/sdk 包的完整参考文档

安装

npm install @agentwallex/sdk

客户端初始化

import { AgentWallex } from "@agentwallex/sdk";
 
const aw = new AgentWallex({
  apiKey: string;          // 你的 API 密钥
  environment?: "sandbox" | "production";  // 默认: "sandbox"
  baseUrl?: string;        // 自定义端点（可选）
  timeout?: number;        // 请求超时毫秒数（默认: 30000）
});

Agent 管理

`aw.agents.create(params)`

创建带有 MPC 安全钱包的新 Agent。

const agent = await aw.agents.create({
  name: "my-agent",
  chain: "ethereum" | "polygon" | "base" | "arbitrum",
  policies?: {
    maxTransactionAmount?: string;
    dailyLimit?: string;
    allowedAddresses?: string[];
    allowedTokens?: string[];
    requireHumanApproval?: boolean;
    humanApprovalThreshold?: string;
  },
  metadata?: Record<string, string>;
});

返回值：

字段	类型	说明
`id`	`string`	Agent 唯一标识
`name`	`string`	Agent 显示名称
`wallet.address`	`string`	链上钱包地址
`wallet.chain`	`string`	区块链网络
`status`	`string`	`"active"` 或 `"frozen"`
`createdAt`	`string`	ISO 8601 时间戳

`aw.agents.get(agentId)`

按 ID 获取 Agent。

const agent = await aw.agents.get("agent_abc123");

`aw.agents.list(params?)`

列出账户下所有 Agent。

const { agents, pagination } = await aw.agents.list({
  limit: 20,
  offset: 0,
  status: "active",
});

`aw.agents.freeze(agentId)`

立即冻结 Agent 钱包，阻止所有交易。

await aw.agents.freeze("agent_abc123");

`aw.agents.unfreeze(agentId)`

解冻 Agent 钱包。

await aw.agents.unfreeze("agent_abc123");

支付

`aw.payments.send(params)`

发送链上直接支付。

const tx = await aw.payments.send({
  agentId: "agent_abc123",
  to: "0xRecipientAddress",
  amount: "50.00",
  token: "USDC",
  memo?: "API 访问付款",
});

返回值：

字段	类型	说明
`id`	`string`	交易 ID
`hash`	`string`	链上交易哈希
`status`	`string`	`"pending"`、`"confirmed"`、`"failed"`
`amount`	`string`	发送金额
`token`	`string`	代币符号
`fee`	`string`	网络 Gas 费

`aw.payments.get(transactionId)`

获取交易详情和状态。

const tx = await aw.payments.get("tx_xyz789");

`aw.payments.list(params)`

列出 Agent 的交易记录。

const { transactions } = await aw.payments.list({
  agentId: "agent_abc123",
  limit: 50,
  status: "confirmed",
});

x402 微支付

`aw.x402.createSession(params)`

创建 x402 支付会话（对应 POST /api/v1/x402/sessions）。

const session = await aw.x402.createSession({
  agentId: "agent_abc123",      // -> agent_id
  budgetLimit: "100.00",         // -> budget_limit
  chain: "eip155:84532",
  ttlSeconds: 3600,              // -> ttl_seconds
  allowedUrls: ["https://paid-api.example.com/v1/data"],
});

`aw.x402.check(params)`

检查目标 URL 是否支持 x402 支付协商。

const info = await aw.x402.check({
  url: "https://paid-api.example.com/v1/data",
});

`aw.x402.pay(params)`

发起并完成一次 x402 支付协商。

const result = await aw.x402.pay({
  agentId: "agent_abc123",
  targetUrl: "https://paid-api.example.com/v1/data",
  sessionId: session.id,          // 可选
  chain: "eip155:84532",          // 可选
});

`aw.x402.sessionPay(sessionId, params)`

在已有会话预算内执行支付。

await aw.x402.sessionPay(session.id, {
  targetUrl: "https://paid-api.example.com/v1/data",
});

`aw.x402.httpInterceptor(params)`

创建自动处理 x402 v2 challenge 的拦截器：

读取 PAYMENT-REQUIRED
通过 AgentWallex 发起支付
使用 PAYMENT-SIGNATURE 自动重试

const fetchWithPayment = aw.x402.httpInterceptor({
  agentId: "agent_abc123",
  chain: "eip155:84532",
});

策略管理

`aw.policies.update(agentId, policies)`

更新 Agent 的支出策略。

await aw.policies.update("agent_abc123", {
  maxTransactionAmount: "200",
  dailyLimit: "2000",
  allowedAddresses: ["0xAddr1", "0xAddr2"],
  velocityLimit: { maxCount: 100, windowSeconds: 3600 },
});

`aw.policies.get(agentId)`

获取 Agent 当前策略。

const policies = await aw.policies.get("agent_abc123");

Webhook

`aw.webhooks.create(params)`

const webhook = await aw.webhooks.create({
  url: "https://your-app.com/webhooks/agentwallex",
  events: [
    "payment.completed",
    "payment.failed",
    "agent.frozen",
    "policy.violated",
  ],
  secret: "whsec_your_signing_secret",
});

Webhook 事件类型

事件	说明
`payment.completed`	交易已在链上确认
`payment.failed`	交易失败或回滚
`payment.pending`	交易已提交，等待确认
`agent.frozen`	Agent 钱包已冻结
`agent.unfrozen`	Agent 钱包已解冻
`policy.violated`	交易被策略引擎拒绝
`x402.session.expired`	x402 会话预算或有效期已耗尽

错误处理

import { AgentWallexError, PolicyViolationError } from "@agentwallex/sdk";
 
try {
  await aw.payments.send({ ... });
} catch (error) {
  if (error instanceof PolicyViolationError) {
    console.log(`策略违规: ${error.rule}`);
    console.log(`详情: ${error.message}`);
  } else if (error instanceof AgentWallexError) {
    console.log(`API 错误: ${error.code} - ${error.message}`);
  }
}

TypeScript 类型

所有类型均从包中导出：

import type {
  Agent,
  Payment,
  Transaction,
  Policy,
  X402Session,
  WebhookEvent,
} from "@agentwallex/sdk";