管理 SDK
在运营者服务端通过专用 TypeScript 客户端配置和查询 Agent Payments。
@stableops/agent-payments-api-sdk 是 Agent Payments 的专用管理客户端。它应运行在受信任的运营者服务端，不能放入 Agent 运行时或浏览器代码。
安装
pnpm add @stableops/agent-payments-api-sdk创建管理客户端
管理 API Key 同时限定组织、环境和产品权限：
import { StableOpsAgentPayments } from '@stableops/agent-payments-api-sdk'
const apiKey = process.env.STABLEOPS_API_KEY?.trim()
if (!apiKey) throw new Error('缺少 STABLEOPS_API_KEY')
const management = new StableOpsAgentPayments({
apiKey,
baseUrl: process.env.STABLEOPS_API_URL,
})管理 API Key 可以修改 Agent、钱包、策略和预算，绝不能交给 Agent 运行时。运行时只应持有
ak_sandbox_... 或 ak_live_... 格式的受限 Agent Key。可用资源
| 资源 | 主要操作 |
|---|---|
management.agents | 创建、查询、更新、暂停或恢复 Agent，管理 Agent Key 和不可变策略版本 |
management.wallets | 创建钱包登记质询、登记钱包、查询钱包，以及绑定或解绑 Agent 的默认钱包 |
management.budgets | 在平台上限内查询或更新组织与 Agent 的日预算 |
management.approvals | 使用管理 API Key 查询审批记录，使用管理员会话批准或拒绝 |
management.payments | 查询支付、状态迁移记录和结算回执 |
金额字段分为两类，不能混用：
- 支出策略和预算中的
automaticPaymentThresholdAtomic、perPaymentLimitAtomic、agentDailyLimitAtomic、limitAtomic等字段统一使用 6 位 USDC 预算单位，因此1000000始终表示 1 USDC。 - 支付、审批和回执中的
maxAmountAtomic使用该网络 USDC 的链上资产最小单位，必须结合返回的assetDecimals解释。BNB Smart Chain 及其测试网为 18 位，其它当前支持网络为 6 位。
例如，BNB Smart Chain 上支付 1 USDC 时，x402 报价和 maxAmountAtomic 是 1000000000000000000，但策略单笔限额和日预算仍写 1000000。服务端会向上取整换算预算占用，避免 18 位资产的极小金额绕过预算。
策略版本创建后不可修改。需要调整规则时，应创建新版本并显式激活。完整网络位数见介绍中的支持范围。
Agent Key 只显示一次
const credential = await management.agents.createKey('agent_...', {
name: 'production-runtime',
})
if (!credential.secret) throw new Error('没有返回一次性 Agent Key')
console.log(`STABLEOPS_AGENT_KEY=${credential.secret}`) // 仅在安全的首次配置环境中输出。API 不会再次返回明文。密钥丢失或泄露时，应撤销旧 Key 并签发新 Key。
审批使用独立的管理员会话
管理 API Key 可以读取审批队列，但批准和拒绝属于高风险操作，只接受当前已登录的 StableOps 组织管理员会话所签发的短时访问令牌。大多数接入方应直接使用控制台审批页；下面的模式只适用于已经接入 StableOps 登录态的控制台代码：
async function approveFromDashboardSession(accessToken: string) {
const dashboard = new StableOpsAgentPayments({
accessToken,
environment: 'sandbox',
baseUrl: process.env.STABLEOPS_API_URL,
})
const approvals = await dashboard.approvals.list()
const approval = approvals[0]
if (!approval) throw new Error('当前没有待处理审批')
await dashboard.approvals.approve(approval.id, '预算内的常规数据购买')
}同一个客户端不能同时配置 apiKey 和 accessToken。管理员访问令牌不能缓存、写入环境变量或交给 Agent 运行时。
完整的钱包登记、策略配置和支付流程见快速开始。
这篇文档怎么样？
最后更新