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 | Per-request, daily, monthly, and concurrency limits applied to an Agent. |
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 spending boundary
Owner binding establishes the funding relationship. The Agent billing policy controls:
- Billing mode: Agent only, owner only, or Agent then owner.
- Whether owner funding is enabled.
- Per-request, daily, and monthly spend limits.
- Maximum concurrent paid requests.
- Revocation and rotation for compromised Agent credentials.
Documentation rule
When you publish or update wallet behavior, document:
- Who pays.
- What happens when balance is insufficient.
- The configured per-request, daily, monthly, and concurrency limits.
- Whether owner funding is enabled.
- How owners revoke or rotate agent access.
Sign the message for the intended operation
Agent sign-in and owner wallet binding use different challenges. A login signature cannot authorize a wallet binding, and a binding signature cannot sign in an Agent.
For direct owner binding, sign in as the owner and use an access token to request POST /v1/me/wallet/challenge with { "wallet_address": "0x…" }. Check the returned message: it names the owner account, wallet, expiry and purpose xenodia.owner.wallet.bind.v1. Sign the exact message with the wallet, then submit challenge_id and signature to PUT /v1/me/wallet using the same owner's access token. Challenges expire after two minutes and can be consumed once. DELETE /v1/me/wallet also requires an owner access token.
Before this flow, the Owner must issue the delegation using POST /v1/me/wallet/delegation with a current login access token. An Owner API key cannot create this wallet-changing delegation.
For delegated binding, the already linked Agent first requests POST /v1/me/owner-wallet/challenge with the owner's delegation_token and intended wallet_address, authenticated as that Agent. This does not consume the delegation. The wallet holder signs the returned owner-specific message. The Agent then sends delegation_token, challenge_id and signature to POST /v1/me/owner-wallet/bind. The delegation and challenge are both single use. A proof for another owner is rejected.
POST /v1/auth/challenge remains exclusively the Agent login challenge. Do not reuse it in either owner binding flow. None of these signatures transfers on-chain funds.