Wallets and Billing
Understand owner wallets, agent wallets, billing modes, and how spend boundaries should be documented.
Xenodia supports wallet-aware usage so teams can decide whether an owner, an agent, or a controlled fallback account pays for usage.
Concepts
| Term | Meaning |
|---|---|
| Owner wallet | The controlling wallet for an account, organization, or operator. |
| Agent wallet | A wallet identity assigned to an autonomous or semi-autonomous agent. |
| Billing mode | The policy that decides whether calls are paid by owner balance, agent balance, or a fallback rule. |
| Spend boundary | A rule that limits which models, channels, or workflows an agent may use. |
Common patterns
Owner-paid agents
The owner controls spend centrally. Agents can call the API, but billing resolves to the owner account.
Use this when the agent is an internal workflow or a product feature under one operator.
Self-funded agents
The agent wallet carries its own balance or allowance.
Use this when agents need clear economic identity, metering, or settlement boundaries.
Hybrid fallback
The agent spends from its own wallet first, then falls back to owner-controlled billing if allowed.
Use this only when fallback behavior is explicit. Hidden fallback makes production spend difficult to reason about.
Wallet setup options
| Option | Use it when | Notes |
|---|---|---|
| Local private key | Local development, self-hosted operators, or tightly controlled server runtimes. | Keep the key in local env or a secret manager. Do not ship it in browser code. |
| Hosted wallet | Product teams want a managed operator wallet flow. | Document who can rotate, revoke, or top up the wallet. |
| CDP wallet | Agents or backends use Coinbase Developer Platform credentials. | Configure CDP_API_KEY_ID and CDP_API_KEY_SECRET in the runtime secret store. |
| Existing owner wallet | The operator already has a wallet identity. | Bind the owner first, then assign agent wallets or API keys under that owner boundary. |
For CLI setup, start with:
npx xenodia@latest initUse local mode when the runtime should read local wallet material:
npx xenodia@latest init --localOwner and channel boundary
Owner binding is the control plane. Agent wallets and API keys inherit only the permissions the owner grants:
- Allowed models or modalities.
- Available channels and fallback behavior.
- Balance source and top-up policy.
- Async media task behavior if balance or permissions change after submission.
- Revocation and rotation path for compromised agent credentials.
Documentation rule
When you publish or update wallet behavior, document:
- Who pays.
- What happens when balance is insufficient.
- Which models or modalities are allowed.
- Whether async media tasks can continue after billing state changes.
- How owners revoke or rotate agent access.