簽名器

使用 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 管理許可權。
簽名器從可信控制面地址自動取得執行授權公鑰。使用本地固定公鑰時，輪換時同時更新金鑰標識和公鑰檔案。
每個網路使用獨立的簽名器、錢包和授權記錄檔案。
單例項可使用檔案授權記錄。多副本部署應改用具備原子寫入和唯一約束的共享儲存。
日誌只記錄授權標識、錢包地址和錯誤類別，不輸出私鑰、完整執行授權或支付簽名。

本頁內容