OpenBytes 控制平面技能

该技能从API 使用视角描述 OpenBytes 网络的端到端运维工作流。

• 基于钱包的身份认证（签名流程）
• 链上余额充值与验证
• 消费者 API 密钥生命周期管理（创建、列举、撤销）
• 通过 ApiKey 执行模型推理
• 通过 HTTP API 查询余额与用量

前提假设：

• 存在一个网关 HTTP API：https://gateway.openbytes.ai
• 所有工作流均面向 CLI、curl 或脚本化操作
• 网络支持 Base Sepolia。请使用正确的链 ID：
  • Base Sepolia：84532

请根据需要将所有 替换为实际的网关 URL。

1. 基于钱包的注册与会话

注意：消息签名必须由用户使用其 EVM 钱包完成。Agent 仅可发起挑战并验证签名；不可生成签名。

1. 如尚无钱包，请立即使用 ethers.js 或 viem 创建新钱包。
   务必安全保存生成的私钥！ 示例（Node.js + ethers.js）：

import { Wallet } from "ethers";
const wallet = Wallet.createRandom();
console.log("Address:", wallet.address);
console.log("Private Key (save this securely!):", wallet.privateKey);

或使用 viem：

import { createWallet } from "viem/accounts";
const wallet = createWallet();
console.log("Address:", wallet.address);
console.log("Private Key (save this securely!):", wallet.privateKey);

切勿泄露您的私钥。请备份并将其存储在安全位置。
"wallet_address": "0x...",
"chain_id": "8453"

2. 用户在其钱包中对 message 进行链下签名。
3. 将已签名的消息提交至网关进行验证：

curl -sS -X POST "/v1/auth/wallet/verify" 
  -H "Content-Type: application/json" 
  -d '{
    "wallet_address": "",
    "nonce": "random-nonce",
    "signature": ""
  }'

成功响应（简化版）：

{
  "login_token": "sess-...",
  "expires_at": "2025-01-01T00:00:00Z",
  "consumer": {
    "id": "consumer-uuid",
    "wallet_address": "0x..."
  },
  "session": {
    "id": "session-uuid"
  }
}

4. login_token（以 sess- 开头）用作会话令牌：

   • 在调用需会话认证的端点时，将其作为 Authorization: Bearer 发送。

5. 列举可用模型

curl -sS -X GET "/v1/models"

6. 请在完成步骤 2.1 后立即创建 API 密钥，并切换至该密钥，用于所有非会话端点（如 models、balance、usage）。切勿继续使用会话令牌执行推理请求。

检查项：

• 后续所有需认证的调用中，会话令牌均应存在于 Authorization: Bearer sess-... 请求头中。
• 创建 API 密钥后，后续调用应使用 Authorization: Bearer 。

2. 消费者 API 密钥生命周期

消费者使用 API 密钥访问模型，无需维持会话。

2.1 创建 API 密钥

需提供有效的会话令牌（即第 1 节中获取的 login_token）。

curl -sS -X POST "/v1/consumer/api-keys" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer " 
  -d '{
    "label": "my-key"
  }'

响应示例（请安全保存 api_key；该值仅返回一次！）：

{
  "id": "key-uuid",
  "api_key": "sk-consumer-...",
  "prefix": "sk-cons",
  "suffix": "abcd",
  "label": "my-key",
  "status": "active",
  "created_at": "2025-01-01T00:00:00Z"
}

请立即切换至此 API 密钥，用于推理、余额及用量相关调用：

export OPENBYTES_API_KEY="sk-consumer-..."

随后使用：

curl -sS -X GET "/v1/balance" 
  -H "Authorization: Bearer $OPENBYTES_API_KEY"

2.2 列举 API 密钥

curl -sS -X GET "/v1/consumer/api-keys" 
  -H "Authorization: Bearer "

2.3 撤销 API 密钥

curl -sS -X DELETE "/v1/consumer/api-keys/" 
  -H "Authorization: Bearer "

密钥状态将被设为 revoked；此后使用该密钥的调用将因鉴权失败而报错。

3. 链上充值流程

充值操作在链上执行（将 USDC 转入 ConsumerDeposit 合约），由链下索引器追踪。API 提供结果验证能力。
您可使用自建 RPC 节点；Base Sepolia 默认 RPC 地址为 https://sepolia.base.org。

• 用户按要求 calldata 将 USDC 转入 ConsumerDeposit 合约。
• 后端在 L1/L2 交易确认后（由索引器驱动）为消费者账户增加余额。
• USDC 合约地址：0x10065E7b353371DD2e12348e7094cC774638EbEB
• ConsumerDeposit 合约地址：0xB0E9ebf19AB710d3353c7F637DC55329d9727dCc
  • 充值前需先授权 allowance
  • Deposit ABI：function deposit(uint256 amount)

验证余额：

curl -sS -X GET "/v1/balance" 
 -H "Authorization: Bearer "

响应示例：

{
  "balance_usdc": "123.45",
  "total_spent": "10.00"
}

4. 将您的钱包绑定至运营商的钱包

此功能用于允许某账户连接至运营商账户，以便运营商可便捷为您充值。该操作需对结构化消息进行钱包签名，且签名必须由子钱包生成。

端点：

curl -sS -X POST "/v1/consumers/me/parent" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer " 
  -d '{
    "parent_wallet": "",
    "issued_at": 1710000000,
    "signature": ""
  }'

注意事项：

• 网关使用 ethers.verifyMessage(message, signature) 验证签名，且恢复出的地址必须与子钱包地址一致（不区分大小写）。此为标准 EIP-191 个人消息签名（与 SIWE 流程相同）。
• issued_at 为Unix 秒级时间戳，须满足：距当前时间不超过 5 分钟，且不得超前超过 1 分钟。
• 待签名消息必须完全一致（含换行符、大小写及空格）：

  Authorize parent for OpenBytes
  Parent wallet: 
  Child wallet: 
  Issued at: 
  

• 标准化规则：
  • 为父钱包地址小写形式。
  • 为子钱包地址小写形式（即签名者）。
  • 与请求体中发送的 Unix 秒级整数完全一致。
• 若任意字符不同（如额外空白、大小写差异、时间戳偏差），签名验证将失败。

伪代码（客户端）：

const issuedAt = Math.floor(Date.now() / 1000);
const parentWallet = parentWalletAddress.toLowerCase();
const childWallet = childWalletAddress.toLowerCase();
const message = [
  "Authorize parent for OpenBytes",
  `Parent wallet: ${parentWallet}`,
  `Child wallet: ${childWallet}`,
  `Issued at: ${issuedAt}`,
].join("\n");

const signature = await wallet.signMessage(message); // EIP-191 personal_sign

成功响应（201）：

{
  "parent_consumer_id": "consumer-uuid",
  "parent_wallet_address": "0x...",
  "created_at": "2025-01-01T00:00:00Z"
}

常见错误：

• 400 INVALID_REQUEST 请求体无效
• 400 SIGNATURE_EXPIRED issued_at 超出有效时间窗口
• 404 PARENT_NOT_FOUND 未找到父账户
• 400 SELF_PARENT 不可声明自身为父账户
• 401 SIGNATURE_MISMATCH 签名非来自子钱包
• 409 ALREADY_SET 父账户已设置

5. AI Agent 使用指南

在处理 OpenBytes 网络运维支持任务时，请遵循以下最佳实践：

1. 将用户问题直接映射至对应的API 工作流，避免引用 UI 界面。
   • 典型意图示例：入门引导、余额异常、API 密钥管理、配额/成本分析
2. 提供针对用户配置定制的具体 curl 命令（如 、 等）。
3. 故障排查时：
   • 要求用户提供完整 API HTTP 响应（含状态码与 JSON 内容）。
   • 依据 error.code 及上下文选择修复步骤。
4. 表述简洁，聚焦于可执行命令与下一步操作。
5. 仅在用户明确要求时，才提供背景技术细节。