API 与代理

您在 Watchdog 页面上能做的一切，也都可以通过 /api/x402 完成：列出和创建监控、修改信号和路由、管理接收者和发送测试、读取和导出提醒历史、查询价格、购买槽位以及充值积分。通过 API 所做的更改会立即显示在应用中，反之亦然。

机器使用钱包登录，而不是使用密码。流程共五步：

1. 使用钱包地址、所请求的权限范围以及可选的令牌名称调用 POST /api/x402/auth/challenge。
2. 响应中包含一条 SIWE 格式（EIP-4361）的登录消息。该消息有效期为 5 分钟，并列出所请求的权限范围。
3. 钱包对该消息签名。支持 EIP-1271 的智能合约钱包同样适用。
4. 使用该消息和签名调用 POST /api/x402/auth/token。
5. 响应中包含一个以 fbx_ 开头的令牌及其到期时间，默认 24 小时。机器通过请求头 Authorization: Bearer 发送该令牌。

令牌只会在该响应中显示。请像保管密码一样保管它。

• read 始终包含在内：读取监控、接收者、警报、价格和账户。
• write 允许进行更改：创建和编辑监控、接收者和设置。
• spend 允许执行消耗积分的操作，例如购买槽位。

示例：只显示警报的仪表板需要 read。为新团队成员设置监控的机器人需要 read 和 write。还要自行购买槽位的代理需要 read、write 和 spend。如果缺少某个权限范围，API 会返回 403，代码为 insufficient_scope，并注明所需的权限范围。

您钱包的所有令牌都列在账户设置 → API 访问中，包括名称、创建日期、到期时间和上次使用时间。“撤销”会立即停用令牌；此操作无法撤回。一个钱包最多可同时拥有 10 个有效令牌。机器也可以通过 DELETE /api/x402/auth/tokens/{id} 自行撤销令牌。

创建内容或消耗积分的请求需要请求头 Idempotency-Key，其值由 8 到 128 个字母、数字、_ 或 - 组成。如果连接中断，机器可以用相同的键再次发送相同的请求，并获得第一次的结果，而不会重复付款。使用相同的键发送不同的请求会被拒绝，并返回 idempotency_key_reused。

如果监控需要槽位或余额不足，API 会返回 402。响应中包含代码 slot_required 或 insufficient_credits、一个现成的购买建议以及用于充值的端点。代理可以自行决定，也可以先询问您。

• 所有操作的 OpenAPI 描述，包括权限范围和错误代码。
• 适用于您的 Webhook 所接收警报的 Webhook Schema v2。
• llms.txt，作为面向语言模型的简短入口。
• 符合 RFC 9727 的 API 目录。
• 面向人类读者、附带代码示例的 API 文档。

一个支持 Model Context Protocol、可供 AI 助手直接连接的服务器已在计划中，但目前尚未提供。在此之前，代理请使用上文所述的 HTTP API。