钱包与计费

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 生效的单次、每日、每月和并发限制。

常见模式

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 --local

Owner 与消费边界

Owner binding 建立付款关系。Agent 计费策略控制：

计费模式：仅 Agent、仅 owner，或先 Agent 后 owner。
是否允许 owner 代付。
单次、每日和每月消费上限。
最大并发付费请求数。
Agent 凭证受损后的撤销与轮换方式。

文档规则

更新 wallet behavior 时，必须写清：

谁付费。
余额不足时发生什么。
已配置的单次、每日、每月和并发限制。
是否允许 owner 代付。
Owner 如何撤销或轮换 agent access。

按操作用途签署钱包消息

Agent 登录与主账户钱包绑定使用不同挑战。登录签名不能授权绑定，绑定签名也不能用于 Agent 登录。

直接绑定时，以主账户 access token 调用 POST /v1/me/wallet/challenge，请求体为 { "wallet_address": "0x…" }。核对返回消息中的主账户 ID、钱包地址、有效期以及用途 xenodia.owner.wallet.bind.v1，使用钱包对原文签名，再以同一主账户 access token 向 PUT /v1/me/wallet 提交 challenge_id 与 signature。挑战有效期为两分钟，只能消费一次；解绑接口 DELETE /v1/me/wallet 同样需要主账户 access token。

开始前，主账户必须使用当前登录会话的 access token 调用 POST /v1/me/wallet/delegation 批准委托；Owner API key 不能签发这种可改变钱包绑定的委托。

委托绑定时，已关联的 Agent 使用自身凭证调用 POST /v1/me/owner-wallet/challenge，提交主账户签发的 delegation_token 和待绑定的 wallet_address。这一步不会消费委托令牌。钱包持有人核对并签署包含目标主账户的消息，Agent 再向 POST /v1/me/owner-wallet/bind 提交 delegation_token、challenge_id 和 signature。委托与挑战都只能使用一次，其他主账户的证明会被拒绝。

POST /v1/auth/challenge 只用于 Agent 登录，不能用于以上绑定流程。这些签名均不执行链上资金转账。

钱包与计费

本页内容