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 に適用する1回・日次・月次・同時実行の上限。 |
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 spending boundary
Owner binding は支払い関係を確立します。Agent billing policy は次を制御します：
- Billing mode：Agent only、owner only、Agent then owner。
- owner funding を有効にするか。
- 1回、日次、月次の spend limit。
- paid request の最大同時実行数。
- 侵害された Agent credential の revoke / rotate 方法。
Documentation rule
Wallet behavior を公開または更新するときは、次を明記します：
- 誰が支払うか。
- balance が不足したとき何が起きるか。
- 設定済みの1回・日次・月次・同時実行上限。
- owner funding が有効か。
- owner が agent access を revoke / rotate する方法。
操作に対応するメッセージへ署名する
Agent ログインと owner wallet の紐付けは異なる challenge を使います。ログイン署名を紐付けに流用できず、紐付け署名でも Agent にログインできません。
直接紐付ける場合は、owner の access token で POST /v1/me/wallet/challenge に { "wallet_address": "0x…" } を送ります。返されたメッセージの owner ID、wallet、期限、purpose xenodia.owner.wallet.bind.v1 を確認し、その原文に wallet で署名します。同じ owner の access token で PUT /v1/me/wallet に challenge_id と signature を送信してください。Challenge は二分間有効で、一度だけ使用できます。DELETE /v1/me/wallet にも owner の access token が必要です。
このフローの前に、Owner は現在のログイン access token で POST /v1/me/wallet/delegation を呼び出して委任を承認します。Owner API key では Wallet の紐付けを変更できる委任を発行できません。
委任する場合は、紐付け済み Agent が自分の認証情報で POST /v1/me/owner-wallet/challenge を呼び、owner 発行の delegation_token と対象 wallet_address を送ります。この段階では委任 token を消費しません。Wallet の所有者が対象 owner を明記したメッセージを確認して署名し、Agent が POST /v1/me/owner-wallet/bind に delegation_token、challenge_id、signature を送信します。委任 token と challenge は一回限りで、別 owner の証明は拒否されます。
POST /v1/auth/challenge は Agent ログイン専用です。以上の紐付けでは使わないでください。これらの署名でオンチェーン資金が送金されることはありません。