Wallets and Billing
owner wallet、agent wallet、billing mode、spend boundary を理解する。
Xenodia は wallet-aware usage をサポートし、owner、agent、または制御された fallback account のどれが利用料金を支払うかを決められます。
Concepts
| Term | Meaning |
|---|---|
| Owner wallet | account、organization、operator を制御する wallet。 |
| Agent wallet | autonomous または semi-autonomous agent に割り当てる wallet identity。 |
| Billing mode | owner balance、agent balance、fallback rule のどれで支払うかを決める policy。 |
| Spend boundary | agent が使える model、channel、workflow を制限する rule。 |
Common patterns
Owner-paid agents
Owner が支出を一元管理します。Agent は API を呼び出せますが、課金は owner account に解決されます。
内部 workflow や 1 operator 配下のプロダクト機能に向いています。
Self-funded agents
Agent wallet が自身の balance または allowance を持ちます。
明確な経済 identity、metering、settlement boundary が必要な agent に向いています。
Hybrid fallback
Agent がまず自身の wallet を使い、明示的に許可された場合に owner-controlled billing に fallback します。
Fallback behavior は必ず明示してください。隠れた fallback は本番支出を読みにくくします。
Wallet setup options
| Option | Use it when | Notes |
|---|---|---|
| Local private key | local development、自ホスト operator、制御された server runtime。 | local env または secret manager に置き、browser code に入れない。 |
| Hosted wallet | managed operator wallet flow を使いたい場合。 | rotate、revoke、top up できる主体を明記する。 |
| CDP wallet | Coinbase Developer Platform credentials を使う agent / backend。 | CDP_API_KEY_ID と CDP_API_KEY_SECRET を runtime secret store に設定する。 |
| Existing owner wallet | operator が既存 wallet identity を持つ場合。 | owner を先に bind し、その boundary 下で agent wallet / API key を割り当てる。 |
CLI setup：
npx xenodia@latest initlocal wallet material を読む場合：
npx xenodia@latest init --localOwner and channel boundary
Owner binding は control plane です。Agent wallet と API key は owner が許可した権限だけを継承します：
- Allowed models or modalities。
- Available channels and fallback behavior。
- Balance source and top-up policy。
- 送信後に balance / permission が変わった場合の async media task の扱い。
- 侵害された agent credential の revocation と rotation path。
Documentation rule
Wallet behavior を公開または更新するときは、次を明記します：
- 誰が支払うか。
- balance が不足したとき何が起きるか。
- どの model / modality が許可されるか。
- billing state 変更後も async media task が続くか。
- owner が agent access を revoke / rotate する方法。