StableOps

签名器

使用 StableOps Agent Payments Signer 命令行校验钱包配对质询、启动本地伴随服务，并通过本地测试密钥、Solana 密钥或 AWS KMS 完成受控支付签名，确保私钥和签名权限始终留在用户环境中。

@stableops/agent-payments-signer 把钱包密钥留在用户环境中。用户通过 CLI 完成一次性钱包登记，日常付款则由 MCP 调用本机签名伴随服务：

Agent → stableops-agent-payments-mcp → 签名伴随服务 /v1/sign → 本地钱包密钥或 AWS KMS

伴随服务只签署与 StableOps 短时执行授权匹配的 EIP-3009、Permit2 或 Solana 付款。授权会绑定 Agent、钱包、网络、资产、收款地址、金额、随机数和有效期。字段不一致、授权过期、签发密钥未知或重放冲突都会被拒绝。

这里涉及两种用途不同的私钥：

私钥由谁配置配置位置
付款钱包私钥用户配置在签名器主机。本地 EVM 使用 STABLEOPS_EVM_PRIVATE_KEY_FILE，Solana 使用 STABLEOPS_SOLANA_PRIVATE_KEY_FILE，AWS KMS 使用 KMS 密钥标识。
执行授权签发私钥StableOps 控制面运营方配置在 API 服务的 AGENT_PAYMENTS_GRANT_PRIVATE_KEY_BASE64。用户和签名伴随服务都不会取得这把私钥。

签名器自动获取的是第二把私钥对应的公钥，用于确认执行授权确实由 StableOps 控制面签发。它不能用于签署付款。真正签署付款的仍是用户配置的付款钱包私钥或 AWS KMS 密钥。

命令行工具

该 npm 包同时提供 stableops-agent-payments-signer 命令行工具，需要 Node.js 20 或更高版本。全局安装后可以在终端直接调用：

pnpm add -g @stableops/agent-payments-signer

使用 --help 查看当前版本支持的命令：

stableops-agent-payments-signer --help

命令行工具提供两个主要命令：

命令运行方式用途
pair-wallet单次运行校验并签署一份尚未过期的钱包登记质询，向标准输出写入签名后退出。质询可通过 --challenge <base64url> 传入。省略该选项时，命令会从标准输入读取完整质询。
serve常驻运行启动仅监听本机回环地址的签名伴随服务，提供健康检查和受执行授权约束的付款签名接口。密钥、网络、授权验证、记录存储及服务鉴权配置均从环境变量读取。

两个命令都使用 --signer <local|aws-kms|solana> 选择签名器，也可以通过 STABLEOPS_SIGNER_TYPE 设置默认值。同时提供时，命令行选项优先。local 使用本地 EVM 测试密钥，aws-kms 使用 AWS KMS 中的 EVM 密钥，solana 使用本地 Solana 密钥。命令行工具不会接受命令行参数或环境变量中的本地私钥值，只接受受保护密钥文件的路径。

签名器能够生成签名，不代表收费服务接受对应网络。首次接入建议使用 Base Sepolia 本地 EVM 签名器。选择其它签名器和网络前，请先确认收费服务返回的付款要求与支持范围一致，再完成一笔需要人工审批的小额付款。

登记钱包：pair-wallet

钱包登记时，先领取一次性质询。用户再在受信任终端运行一次性命令。

MCP 会返回完整的质询文本。可以直接通过标准输入把它交给 CLI。

先在受信任终端设置私钥文件路径：

export STABLEOPS_EVM_PRIVATE_KEY_FILE='/受保护的绝对路径/evm-private-key'

应根据质询地址实际由哪类密钥控制来选择签名器：

  • 本地 EVM 沙盒钱包：按上文设置 STABLEOPS_EVM_PRIVATE_KEY_FILE，使用 --signer local。
  • AWS KMS 中的 EVM 钱包：设置 STABLEOPS_KMS_KEY_ID 和 AWS_REGION，使用 --signer aws-kms。命令行工具会推导 KMS 密钥对应的 EVM 地址，并拒绝签署其它地址的质询。
  • Solana 钱包：把 STABLEOPS_SOLANA_PRIVATE_KEY_FILE 指向受保护的 Base58 密钥文件，使用 --signer solana。

只复制完整的 7 行质询消息，从 StableOps Agent Wallet Pairing 开始，到 Expires At: ... 结束。每行字段名必须从行首开始，不要额外添加缩进或插入换行。不要复制说明文字或单独的质询 ID。

根据系统选择一种输入方式，只运行一次签名器。macOS 推荐从剪贴板传入质询：

pbpaste | stableops-agent-payments-signer pair-wallet --signer <local|aws-kms|solana>

其他系统启动交互命令：

stableops-agent-payments-signer pair-wallet --signer <local|aws-kms|solana>

命令等待输入时，粘贴这 7 行质询。最后一行粘贴完成后先按回车，再在下一行空行按 Ctrl-D，结束标准输入。CLI 会校验质询格式、有效期和钱包地址，只向标准输出写入签名。本地 EVM 与 AWS KMS 签名器输出 0x 开头的十六进制签名。Solana 签名器输出不带该前缀的 Base58 签名。把输出原样交回 Agent，不要转成 Base64。

只有使用 --challenge 参数时，才需要先把完整质询消息编码为无填充 Base64URL：

stableops-agent-payments-signer pair-wallet --signer <local|aws-kms|solana> --challenge <完整质询的无填充 Base64URL 编码>
pair-wallet 只签署格式、有效期和钱包地址均通过校验的 StableOps 配对质询。它不接受任意消息，也不用于日常付款。

完整流程见快速开始：登记并绑定付款钱包。

日常付款：serve

serve 在 127.0.0.1:8789 启动伴随服务，提供 GET /health 和 POST /v1/sign。运行时 MCP 使用伴随服务地址和鉴权令牌调用它。Agent 不直接执行签名器 CLI。

通用配置

用户只需要准备授权记录路径和伴随服务令牌。执行授权验证公钥由签名器自动获取：

环境变量填写方式
STABLEOPS_AUTHORIZATION_STORE_FILE用户选择的持久化 JSON 文件绝对路径。文件不需要预先创建，签名器会在首次记录授权时以 0600 权限创建。
STABLEOPS_SIDECAR_TOKEN用户自行生成的共享鉴权令牌。生成一次至少 32 字节的随机值，然后把同一个值配置给签名器和运行时 MCP。

在 macOS 或 Linux 上，先准备存储目录。示例中的用户名需要替换为实际用户名：

mkdir -p /Users/alice/.config/stableops/signer
chmod 700 /Users/alice/.config/stableops/signer

生成一次伴随服务令牌：

openssl rand -hex 32

复制命令输出的 64 位十六进制字符串，并在签名器与运行时 MCP 中使用同一个值。不要在两个进程中分别运行命令，否则会得到不同令牌。

准备完成后配置签名器：

export STABLEOPS_AUTHORIZATION_STORE_FILE='/Users/alice/.config/stableops/signer/grant-authorizations.json'
export STABLEOPS_SIDECAR_TOKEN='openssl 生成的 64 位十六进制字符串'

自动获取执行授权公钥

serve 启动时会请求以下公开接口：

GET https://api.stableops.dev/v1/public/agent-payments/execution-grant-keys

接口以 JWKS 格式返回当前控制面使用的 Ed25519 密钥标识和公钥。它不需要 API Key，也不会返回签发私钥。签名器会校验密钥类型、算法和编码后再启动。接口不可用或响应无效时，签名器拒绝启动。

验证公钥不属于某个用户、组织或钱包。每个 StableOps API 部署发布一组验证公钥，该部署下的组织共同使用。每份执行授权仍单独绑定组织、Agent、Intent、钱包、环境、网络、资产、收款地址、金额、随机数和有效期。

只有离线部署或需要固定公钥时，才同时配置 STABLEOPS_GRANT_KEY_ID 和 STABLEOPS_GRANT_PUBLIC_KEY_FILE。配置后签名器读取本地 PEM 文件，不再请求密钥发现接口。密钥轮换时必须同时更新这两个值。

StableOps 会自动发布验证公钥。用户不需要配置控制面地址，不需要提交工单，也不需要为自己的组织生成执行授权密钥。

运行时 MCP 使用以下配置连接伴随服务：

{
  "STABLEOPS_SIDECAR_URL": "http://127.0.0.1:8789",
  "STABLEOPS_SIDECAR_TOKEN": "与签名器相同的高熵随机令牌"
}

本地 EVM 测试签名器

local 仅用于沙盒 EVM 测试网络。私钥必须与 StableOps 登记的钱包地址匹配：

export STABLEOPS_EVM_PRIVATE_KEY_FILE='/受保护的绝对路径/evm-private-key'

stableops-agent-payments-signer serve --signer local
环境变量填写私钥文件的绝对路径，不是私钥本身。文件内容必须是 0x 加 64 位十六进制字符。文件必须是权限为 0600 的普通文件，不能是符号链接。缺少 0x 前缀时，CLI 会给出对应错误提示。

local 默认使用 SANDBOX、Base Sepolia 网络 eip155:84532 和端口 8789。其他沙盒 EVM 网络需设置 STABLEOPS_SIGNER_NETWORK。本地 EVM 模式不能连接正式环境。

Solana 签名器

Solana 私钥使用 Base58 编码。必须明确设置环境和 Solana CAIP-2 网络标识：

export STABLEOPS_SIGNER_ENVIRONMENT=LIVE
export STABLEOPS_SIGNER_NETWORK='solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
export STABLEOPS_SOLANA_PRIVATE_KEY_FILE='/受保护的绝对路径/solana-private-key'

stableops-agent-payments-signer serve --signer solana

Solana 私钥文件同样要求使用绝对路径、普通文件和 0600 权限。结算服务费用支付方承担交易费，付款钱包无需为 x402 付款持有 SOL。

AWS KMS 签名器

正式环境 EVM 部署应把私钥放在 AWS KMS。AwsKmsSigner 要求用途为 SIGN_VERIFY、密钥规格为 ECC_SECG_P256K1，并支持 ECDSA_SHA_256：

export STABLEOPS_SIGNER_ENVIRONMENT=LIVE
export STABLEOPS_SIGNER_NETWORK='eip155:8453'
export STABLEOPS_KMS_KEY_ID='替换为 KMS 密钥标识或 ARN'
export STABLEOPS_WALLET_ADDRESS='0x替换为 KMS 公钥对应的钱包地址'
export AWS_REGION='替换为 KMS 所在区域'

stableops-agent-payments-signer serve --signer aws-kms

启动时，签名器会读取 KMS 公钥并验证其 EVM 地址。地址与 STABLEOPS_WALLET_ADDRESS 不一致时拒绝启动。KMS 只签署已经通过执行授权校验的付款摘要。

AWS KMS 仅支持 EVM 网络。正式环境还必须通过 StableOps 的组织主网风控门禁。

部署检查

  • 伴随服务只能监听回环地址，不能暴露到公网。
  • 运行时 MCP 只持有伴随服务地址和鉴权令牌，不持有钱包私钥或 KMS 管理权限。
  • 签名器从可信控制面地址自动获取执行授权公钥。使用本地固定公钥时，轮换时同时更新密钥标识和公钥文件。
  • 每个网络使用独立的签名器、钱包和授权记录文件。
  • 单实例可使用文件授权记录。多副本部署应改用具备原子写入和唯一约束的共享存储。
  • 日志只记录授权标识、钱包地址和错误类别，不输出私钥、完整执行授权或支付签名。

这篇文档怎么样？

最后更新

管理 SDK

在受信任的运营者 TypeScript 服务中使用 StableOps Agent Payments 管理 SDK，创建和查询付款 Agent、钱包、不可变支出策略、预算、多人审批与付款记录，并了解管理密钥范围、请求映射和安全的自动化配置方式。

Webhook

接收 StableOps Agent Payments 的付款、资源响应、人工审批、链上结算与熔断状态 Webhook。正确验证签名、处理时间戳和重放保护、按事件标识去重、应对乱序投递与重试，并使用原付款 Intent 完成可靠对账。

本页内容

命令行工具登记钱包：pair-wallet日常付款：serve通用配置自动获取执行授权公钥本地 EVM 测试签名器Solana 签名器AWS KMS 签名器部署检查