快速開始

安裝 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 整合中接收審批、結算和異常狀態。
• 上主網前核對支援範圍中的網路、合約、資產位數和付款方式。