Agent API 认证

Alphio Agent API 将提供两种认证方式：API Key（订阅）与 x402（按量付费稳定币）。

入口：尚未公开发布。下面的流程描述早期试用开放后的设计。

注意

认证设计仍在最终敲定，下文为当前方案，公开发布前可能调整。

---

1. API Key 认证

默认路径。你从 Alphio Account 生成一把 API key，在每次请求中作为 Bearer token 发送。

Header 格式：

Authorization: Bearer <YOUR_API_KEY>

Key 发放：

• 在你的订阅档位开通 Agent API 后，从 Account 页生成。
• 每把 key 与你的账户绑定；同一账户可生成多把。
• Key 可加标签（如 "ci"、"prod"）便于区分。

Key 生命周期：

• 轮转（Rotate） —— 生成新 key、上线、再删除旧 key。在你撤销旧 key 之前两把都有效，所以轮转无中断。
• 撤销（Revoke） —— 在 Account 页一键失效。用已撤销 key 的请求会返回 401 Unauthorized。
• 过期 —— 默认长期有效；后续可能按订阅档位加过期策略。

API Key 认证随付费订阅打包，配额随档位扩展。

---

2. x402（按量付费）

x402 是一种"请求即支付"的协议，使用稳定币（USDC）结算，最初由 Coinbase 推动作为面向 HTTP 计费的开放标准。每次请求附带支付证明，服务端在链上校验后再返回响应。

x402 不需要 Alphio 订阅。你只需要：

• 一个有 USDC 的钱包
• 一个能在每次请求上附加 x402 支付头的客户端

为什么对 Agent API 重要：

• 无前置计费关系。 适合一次性集成、脚本或试验场景，不必为此办完整订阅。
• 细粒度成本控制。 只为发出的请求付费，没有月度起步价。
• 稳定币原生。 USDC 结算契合 Alphio 主打的 "agentic / 链上" 工作流。

x402 与 API Key 在单次请求层面互斥 —— 一次请求只用其中一种。

---

3. 安全最佳实践

• 绝不把 key 嵌进客户端代码。 网页、App、浏览器扩展的源会下发到用户端；嵌入的 API key 会变成公开。请从你自己的后端调用 Agent API，再把响应转发给客户端。
• 定期轮转。 每月或每季度是一个合理基线。任何疑似泄露的 key 视为已失陷，立即撤销。
• 使用分场景 key。 为不同环境（dev / CI / prod）和不同消费方各自分发 key —— 出事时只影响一个消费方。
• 避免日志打完整 key。 调试时只打前缀（例如前 6 位），避免日志变成泄露源。
• 关注异常流量。 某把 key 突发流量峰值通常是泄露的早期信号。

---

4. 限流

限流分别按 API key 和 x402 钱包独立计算，与订阅档位关系另算。

注意

具体的每秒 / 每分钟 / 每日限流数字仍在敲定。客户端实现时请按 429 Too Many Requests 做退避，正式发布时会公布确切阈值。

不管最终数字如何，最佳实践都适用：

• 429 上用带 jitter 的指数退避。
• 在新鲜度允许的地方做缓存 —— 多数 Data API 端点（日历、基本面）更新频率不高。
• 大吞吐集成建议在多把 key 之间分摊负载，而不是在单把 key 上猛打。