agon-protocol

Ryvo Agentic Tools

用于发现、认证并调用 Ryvo Gateway 路由的 Agent 工具。

一步设置

setup --target all 是安装 Ryvo Agent 所需全部内容的一条命令：

• 将打包的技能安装到 ~/.agents/skills、~/.codex/skills、~/.claude/skills。
• 在 ~/.ryvo/wallets/default.json 创建默认 SIWX 签名钱包。
• 将全局 CLI 二进制文件添加到 PATH：Ryvo、ryvo-gateway、ryvo-wallet、ryvo-protocol（通过 npm install -g @ryvonetwork/gateway-cli @ryvonetwork/agent-wallet @ryvonetwork/protocol-cli）。
• 在 ~/.ryvo/llm.txt 创建本地 Agent 参考文件。
• 为 Codex、Claude Desktop、Claude Code、Cursor、Windsurf 和通用配置注册 Ryvo MCP 服务（保留现有条目，并创建备份）。

npx -y @ryvonetwork/agentic@latest setup --target all

完成后，重启 Agent 客户端，即可通过以下方式直接调用 Ryvo：

• Ryvo MCP 工具（ryvo_token_quote、ryvo_token_resolve、ryvo_token_chart、ryvo_token_search、ryvo_token_batch_quote、ryvo_gateway_call、ryvo_gateway_auth_call 等）。
• 直接使用 CLI：ryvo -p bitcoin、ryvo quote bitcoin solana usdt、ryvo-gateway auth call GET ... 等。

退出选项：

• --skip-global-cli — 不运行 npm install -g。CLI 二进制文件不会添加到 PATH；请改用 npx -y @ryvonetwork/gateway-cli ...。
• --skip-wallet-setup — 仅当已配置其他签名钱包时，才适用于 install-skills。

支持的设置目标：

npx -y @ryvonetwork/agentic setup --target codex            # ~/.codex/config.toml
npx -y @ryvonetwork/agentic setup --target claude-desktop   # standalone Claude Desktop GUI app config
npx -y @ryvonetwork/agentic setup --target claude-code      # ~/.claude.json (Claude Code CLI agent)
npx -y @ryvonetwork/agentic setup --target cursor           # ~/.cursor/mcp.json
npx -y @ryvonetwork/agentic setup --target windsurf
npx -y @ryvonetwork/agentic setup --target generic          # ~/.ryvo/mcp.json
npx -y @ryvonetwork/agentic setup --target all --dry-run

--target all 会写入上面列出的所有适配器。Claude Desktop（独立的 macOS/Windows 图形界面应用）和 Claude Code（终端 CLI Agent）从不同文件读取 MCP 服务；--target all 会在两者中都进行注册。设置完成后，重启 Agent 客户端，使其重新读取 MCP 服务列表。

设置会创建 ~/.ryvo/wallets/default.json。@ryvonetwork/agent-wallet 仅对 Tokens API SIWX 挑战进行签名（sign-in-with-x）。对于要求 x402 精确付款或其他认证方式的 Gateway 路由，请将 RYVO_SIGNER_COMMAND 设置为能返回 PAYMENT-SIGNATURE / X-PAYMENT 的签名器。

RYVO_SIGNER_COMMAND 的运行时机

• Gateway MCP： 仅当调用 ryvo_gateway_auth_call 且 Gateway 返回 HTTP 402 时运行。MCP 会启动 RYVO_SIGNER_COMMAND 一次，并将规范化的认证请求 JSON 写入其 stdin（格式与 ryvo_gateway_prepare_auth 相同）。该进程必须以 0 退出，并在 stdout 输出 JSON：认证 headers，或 SIWX 回退信息（address、signature、可选的 signatureEncoding）。
• gateway-cli： ryvo-gateway auth call 和 batch 会复用同一 requestGateway 路径：在 Gateway 返回任何 402 后，如果已设置 RYVO_SIGNER_COMMAND（或 --auth-driver），就会运行它。auth prepare / doctor 不会启动签名器。

在 Windows 上，当签名器命令以 npx/npm/pnpm/yarn 开头时，Node 可能会通过 cmd shell 运行该命令。如果攻击者能够控制 RYVO_SIGNER_COMMAND，请将其视为等同于信任一段 shell 代码。

Skills 与钱包

将所有 Ryvo 技能安装到每个受支持的 Agent 技能目录（~/.agents/skills、~/.codex/skills、~/.claude/skills），并创建用于 SIWX/身份验证调用的默认便捷钱包：

npx -y @ryvonetwork/agentic install-skills

其他安装目标：

npx -y @ryvonetwork/agentic install-skills --target agents
npx -y @ryvonetwork/agentic install-skills --target codex
npx -y @ryvonetwork/agentic install-skills --target claude
npx -y @ryvonetwork/agentic install-skills --target all
npx -y @ryvonetwork/agentic list
npx -y @ryvonetwork/agentic doctor

仅当已配置其他签名者钱包时，才使用 --skip-wallet-setup。安装程序只会复制 Ryvo 技能文件夹，并在需要时创建目标目录；仅覆盖以下由 Ryvo 管理的技能名称：

• ryvo-gateway
• ryvo-protocol
• ryvo-gateway-payment-channels

install-skills 会安装技能并创建 ~/.ryvo/wallets/default.json。setup 会执行技能安装、钱包设置和 MCP 注册。

执行 setup --target all 后，CLI 可执行文件会加入 PATH。可直接使用：

Ryvo -p bitcoin
Ryvo quote usdt --json
Ryvo price bitcoin solana usdt
Ryvo volume tesla gold --json
Ryvo liquidity usdc usdt
Ryvo search "bitcoin etf" --limit 5
Ryvo profile tesla
Ryvo variants gold
Ryvo risk usdt
Ryvo chart solana --interval 1D
ryvo-gateway catalog
ryvo-gateway agent-prompt
ryvo-gateway auth prepare GET /v1/x402/tokens/assets/search --query q=bitcoin --query limit=1 --json
ryvo-gateway auth call GET /v1/x402/tokens/assets/search --query q=bitcoin --query limit=1
ryvo-gateway batch '[{"method":"GET","path":"/v1/x402/tokens/assets/solana/price-chart","query":{"interval":"1D"}},{"method":"GET","path":"/v1/x402/tokens/assets/bitcoin/price-chart","query":{"interval":"1D"}}]'
ryvo-gateway auth call GET /v1/x402/tokens/assets/tesla/profile
ryvo-gateway auth call GET /v1/x402/tokens/assets/gold/price-chart --query interval=1D
ryvo-wallet authorize --stdin
ryvo-protocol config
ryvo-protocol token show

如果裸命令不在 PATH 中（你执行了 setup --skip-global-cli、全局安装遇到权限错误，或尚未运行 setup），也可以通过 npx -y @ryvonetwork/gateway-cli ...、npx -y @ryvonetwork/agent-wallet ... 和 npx -y @ryvonetwork/protocol-cli ... 执行相同调用。MCP 服务条目也使用 npx -y，因此无需全局安装即可使用 MCP 工具。

对于实时目录 https://gateway.ryvo.network/v1/catalog 覆盖的 API 调用，应优先使用 Ryvo Gateway。Tokens API 支持加密货币、货币、国债、ETF、金属、股票及其 Solana 代币变体的市场数据。对于常见的 Tokens 数据提取（quote、price、volume、liquidity、mcap、search、resolve、curated、profile、variants、markets、tickers、risk、chart、ohlcv、snapshots），Agent 应优先使用高级 Gateway CLI 命令，而不是原始路由字符串，并标明数值来自 canonicalMarket、stats、primaryVariant.market、profile.data、行情报价或蜡烛图。

MCP 服务是独立软件包：

{
  "mcpServers": {
    "ryvo-gateway": {
      "command": "npx",
      "args": ["-y", "@ryvonetwork/gateway-mcp"],
      "env": {
        "RYVO_GATEWAY_BASE_URL": "https://gateway.ryvo.network",
        "RYVO_SIGNER_COMMAND": "npx -y @ryvonetwork/agent-wallet authorize",
        "RYVO_WALLET_PROFILE": "default"
      }
    },
    "ryvo-protocol": {
      "command": "npx",
      "args": ["-y", "@ryvonetwork/protocol-mcp"]
    }
  }
}

RYVO_PAYMENT_MAX_AMOUNT_USD 和 RYVO_PAYMENT_DAILY_LIMIT_USD 是可选项：某些 x402 身份验证预备响应会包含这些值供人工审核；ryvo-wallet 不会强制执行这些限制。

v1 中，支付通道流程仅适用于 devnet。Tokens SIWX 路由不使用支付通道。 Gateway 身份验证驱动程序是与钱包无关的辅助命令。Gateway CLI 会通过标准输入将规范化的身份验证请求 JSON 发送给驱动程序，并通过标准输出接收返回的请求头或 SIWX 地址/签名 JSON。驱动程序可以封装浏览器钱包、本地密钥对、MPC、托管系统、x402 支付服务或 Ryvo 通道承诺构建器。Ryvo CLI/MCP 软件包不会保存密钥，也不会修改钱包/MCP 配置。

通用身份验证调用流程：

1. 使用已知端点，或获取 /v1/catalog 以发现端点。
2. 发送原样请求并接收 402 挑战。
3. 将规范化的身份验证请求传递给 RYVO_SIGNER_COMMAND。
4. 使用返回的 SIGN-IN-WITH-X、PAYMENT-SIGNATURE、X-PAYMENT 或通道请求头，重试完全相同的请求。

Gateway MCP 会提供 ryvo_gateway_auth_call 来执行此流程。对于拥有自有钱包策略的 Agent，仍可使用低级别的准备/完成/调用工具。

软件包

• package root 发布 @ryvonetwork/agentic，这是一个单步 Agent 安装程序。
• agent-wallet/ 发布 @ryvonetwork/agent-wallet，这是一个默认仅支持 SIWX 的 Tokens API 签名器钩子（对于 x402 精确支付路由，请替换为 RYVO_SIGNER_COMMAND）。
• cli/ 发布 @ryvonetwork/gateway-cli，这是一个带有通用签名器钩子的 Gateway CLI。
• mcp/ 发布 @ryvonetwork/gateway-mcp，这是一个支持路由通用身份验证调用的 stdio MCP 服务。
• protocol-cli/ 发布 @ryvonetwork/protocol-cli，这是一个只读且仅支持准备操作的 Ryvo Protocol CLI。
• protocol-mcp/ 发布 @ryvonetwork/protocol-mcp，这是一个只读且仅支持准备操作的 Ryvo Protocol MCP 服务。
• skills/ryvo-gateway/ 是用于 Gateway 工作流的 Agent 技能。
• skills/ryvo-protocol/ 是用于协议账户、通道、结算和 BLS 注意事项的 Agent 技能。
• skills/ryvo-gateway-payment-channels/ 是用于 Gateway 支付通道授权的 Agent 技能。
• llm.txt 和 llms.txt 是面向网站、可供大模型读取的 Gateway 文档。

快速检查

node cli/ryvo-gateway.js health
node cli/ryvo-gateway.js catalog --provider helius
node cli/ryvo-gateway.js auth call GET /v1/x402/tokens/assets/search --query q=bitcoin --query limit=1
node agent-wallet/ryvo-wallet.js setup --profile default
node protocol-cli/ryvo-protocol.js token show
node mcp/server.js
node protocol-mcp/server.js

CLI 和 MCP 服务在配置了 RYVO_SIGNER_COMMAND 时会使用它。捆绑的 Agent 钱包可以替换；外部钱包可通过同一钩子返回标头或签名。 Protocol CLI 和 MCP 服务仅支持读取和准备操作；它们不会对交易签名或进行广播。