StableOps Agent Payments SDK

查看英文说明

StableOps Agent Payments 让自主代理能够在明确的策略、组织与代理预算以及人工审批约束下发起稳定币付款。代理只会获得受限的代理密钥（Agent Key），不会接触管理 API Key 或不受限制的钱包权限。

这个 SDK 运行在代理进程中，负责请求付费资源、通过 StableOps 控制 API 协调付款意图、从客户自行托管的 @stableops/agent-payments-signer 签名器伴随服务获取签名，并携带付款凭证重试原始 x402 请求。StableOps 不会代理资源请求，也不会持有客户私钥。

功能

• 为 HTTPS 资源提供完整的 x402 v2 exact 付款流程。
• 通过 StableOps 控制 API 执行策略、预算和审批约束。
• 通过本地签名器伴随服务完成客户自主管理的签名。
• 仅允许 HTTPS 资源请求，固定 DNS 解析结果并阻止私网地址。
• 付款前仅允许同源重定向，附加付款签名后禁止重定向。
• 支持任务级幂等键和审批后继续执行。
• 提供受当前代理密钥范围约束的预算和付款只读查询。
• 提供四个框架无关的 AI 运行时工具定义。
• 同时输出 CJS、ESM 和 TypeScript 类型声明。

环境要求

• Node.js 20 或更高版本。
• StableOps 代理密钥。不要在代理运行时中使用管理 API Key。
• 客户自行托管的 @stableops/agent-payments-signer 签名器伴随服务。
• 当前 StableOps 环境支持的 HTTPS x402 资源。

安装

pnpm add @stableops/agent-payments-sdk

npm install @stableops/agent-payments-sdk

yarn add @stableops/agent-payments-sdk

快速开始

import {
  AgentPaymentsControlClient,
  HttpAgentSignerSidecar,
  SafeHttpsRequester,
  StableOpsAgent,
} from '@stableops/agent-payments-sdk'

function required(name: string): string {
  const value = process.env[name]?.trim()
  if (!value) throw new Error(`缺少环境变量 ${name}`)
  return value
}

const payments = new StableOpsAgent({
  control: new AgentPaymentsControlClient({
    agentKey: required('STABLEOPS_AGENT_KEY'),
  }),
  sidecar: new HttpAgentSignerSidecar({
    url: 'http://127.0.0.1:8789',
    authToken: required('STABLEOPS_SIDECAR_TOKEN'),
  }),
  requester: new SafeHttpsRequester(),
})

const result = await payments.x402Fetch('https://api.example.com/paid', {
  method: 'POST',
  body: JSON.stringify({ query: 'stablecoins' }),
  contentType: 'application/json',
  idempotencyKey: 'task_123:paid-resource:v1',
  context: {
    workflowId: 'research-workflow-1',
    taskId: 'market-report-2026-08-12',
    toolName: 'premium_market_data',
    purposeCode: 'research.market-data',
    costCenter: 'research',
  },
})

if (result.status === 'paid' || result.status === 'not_required') {
  const data = await result.response.json()
  console.log(data)
} else if (result.status === 'awaiting_approval') {
  // 保存 result.intentId，等待控制台或 Webhook 确认审批通过。
  console.log(`等待审批：${result.intentId}`)
}

只有在控制台或 Webhook 已经确认审批通过后，才能恢复原付款：

const approvedIntentId = 'pint_...' // 读取 awaiting_approval 阶段保存的 ID。
const resumed = await payments.x402Fetch('https://api.example.com/paid', {
  resumeIntentId: approvedIntentId,
  method: 'POST',
  body: JSON.stringify({ query: 'stablecoins' }),
  contentType: 'application/json',
})

HTTP Sidecar 客户端遇到传输错误、HTTP 408、425、429、5xx 或成功响应被截断时，会使用完全相同的执行 Grant 重试一次。签名器必须持久化 grantId -> authorization 结果，确保重试返回相同授权和 nonce。默认最多尝试两次，间隔 100 毫秒；可通过 maxAttempts 在 1 到 5 次之间调整，并通过 retryDelayMs 设置不超过 5 秒的间隔。

不能在收到 awaiting_approval 后立即恢复，也不能新建付款。复用同一个 intentId 可以保留原批准参数和预算预留。

SDK 还提供受代理密钥范围约束的只读方法：

const budget = await payments.getBudget()
const payment = await payments.getPayment('pint_...')
const recentPayments = await payments.listRecentPayments(20)

当资源服务器声明 x402 payment-identifier 扩展时，SDK 会根据 StableOps 付款意图生成稳定标识，并在审批后继续执行和请求重试时复用该标识。

对于可能重启或等待审批的工作流，可以使用 DurableAgentPaymentWorkflow 包装代理。正式环境的存储必须持久化记录，并通过分布式锁为每个 workflowId 实现 runExclusive：

const workflow = new DurableAgentPaymentWorkflow({
  agent: payments,
  store: durableWorkflowStore,
})

const { record, response } = await workflow.run(
  'report-job-2026-08-09',
  'https://api.example.com/paid',
  {
    taskId: 'market-report-2026-08-12',
    toolName: 'premium_market_data',
    purposeCode: 'research.market-data',
  },
)

同一个工作流编号会永久绑定到同一个网址和幂等键。结算状态未知时，后续运行只会查询原付款意图，不会创建新的授权。MemoryAgentPaymentWorkflowStore 仅供本地开发和测试使用。

资源也可以声明 x402 offer-receipt 扩展。由于签名有效并不能单独证明签名密钥已获准用于该资源，SDK 只有在配置 offerReceiptVerifier 后才接受此扩展。验证器必须同时验证密码学签名，以及密钥与受保护来源之间的绑定关系。验证通过的报价和收据会随请求结果返回，并由持久工作流保存。

BazaarAgentPaymentDiscovery 通过已配置的协调服务搜索或列出 x402 Bazaar 资源。它只返回 Agent Payments 支持的、具有 USDC exact 付款要求的具体 HTTPS GET、POST、PUT、PATCH 或 DELETE 资源。资源发现不会绕过正常的来源、收款地址、金额、预算、风控或审批检查。

agentPaymentTools 包含 stableops_get_budget、stableops_preview_x402_purchase、stableops_x402_fetch、stableops_get_payment 和 stableops_list_recent_payments 五个框架无关工具定义。

购买预检

在真正创建付款意图前，可以先读取资源的 402 挑战并执行只读预检：

const result = await agent.previewX402Purchase(resourceUrl)
if (result.status === 'payment_required') {
  console.log(result.preview.decision)
  console.log(result.preview.budget.agent.projectedAvailableAtomic)
  console.log(result.preview.reasons)
}

预检会返回策略判断、预计审批人数、默认钱包就绪状态、风控门禁，以及组织与 Agent 的预算投影、使用率和健康状态。它还会按当前组织、环境、来源、收款地址和网络汇总最近一百次资源交付结果，返回样本量、响应率与置信度；这只是历史质量信号，不会绕过策略或风控。预检不会创建 Intent、预留预算、领取执行授权或发送付款请求。预检结果是当时的只读快照，正式创建 Intent 时仍会在事务内重新检查全部条件；正式环境的收款地址筛查会在授权阶段执行。

结构化失败诊断

所有 AgentSdkError 都会提供失败来源、失败阶段、是否可安全自动重试、建议动作和结算确定性，并在可取得时提供请求编号和尝试次数。未知错误也可以通过统一函数转换：

import { describeAgentPaymentError } from '@stableops/agent-payments-sdk'

try {
  await workflow.run('report-job-2026-08-09', resourceUrl)
} catch (error) {
  const details = describeAgentPaymentError(error)
  console.error(details)
}

只有 retryable: true 才表示可以复用同一工作流和幂等键自动重试。retryDirective: 'wait_for_authorization_expiry' 表示签名阶段已经取得授权，必须等待原授权得到明确结果；reconcile_original_intent 表示付费请求可能已经送达，只能核对原付款意图。客户端诊断字段不能用于释放已提交预算，预算释放仍以 StableOps 服务端对账结果为准。

官方文档

完整配置流程、策略和审批行为、签名器部署与 x402 示例，请查看官方文档：

• 中文文档：https://stableops.dev/zh/docs/agent-payments
• 英文文档：https://stableops.dev/en/docs/agent-payments
• 快速开始：https://stableops.dev/zh/docs/agent-payments/quickstart

当前支持范围

当前版本支持：

• x402 v2 exact 付款。
• 六个 EVM 主网及其对应测试网，以及 Solana 主网和 Devnet 上的 HTTPS GET、POST、PUT、PATCH 和 DELETE 请求。
• 上述网络中已配置的 USDC；TRON 和 Nile 暂不支持。
• 沙盒只能使用测试网；正式环境支持主网，组织完成风控与恢复演练门禁后由 StableOps 开通。

当前不支持浏览器或边缘运行时、USDC 之外的资产、upto、直接转账、任意请求头或裸私钥。

遇到 SettlementUnknownError 时，不能创建新的付款意图重付。应查询原付款意图，并由 StableOps 根据授权随机数对账。

许可证

本 SDK 使用 Apache-2.0 许可证。