Peer

peer-cli

Peer 的标准 Agent 接口：一个以 JSON 为先的 CLI、本地和托管的 MCP 服务，以及一份适用于协议、索引器、市场、结账和 Peer Cash 工作流的生成式契约。

• 文档和面向 Agent 的文本：https://agents.peer.xyz
• 精确的 CLI 架构：agents/tool-catalog.json
• 错误契约：agents/error-catalog.json
• 运行时配置和数量： agents/runtime-manifest.json

生成的文件来自运行时注册表。请勿在文档中手动维护第二份命令列表。

安装

需要 Node.js 22 或更高版本。

此软件包名为 peer-protocol-cli；请勿安装名称相近但无关的未限定作用域软件包 peer-cli。

npm install --global [email protected]
peer --help

无需全局安装即可运行：

npx -y [email protected] quote --from USD --amount 100 --platform wise

默认情况下，成功输出为 JSON。错误始终通过 stderr 使用标准 JSON 错误封装格式。--format table 仅更改面向用户的成功输出。

安全模型

读取命令会立即执行。可能修改状态的命令会先返回交易或 API 预览，只有进程收到 --yes 后才会执行。

签名者材料从 PEER_PRIVATE_KEY 或 --wallet-path 解析。支持在命令行中传入私钥，但它会显示在进程列表中；建议使用环境变量或仅所有者可读的钱包文件。持久化配置和结账缓存均以仅所有者可访问的权限写入。

除非有意允许该进程中的每个写入工具无需第二次 CLI 预览便广播，否则切勿使用 --yes 启动具备写入能力的 MCP 进程。

MCP 配置

peer mcp 必须指定以下三种配置之一：

• read-only — 默认协议读取和 Peer Cash 读取。不签名或广播。
• cash — 完整的、托管权限分离的 peer_cash_* 工具集。它会准备未签名的交易计划，但绝不接受私钥、签名或广播。
• full — 所有通用 CLI 支持的 MCP 工具，以及 Peer Cash。通用写入工具仍会先提供预览，除非启动 MCP 进程时指定了全局 --yes。

当前工具数量由 agents/runtime-manifest.json 生成。

{
  "mcpServers": {
    "peer": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "mcp",
        "--profile",
        "read-only"
      ]
    }
  }
}

使用 --profile cash 运行便携式 Peer Cash 工作流，或使用 --profile full 运行完整的操作员工具集。

托管的 MCP 服务仅通过 Streamable HTTP 暴露 read-only 配置：

https://mcp.peer.xyz/mcp

使用 peer mcp --transport http 自行运行相同的传输方式。HTTP 不支持 cash 和 full 配置；这些具有权限的配置仍作为本地 stdio 进程运行。

Peer Cash

已停用的独立 peer-cash-mcp 服务现已整合到此处。其工具名称和托管权限边界保持不变：

1. peer_cash_capabilities / peer_cash_source_capabilities — 获取实时出款渠道，以及 Relay 支持的源链和代币。
2. peer_cash_fill_stats / peer_cash_buyer — 查看历史成交凭证和买方协议历史记录。
3. peer_cash_quote_source / peer_cash_relay_status — 查询并跟踪跨链路由，将资金转入 Base USDC，且不授予签名权限。
4. peer_cash_estimate — 按当前预言机汇率估算收到的法币金额。
5. peer_cash_prepare — 返回有序的未签名授权和存款交易。
6. peer_cash_finalize — 将已确认的收据解析为持久化的 depositId。
7. peer_cash_order / peer_cash_orders — 恢复并查看订单。
8. peer_cash_prepare_access_policy、peer_cash_prepare_withdraw 和 peer_cash_prepare_top_up — 准备后续交易。

Base USDC 金额以 6 位小数的基本单位表示为十进制字符串：100 USDC 为 100000000。估算值不是锁定报价；具有约束力的 Chainlink 汇率会在买方成交时确定。

当 Agent 主机支持 Agent Skills 时，可从 skills/peer-cash/SKILL.md 安装打包的便携式技能。

配置

配置按以下顺序解析：

1. CLI 标志
2. 环境变量
3. ~/.peer/config.json
4. 运行时默认值

常用设置：

• PEER_ENV：production、preproduction 或 staging
• PEER_PRIVATE_KEY / PEER_WALLET_PATH：通用写入命令的签名材料
• PEER_RPC_URL：Base RPC 覆盖项
• PEER_API_KEY：需要时使用的 Curator API 密钥
• PEER_INDEXER_API_KEY / PEER_INDEXER_URL：索引器覆盖项
• PEER_MARKET_API_KEY / PEER_MARKET_BASE_URL：Peerlytics 访问配置
• PEER_PAY_API_KEY / PEER_PAY_BASE_URL：托管结账访问配置
• PEER_BASE_API_URL：Curator 覆盖项。默认值根据 PEER_ENV 确定： api.zkp2p.xyz、api-preprod.zkp2p.xyz 或 api-staging.zkp2p.xyz。
• PEER_CASH_RPC_URL、PEER_CASH_API_KEY、PEER_CASH_REFERRAL_CODE 和 PEER_CASH_REFERRER：现金配置文件覆盖项

使用 peer config show、set、unset 和 reset 管理持久化的本地 设置。peer config show 会隐藏机密值。凭据优先使用环境变量。

命令类别

CLI 涵盖：

• 报价、收款方注册和收款方哈希解析
• 存款生命周期、支付方式、货币、预言机配置和批量更新
• 意图、预意图钩子、履约、释放和清理
• StakeVault 存款、取款、授权、索引数据新鲜度和已到期的拒付释放
• IntentGuardian 策略、实时扩展报价、付款方注资和预览优先的意图扩展
• ProtocolViewer 和索引器读取，包括原始 GraphQL 应急接口
• 金库、费率管理器、委托、费用和快照
• Peerlytics 市场、浏览器、历史记录、归因和 API 密钥操作
• USDC 余额和转账
• 托管结账创建、读取、取消和本地恢复缓存
• 本地配置和环境检查

运行 peer --help、peer <family> --help，或查看生成的工具目录，了解当前准确的路径、 标志、架构、身份验证要求和危险标记。

每条命令也支持 --params <json> 和 --params-file <path>。类型化 标志优先于原始值。

开发

此代码库使用 npm 和已提交的 package-lock.json。

npm install
npm run dev -- quote --from USD --amount 100 --platform wise
npm run check

npm run build 会在打包 peer 和公开的 MCP 库入口点之前，重新生成所有 Agent 目录。更改联网 流程或结账行为后，请运行 npm run test:e2e。

agents.peer.xyz 的文档应用由 zkp2p/zkp2p-clients 中的 clients/agents 负责；本代码库负责可执行 运行时、软件包清单、可移植技能以及其文档中描述的生成合约。

UPI

生产、预生产和暂存环境均支持 UPI/INR，与 @zkp2p/sdk 目录一致。peer config platforms 会将其与其他 支付渠道一同列出，peer quote --from INR --amount 100 --platform upi 则会请求 报价。存款创建、收款方注册和意图预览也接受相同的平台。