StableOps Agent Payments API SDK

查看英文说明

StableOps Agent Payments 是面向自主代理的付款控制层，通过不可变的支出策略、组织与代理预算、人工审批、客户自主管理的钱包、短时执行授权和付款对账来约束代理付款。

这个 SDK 适合在运营方服务端配置和管理 Agent Payments。管理凭证应保留在运营方服务端，不能放入代理运行时。

功能

• 创建、更新、暂停和恢复付款代理。
• 签发、查询和撤销受限的代理密钥。
• 注册、停用客户自主管理的钱包并将其绑定到代理。
• 创建、查询、启用和模拟不可变的多网络支出策略版本。
• 查询和更新组织级与代理级预算。
• 查询采用法定人数机制的待审批付款。
• 按付款状态、资源结果、Agent、业务上下文、来源和时间查询及导出付款记录。
• 查询状态迁移记录和结算回执。
• 同时输出 CJS、ESM 和 TypeScript 类型声明。

环境要求

• Node.js 20 或更高版本。
• StableOps 组织。
• 用于管理和查询操作的组织 API Key。
• 服务端运行环境。不要把凭证暴露给代理或打包到浏览器代码中。

安装

pnpm add @stableops/agent-payments-api-sdk

npm install @stableops/agent-payments-api-sdk

yarn add @stableops/agent-payments-api-sdk

快速开始

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

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

const payments = new StableOpsAgentPayments({
  apiKey: required('STABLEOPS_API_KEY'),
})

const agent = await payments.agents.create({
  name: '采购代理',
  description: '购买已批准的业务数据',
})

const credential = await payments.agents.createKey(agent.id, {
  name: '采购代理运行时',
})

// 明文代理密钥只会返回一次，应将其保存到密钥管理服务。
console.log(credential.secret)

API Key 会把请求限定在其所属的组织和环境，无需另行选择环境或发送环境请求头。

客户端按管理领域提供独立资源：

const agents = await payments.agents.list()
const wallets = await payments.wallets.list()
const organizationBudget = await payments.budgets.getOrganization()
const approvals = await payments.approvals.list()
const recentPayments = await payments.payments.list()

兼容接口 list() 仍返回数组。需要分页信息或服务端筛选时，使用 listPage()：

const page = await payments.payments.listPage({
  agentId: agent.id,
  status: 'settled',
  resourceStatus: 'response_received',
  workflowId: 'research-weekly',
  toolName: 'market-data',
  costCenter: 'research',
  limit: 50,
})

console.log(page.data, page.hasMore, page.nextCursor, page.total)

const csv = await payments.payments.exportCsv({
  status: 'settled',
  workflowId: 'research-weekly',
  createdFrom: '2026-08-01T00:00:00.000Z',
  createdTo: '2026-08-31T23:59:59.999Z',
})

CSV 导出使用同一组筛选条件，单次最多包含 10,000 条记录，并会阻止调用方可控字段触发电子表格公式。超过上限时，应缩小日期范围或增加业务上下文筛选条件。

代理、钱包和审批也提供相同的分页接口。可通过 payments.agents.simulatePolicy() 模拟策略，通过 payments.wallets.disable() 永久停用钱包。

金额单位

策略阈值和全部预算始终使用 6 位 USDC 预算单位，因此所有网络上的 1000000 都表示 1 USDC。支付、审批和回执金额使用链上资产最小单位，并通过 assetDecimals 返回位数。BNB Smart Chain 及其测试网为 18 位，其它当前支持网络为 6 位。

例如，BNB Smart Chain 上的 1 USDC 在支付记录中是 1000000000000000000，但在策略限额或日预算中仍是 1000000。不要在未换算为 6 位预算单位前，把支付金额直接复制到策略中。

审批决定应在 StableOps 控制台完成。本 SDK 只使用组织 API Key，可以查询审批记录，但不接受控制台访问令牌，也不提供批准和拒绝操作。

官方文档

完整的钱包注册、策略、预算、审批和付款查询示例，请查看官方文档：

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

当前支持范围

当前版本支持六个 EVM 主网及其对应测试网，以及 Solana 主网和 Devnet 上已配置的 USDC 与 x402 v2 exact。沙盒只能使用测试网；正式环境支持主网，组织完成风控与恢复演练门禁后由 StableOps 开通。TRON 和 Nile 暂不支持。

代理运行时应使用 @stableops/agent-payments-sdk，客户自主管理的签名环境应使用 @stableops/agent-payments-signer。

许可证

本 SDK 使用 Apache-2.0 许可证。