快速开始

安装 Agent Payments MCP 服务和签名器 CLI 后，Agent 可以通过一组受限 MCP 工具配置支付轨道、检查运行状态，并在策略与预算约束内完成支付。用户可以直接在终端完成钱包配对和启动签名器。

安装

需要 Node.js 20 或更高版本。全局安装 MCP 服务和签名器 CLI：

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

MCP 主机根据配置自动启动 stableops-agent-payments-mcp。用户在受信任终端运行 stableops-agent-payments-signer。

安全边界保持不变：

准备条件

本快速开始使用 Base Sepolia，这是首次沙盒付款的推荐网络。完成这套流程后再配置其它网络。收费服务要求其它网络时，请确认付款要求与支持范围所列网络和 USDC 一致，再从需要人工审批的小额付款开始。

• 一个 StableOps 组织和沙盒 Agent Payments 管理 API Key。
• 一个由你控制私钥的独立 Base Sepolia 测试付款钱包地址。建议在支持 Base Sepolia 的 EVM 钱包软件中创建专用测试账户，只存放测试资产，不要复用持有真实资产的钱包。沙盒网络标识为 eip155:84532，官方测试 USDC 合约为 0x036CbD53842c5426634e7929541eC2318f3dCF7e。
• 钱包内有测试 USDC。当前 EIP-3009 流程由结算服务提交交易，付款钱包不需要为本流程持有测试 ETH。

金额和预算统一用最小单位字符串表示。USDC 为 6 位小数，1000000 表示 1 USDC。沙盒上限为单笔 1 USDC、单 Agent 每日 10 USDC、组织每日 100 USDC。

1. 把管理 MCP 交给 Agent

下面的配置应写入运行 Agent 的 MCP 主机配置文件，不是写入项目的 .env 文件，也不是作为命令单独粘贴到终端。常见配置位置包括：

• Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor：全局配置 ~/.cursor/mcp.json，或项目配置 .cursor/mcp.json
• Codex CLI：~/.codex/config.toml，使用下文单独给出的 TOML 格式

其他 MCP 主机也需要配置同样的启动命令和环境变量，但配置文件位置与字段名称可能不同。修改后需要重启 MCP 主机，使其重新启动服务进程。

准备配置值

在 macOS 或 Linux 上，可以先准备仅当前用户可访问的父目录。下面的命令不会创建 agent-key 文件：

mkdir -p "$HOME/.config/stableops"
chmod 700 "$HOME/.config/stableops"

在 MCP 配置中把 $HOME 展开成真实绝对路径，例如 /Users/alice/.config/stableops/agent-key。

JSON 配置示例

使用 JSON 配置的 MCP 主机可加入：

{
  "mcpServers": {
    "stableops-agent-payments": {
      "command": "stableops-agent-payments-mcp",
      "env": {
        "STABLEOPS_API_KEY": "sk_sandbox_替换为管理密钥",
        "STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES": "true",
        "STABLEOPS_AGENT_KEY_OUTPUT_FILE": "/受保护的绝对路径/stableops-agent-key"
      }
    }
  }
}

其中三个示例值都必须按前文说明替换。mcpServers 下的名称 stableops-agent-payments 只是本机显示名称，可以修改。command 必须保持为安装后生成的 stableops-agent-payments-mcp。

Codex CLI 配置示例

Codex CLI 使用 TOML。把等价配置加入 ~/.codex/config.toml：

[mcp_servers.stableops-agent-payments]
command = "stableops-agent-payments-mcp"
env = { STABLEOPS_API_KEY = "sk_sandbox_替换为管理密钥", STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES = "true", STABLEOPS_AGENT_KEY_OUTPUT_FILE = "/Users/alice/.config/stableops/agent-key" }

管理模式默认只注册只读工具。仅在受信任的首次配置会话中开启管理写入，完成后删除写入开关和管理 API Key。

**控制台：**创建并保存组织级 sk_sandbox_... 管理 API Key。这个密钥只在首次配置会话中使用。

**MCP 返回结果：**Agent 调用 stableops_ap_create_wallet_pairing_challenge 后，MCP 返回完整的钱包配对质询。

**受保护的输出文件：**完成钱包登记和策略激活，并显式调用 stableops_ap_issue_agent_key 后，MCP 会把只返回一次的 ak_sandbox_... Agent Key 写入 STABLEOPS_AGENT_KEY_OUTPUT_FILE。

连接 MCP 后，向 Agent 提供下面的配置目标：

请使用 StableOps Agent Payments MCP 为 research-agent 配置沙盒支付：
- 网络：eip155:84532
- 钱包地址：<替换为你控制的 Base Sepolia 测试付款钱包公开地址>
- 签名器：LOCAL_TEST，标识为 local:<同一钱包地址的小写形式>
- 首个策略不设置自动付款白名单，自动阈值为 0
- 单笔上限 1000000，Agent 日限额 10000000
- 不修改组织预算

先查询现有 Agent，避免重复创建。领取钱包配对质询后必须停止，
把完整消息放在纯文本代码块中交给我核对和签名，质询必须严格保持 7 行，不得缩进或插入换行。不得索要私钥或助记词。收到签名后再登记、
绑定钱包、创建并模拟策略、激活策略，最后必须调用
`stableops_ap_issue_agent_key` 签发运行时 Agent Key。

“钱包地址”是实际支付测试 USDC 的用户钱包公开地址，不是 StableOps 或商家提供的地址。它必须满足：

1. 你能够用该钱包账户签署后续的配对质询，以证明自己控制它。
2. 本地签名器使用的测试私钥能够推导出同一个地址，否则付款签名会被拒绝。
3. 该地址持有足够的 Base Sepolia 测试 USDC。当前流程不要求它持有测试 ETH。

建议使用只持有少量测试资产的专用账户。local:<小写钱包地址> 是本地签名密钥的非敏感标识，不是私钥或另一个钱包地址。

Agent 应先查询现有资源，再创建并模拟策略，最后单独激活。登记和激活完成后，必须调用 stableops_ap_issue_agent_key，并提供当前 Agent 的 agent_id 和一个密钥名称，例如 research-agent-runtime。

Agent Key 明文不会显示在对话中。MCP 会先创建前述受保护文件，再请求 API 签发密钥，并把只返回一次的 ak_sandbox_... 明文写入文件。工具结果只会确认 secret_stored: true 及密钥元数据。写入失败时会撤销刚签发的密钥，MCP 也不会覆盖已有文件。

如果工具列表中没有 stableops_ap_issue_agent_key，请确认 MCP 已设置 STABLEOPS_AP_ENABLE_MANAGEMENT_WRITES="true" 并重启 MCP 主机。如果工具执行成功但找不到文件，请检查 STABLEOPS_AGENT_KEY_OUTPUT_FILE 是否为 MCP 主机上的新建绝对路径。

登记并绑定付款钱包

stableops_ap_create_wallet_pairing_challenge 返回质询标识、完整消息和 requires_user_action: true。此时 Agent 必须停止，由用户完成以下操作：

1. 核对组织、网络、钱包地址和有效期。

2. 确认签名器主机上的付款钱包私钥能够推导出质询中的 Address。私钥必须保存在签名器主机的受保护文件中，不能粘贴到对话、MCP 配置或命令行参数。

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

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

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

5. 根据系统选择一种输入方式，只运行一次签名器：

   macOS 推荐从剪贴板传入质询，让标准输入自动结束：

   pbpaste | stableops-agent-payments-signer pair-wallet --signer local

   其他系统启动交互命令：

   stableops-agent-payments-signer pair-wallet --signer local

   命令等待输入时，粘贴这 7 行质询。最后一行粘贴完成后先按回车，再在下一行空行按 Ctrl-D，结束标准输入。

6. 签名器会在标准输出打印一个 0x 开头的 EVM 签名。把这个签名原样交回 Agent。不要自行转成 Base64，也不要把私钥或助记词交回 Agent。

Agent 随后调用 stableops_ap_register_wallet 和 stableops_ap_bind_wallet。CLI 会校验质询、有效期和密钥对应地址，MCP 服务与网页不会接触私钥。

如果使用 pair-wallet --challenge 参数，参数值必须是完整质询消息的无填充 Base64URL 编码。Agent 返回的是可直接粘贴到标准输入的原始文本，因此按上面的标准输入方式操作最简单。

首次策略建议保持 allowed_origins 与 allowed_pay_to 为空、automatic_payment_threshold_atomic 为 0。这样任何真实付款都会进入人工审批。确认某个服务可信后，再创建新策略版本，把准确来源和收款地址加入自动付款白名单。

2. 启动用户控制的签名伴随服务

stableops-agent-payments-signer 提供两个签名命令：

• pair-wallet 用于钱包登记。它校验并签署一次性质询，输出签名后退出。
• serve 用于日常付款。它启动常驻签名伴随服务，验证执行授权并签署对应付款。日常付款期间必须保持该进程运行。

Agent 不会直接执行签名器 CLI，也不会接触钱包密钥。运行时调用链如下：

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

MCP 服务从 StableOps API 取得逐字段绑定的短时执行授权，然后使用 STABLEOPS_SIDECAR_URL 和 STABLEOPS_SIDECAR_TOKEN 请求伴随服务。伴随服务验证执行授权后才签署对应付款，不提供任意消息签名接口。

请按签名器页面配置并启动：

• 沙盒测试运行 stableops-agent-payments-signer serve --signer local，默认仅监听 127.0.0.1:8789。
• 正式环境 EVM 钱包运行 stableops-agent-payments-signer serve --signer aws-kms，使用 AWS KMS 中不可导出的密钥。
• 伴随服务必须设置高熵鉴权令牌，并使用可持久化的授权记录存储。

这一步需要用户明确决定使用哪个钱包或 KMS 密钥，并在受信任环境中配置密钥材料。Agent 可以通过 MCP 检查伴随服务健康状态，但不应读取或代管密钥。

3. 切换到受限运行时 MCP

首次配置使用组织级管理权限。日常付款改用只属于当前 Agent 和环境的 Agent Key。运行时不会注册管理工具，仍需通过策略、预算、风险检查、人工审批和签名器。

完成钱包登记、策略激活和密钥签发后，STABLEOPS_AGENT_KEY_OUTPUT_FILE 指向的文件中才会出现 ak_sandbox_... 密钥。StableOps API 只在签发时向 MCP 提供一次密钥明文。密钥不会显示在 Agent 对话中，也不能通过查询接口再次取回。

请在受信任终端读取该文件，把密钥转移到 MCP 主机的运行时密钥配置，确认运行时配置可以读取后删除临时文件。然后删除 STABLEOPS_API_KEY 和管理写入开关，加入签名器地址和令牌：

{
  "mcpServers": {
    "stableops-agent-payments": {
      "command": "stableops-agent-payments-mcp",
      "env": {
        "STABLEOPS_AGENT_KEY": "ak_sandbox_替换为一次性返回的密钥",
        "STABLEOPS_SIDECAR_URL": "http://127.0.0.1:8789",
        "STABLEOPS_SIDECAR_TOKEN": "替换为高熵随机令牌"
      }
    }
  }
}

三个运行时配置值的来源如下：

• STABLEOPS_AGENT_KEY：来自首次配置时 STABLEOPS_AGENT_KEY_OUTPUT_FILE 指向的文件。完整密钥为 ak_sandbox_... 格式，只属于签发它的 Agent。
• STABLEOPS_SIDECAR_URL：第二步部署签名器伴随服务后得到的本机地址。按本文示例启动时为 http://127.0.0.1:8789。
• STABLEOPS_SIDECAR_TOKEN：由用户自行生成的高熵随机令牌。签名器伴随服务和运行时 MCP 必须配置相同的值。不要把它写入提示词、源代码或提交到仓库。

在 macOS 或 Linux 上，可以用下面的命令生成 32 字节随机令牌，并把输出安全地保存到密钥管理工具：

openssl rand -hex 32

管理模式和运行时模式互斥。配置中不能同时保留 STABLEOPS_API_KEY 与 STABLEOPS_AGENT_KEY，否则 MCP 服务会拒绝启动。

重启 MCP 后按以下顺序使用运行时工具：

1. 检查运行身份、预算、支持网络和伴随服务状态。
2. 发现候选服务，对准确网址执行预检并取得 preview_token。
3. 使用相同的 preview_token 和稳定的 idempotency_key 发起购买。
4. 需要人工审批时保存 intent_id，审批后恢复原付款。
5. 结算状态未知时只查询原付款，不创建替代付款。

未配置伴随服务时，MCP 仍可发现和预检，但不会注册购买与恢复工具。未知来源、未知收款地址或超自动阈值付款需要用户在控制台审批，Agent 无法自行批准。

4. 完成第一笔沙盒付款

运行时 MCP 和签名伴随服务就绪后，前往使用 Agent Payments 购买 x402 资源。该页面会引导你让 Agent 发现或指定收费资源，核对预检结果，发起付款，处理人工审批并确认最终状态。

下一步

• 在签名器从本地测试钱包迁移到 AWS KMS。
• 在 Webhook 集成中接收审批、结算和异常状态。
• 上主网前核对支持范围中的网络、合约、资产位数和付款方式。