钱包与计费
理解 owner wallet、agent wallet、billing mode 和 spend boundary。
Xenodia 支持 wallet-aware usage，让团队决定由 owner、agent 或受控 fallback account 为调用付费。
概念
| Term | Meaning |
|---|---|
| Owner wallet | 控制 account、organization 或 operator 的钱包。 |
| Agent wallet | 分配给 autonomous 或 semi-autonomous agent 的钱包身份。 |
| Billing mode | 决定调用由 owner balance、agent balance 或 fallback rule 支付的策略。 |
| Spend boundary | 限制 agent 可使用哪些模型、channel 或 workflow 的规则。 |
常见模式
Owner-paid agents
Owner 统一控制支出。Agent 可以调用 API，但计费归属到 owner account。
适合内部 workflow 或一个 operator 下的产品功能。
Self-funded agents
Agent wallet 拥有自己的 balance 或 allowance。
适合需要清晰经济身份、metering 或 settlement boundary 的 agent。
Hybrid fallback
Agent 先使用自己的 wallet，再在明确允许时 fallback 到 owner-controlled billing。
只有 fallback 行为明确时才使用。隐藏 fallback 会让生产支出难以推理。
Wallet setup options
| Option | Use it when | Notes |
|---|---|---|
| Local private key | 本地开发、自托管 operator 或受控 server runtime。 | 放在本地 env 或 secret manager，不要进 browser。 |
| Hosted wallet | 产品团队希望使用托管 operator wallet flow。 | 文档要说明谁能 rotate、revoke 或 top up。 |
| CDP wallet | Agent 或 backend 使用 Coinbase Developer Platform credentials。 | 在 secret store 中配置 CDP_API_KEY_ID 和 CDP_API_KEY_SECRET。 |
| Existing owner wallet | Operator 已有钱包身份。 | 先绑定 owner，再在 owner boundary 下分配 agent wallet 或 API key。 |
CLI 设置：
npx xenodia@latest init本地 wallet material：
npx xenodia@latest init --localOwner and channel boundary
Owner binding 是控制平面。Agent wallet 和 API key 只继承 owner 授予的权限：
- Allowed models or modalities。
- Available channels and fallback behavior。
- Balance source and top-up policy。
- Async media task 在提交后遇到 balance 或 permission 变化时的行为。
- Compromised agent credential 的 revocation 和 rotation path。
文档规则
更新 wallet behavior 时，必须写清：
- 谁付费。
- 余额不足时发生什么。
- 哪些模型或模态可用。
- Billing state 变化后 async media task 是否继续。
- Owner 如何撤销或轮换 agent access。