Use this page when you want the raw Xenodia skill files for your agent runtime. If the installed skill is not enough for a safe API call, open the linked online docs directly instead of guessing undocumented parameters.
---
name: xenodia
description: Use existing Xenodia model and media APIs, wallet authentication, account credits and explicit x402 top-ups.
---
# Xenodia Gateway Skill
API origin: `https://api.xenodia.xyz`; OpenAI-compatible base: `https://api.xenodia.xyz/v1`.
Current API reference: https://docs.xenodia.xyz/docs/quickstart
## Existing account and wallet
Use the existing owner API key or agent wallet. Owner keys are managed at https://www.xenodia.xyz/user-settings/owner-key. Bind agent addresses at https://www.xenodia.xyz/user-settings/my-agents. Do not create a replacement wallet when an existing identity is available.
The Node.js CLI requires Node 24. It supports local wallets and CDP wallet signing. Local keys are read from `EVM_PRIVATE_KEY`, an explicit `XENODIA_KEY_FILE`, or `$XDG_DATA_HOME/xenodia/agent.key` (default `~/.local/share/xenodia/agent.key`). Existing `.xenodia_agent_key` files require an explicit path to preserve their identity; keep them outside the repository with permissions 0600. Do not put keys in shell command text, logs, chat, or version control. Pass secrets through the runtime environment or a protected file.
CDP uses `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET` and optionally `CDP_WALLET_NAME`. Select the intended existing account; do not assume the first account belongs to this task. The CLI reads these values from the environment. Never print a shell profile to find secrets.
```bash
npx xenodia init # Install skill integration and show setup instructions
npx xenodia init --local # Generate a wallet only if a new identity is intended
npx xenodia balance
npx xenodia models
npx xenodia get-token # Prints a credential; capture privately
npx xenodia get-api-key # Prints a credential; capture privately
npx xenodia chat gpt-5.4 "Hello"
```
Select a model ID returned by the current catalog before a paid call. Chat/media calls consume credits. A zero balance is not a reason to initiate payment without an authorized amount and wallet.
## Authentication and discovery
1. POST `/v1/auth/challenge` with `wallet_address`.
2. Sign the exact returned `message` using EIP-191. Never construct a guessed challenge.
3. POST `/v1/auth/verify` with `challenge_id` and `signature`.
4. Use `tokens.access_token` as a Bearer credential. Respect the returned expiration metadata and refresh via `/v1/auth/refresh` when applicable. Access tokens and long-lived API keys are different credentials.
5. GET `/v1/credits/balance` for account credits. GET `/v1/models` for discovery; model discovery does not initiate a top-up. Owner and agent funding details are returned separately where applicable.
Local signing sends a signature, not a raw private key, to Xenodia. Protect the key and the host running it; do not promise absolute security or imply that wallet assets cannot be lost.
## Explicit x402 top-up
After the owner has authorized the amount and wallet, use the existing command:
```bash
npx xenodia topup --amount 5
```
The top-up endpoint is `/v1/payments/topup`. Read its current 402 payment requirements and verify the network, asset, recipient and amount before signing. A transfer may settle even if the response is lost; check the resulting account balance and transaction before attempting another payment. Never turn model discovery or a routine health check into a paid transaction.
Stripe and x402 are the supported payment methods. Infini and AXON have been permanently retired; never initiate a payment or redeem a transaction through either legacy channel. Historical transactions remain available in payment history.
## Model and media use
Use `/v1/models` and capability discovery for current input fields, request modes, prices and model availability. Text requests use `/v1/chat/completions`; image and video requests use their documented generation endpoints, with `/v1/tasks/{taskId}` for asynchronous results. The installed `xenodia-media` skill and online docs provide examples. Keep internal routing out of user instructions.
Before editing an existing agent provider configuration, verify the endpoint, model availability and account credits. Preserve the previous configuration for recovery. Never print credentials as part of a status report.
## Legacy Python clients
The website also provides `xenodia_client.py` (local signing; `requests` and `eth-account`) and `xenodia_cdp_client.py` (CDP signing; `requests` and `cdp-sdk`). They retain `init`, `check-wallet`, `balance`, `models`, `check-model`, `get-token`, `get-api-key` and `chat` commands. They use the same challenge/verify, balance and model endpoints. Their network requests have timeouts and refuse redirects. Prefer the maintained Node CLI for x402 top-ups.