xapi-to 0.1.18 → 0.1.19

package/skills/xapi/guides/ai.md

@@ -0,0 +1,200 @@
+# AI Guide
+
+Complete guide for AI capabilities via xAPI — text chat, summarize/rewrite, embeddings, asynchronous image/video generation, text-to-speech, and speech-to-text.
+
+All AI endpoints are **built-in capabilities** (`--source capability`). Pass parameters with `--input` as a JSON object.
+
+This guide covers CLI capabilities. For Claude Code, Anthropic/OpenAI SDKs, streaming HTTP APIs, and Gateway routing, read `guides/ai_gateway.md`. For full-duplex OpenAI Realtime or provider-native streaming ASR/TTS, read `guides/ws_gateway.md`.
+
+## Contents
+
+- [Text](#text-synchronous-or-sse-streaming)
+- [Image generation](#image-generation)
+- [Video generation](#video-generation)
+- [Speech generation](#speech-generation)
+- [Speech transcription](#speech-transcription)
+- [Error handling](#error-handling)
+
+## Text (synchronous or SSE streaming)
+
+### Chat completions
+
+```bash
+# Fast — low latency, good for simple tasks
+npx xapi-to call ai.text.chat.fast \
+  --input '{"messages":[{"role":"user","content":"Explain quantum computing in one sentence"}]}'
+
+# Reasoning — slower, more thorough for analysis
+npx xapi-to call ai.text.chat.reasoning \
+  --input '{"messages":[{"role":"user","content":"Analyze the pros and cons of microservices"}]}'
+
+# Auto — you name the model; the gateway auto-routes to the best upstream with fallback
+npx xapi-to call ai.text.chat.auto \
+  --input '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+- `messages` follows the standard `[{role, content}]` chat format. `fast` and `reasoning` accept `system` | `user` | `assistant`; `auto` documents `user` | `assistant`.
+- **When to choose which:** `fast` for quick/cheap replies, `reasoning` for multi-step analysis, `auto` when you want to specify a particular model and let the gateway pick the healthiest provider that serves it (defaults to `deepseek-v4-pro` if `model` is omitted).
+- `ai.text.chat.auto.priority` accepts `default`, `cost`, `speed`, or `quality`. `cost` affects candidate ranking; `speed` and `quality` are accepted routing labels but currently have no dedicated rankers, so do not promise a distinct latency or quality outcome. See `guides/ai_gateway.md` for routing details.
+- Add `--stream` to `ai.text.chat.fast`, `ai.text.chat.reasoning`, `ai.text.chat.auto`, `ai.text.summarize`, or `ai.text.rewrite` to forward the backend HTTP SSE frames unchanged. This is not WebSocket transport. Do not combine it with `--output` or `--code`.
+
+### Summarize & rewrite
+
+```bash
+npx xapi-to call ai.text.summarize --input '{"text":"<long text here>"}'
+
+npx xapi-to call ai.text.rewrite --input '{"text":"<text>","mode":"formalize"}'
+```
+
+`mode` values: `improve`, `simplify`, `formalize`, `casual`, `creative`, `professional`, `academic`.
+
+- Summarization controls that affect execution: `model`, `max_length` (target words), `style` (`concise`, `detailed`, `bullet_points`, or `executive`), `language` (`auto` keeps the input language), `focus`, and `temperature`.
+- Rewrite controls that affect execution: `model`, `mode`, `tone`, `target_audience`, `length_preference` (`shorter`, `similar`, or `longer`), and `temperature`.
+- Always run `get` before using newly advertised fields. Do not assume every declared compatibility field changes current backend behavior.
+
+### Embeddings
+
+```bash
+npx xapi-to call ai.embedding.generate --input '{"input":"hello world"}'
+```
+
+Returns a vector for one input string; use it for semantic search or similarity. Optional fields are `model`, `encoding_format` (`float` or `base64`), model-dependent `dimensions`, `user`, and provider-routing options in the `provider` object. The current declared schema accepts a string, so do not send a batch array until `get` reports array support.
+
+## Image generation
+
+Image generation is asynchronous and returns a task to wait for.
+
+```bash
+npx xapi-to call ai.image.generate \
+  --input '{"prompt":"A serene mountain landscape at sunset, digital art","model":"gpt-image-2"}'
+```
+
+- `prompt` (required) — the text description.
+- `provider` (optional) — upstream, hard-pinned (no fallback). Defaults to `gpt88`.
+- `model` (optional) — **must be compatible with the provider**:
+  - `gpt88` (default provider) serves `gpt-image-2` (default model).
+  - `skyimage` serves `gpt-image-1` and `dall-e-*` (`dall-e-3`, `dall-e-2`).
+  - ⚠️ Picking e.g. `dall-e-3` without also setting `provider: "skyimage"` will fail — the default `gpt88` provider only serves `gpt-image-2`.
+- `n` (optional) — number of images (default `1`); `size` (optional, e.g. `1024x1024`).
+- Other optional controls include `aspect_ratio`, `quality`, `background`, `moderation`, `style`, `image` (reference-image array), and `user`. Support depends on the selected model.
+- Returns an async task handle, not the image itself. Wait for it with `task wait` as described below.
+
+## Video generation
+
+Video generation does **not** return the video immediately. It returns a task handle you must poll.
+
+### Step 1: Submit the generation request
+
+```bash
+npx xapi-to call ai.video.generate \
+  --input '{"prompt":"A cat playing piano in a jazz bar, cinematic"}'
+```
+
+Optional inputs:
+- `model` — any OpenRouter video model accepted upstream, e.g. `bytedance/seedance-2.0-fast`, `bytedance/seedance-2.0`, `google/veo-3.1`, or `openai/sora-2-pro`. Defaults to `bytedance/seedance-2.0-fast`.
+- `provider` — only `openrouter` is currently supported; it is the default and is hard-pinned with no fallback.
+- `image` — a single reference image URL (first frame).
+- `images` — multiple reference image URLs.
+- `input_reference` — OpenAI Videos-style reference material.
+- `size` — frame size or aspect ratio, e.g. `1280x720`, `16:9`, or `9:16`.
+- `duration` / `seconds` — requested duration; accepted values depend on the model.
+- `seed` — random seed.
+- `metadata` — provider-specific options such as roles, resolution, audio, watermark, or ratio.
+
+The response is a **202-style async task**:
+
+```json
+{ "task_id": "…", "status": "pending", "poll_url": "…", "expires_at": "…" }
+```
+
+### Step 2: Wait until terminal
+
+```bash
+npx xapi-to task wait <task_id-from-step-1> --interval 2s --timeout 10m
+```
+
+Status values: `pending` | `processing` | `succeeded` | `failed` | `expired`.
+
+- `task wait` polls every few seconds until the status is **terminal** (`succeeded` / `failed` / `expired`).
+- On `succeeded`, the result payload (video URL/data) is included.
+- On `failed` / `expired`, the error payload is printed and the command exits nonzero.
+
+Use `npx xapi-to task poll <task_id>` for one status read when another scheduler controls the loop. Add `--max-attempts <n>` when an attempt bound is more useful than a time bound. Duration values accept `ms`, `s`, `m`, and `h`.
+
+**Agent-controlled polling loop (pseudocode):**
+
+```
+submit → get task_id
+loop:
+  result = run("npx xapi-to task poll " + task_id)
+  if result.status in {succeeded, failed, expired}: break
+  wait a few seconds
+handle result
+```
+
+Do not busy-loop with zero delay — space polls a few seconds apart. If the task `expires`, resubmit.
+
+## Speech generation
+
+Text-to-speech calls are synchronous.
+
+```bash
+npx xapi-to call ai.audio.generate \
+  --input '{"text":"Hello world, this is a test.","model":"hexgrad/kokoro-82m","voice":"af_bella","format":"mp3"}'
+```
+
+Required inputs:
+
+- `text` — text to convert into speech.
+- `model` — OpenRouter TTS model ID.
+- `voice` — a voice supported by the selected model.
+
+Optional inputs:
+
+- `format` — `mp3` (default) or `pcm`.
+- `speed` — playback-speed multiplier when supported by the model.
+- `provider` — OpenRouter provider-routing options as an object, not a provider name string.
+
+The response is a lossless binary envelope:
+
+```json
+{
+  "success": true,
+  "data": {
+    "type": "binary",
+    "encoding": "base64",
+    "content_type": "audio/mpeg",
+    "content_length": 12345,
+    "content": "<base64-audio>"
+  }
+}
+```
+
+Decode `data.content` from base64 to save or play the audio. `data.content_disposition` may also be present when supplied upstream.
+
+## Speech transcription
+
+Speech-to-text calls are synchronous.
+
+```bash
+npx xapi-to call ai.audio.transcribe \
+  --input '{"audio":{"data":"<base64-audio>","format":"wav"},"model":"openai/whisper-large-v3","language":"en"}'
+```
+
+- `audio` (required) — object containing raw base64 `data` without a data URI prefix and a file `format` such as `wav`, `mp3`, `flac`, `m4a`, `ogg`, `webm`, or `aac`.
+- `model` (required) — OpenRouter speech-recognition model ID.
+- `language` (optional) — ISO-639-1 code; omit it for automatic detection.
+- `temperature` (optional) — transcription sampling temperature.
+- `provider` (optional) — OpenRouter provider-routing options as an object.
+
+Returns the transcribed `text` and optional OpenRouter `usage` information.
+
+## Error handling
+
+- **Missing `prompt`** → `prompt` is required for both `ai.image.generate` and `ai.video.generate`.
+- **Unknown image model** → use a model compatible with the chosen image provider; omit both fields to use `gpt88` + `gpt-image-2`.
+- **Unknown video provider/model** → provider must be `openrouter`; omit `model` to use `bytedance/seedance-2.0-fast`.
+- **Image/video result never ready** → keep polling until a terminal status; on `expired`, resubmit the request.
+- **Missing speech fields** → TTS requires `text`, `model`, and `voice`; transcription requires `audio.data`, `audio.format`, and `model`.
+- **Invalid audio input** → pass raw base64 bytes without a `data:audio/...;base64,` prefix and set the matching file format.
+- **Insufficient balance** → run `npx xapi-to topup --method stripe --amount 10` (AI media and speech calls consume credits).

package/skills/xapi/guides/ai_gateway.md

@@ -0,0 +1,263 @@
+# AI Gateway Guide
+
+Use xAPI's public AI Gateway when a tool or application expects an Anthropic- or OpenAI-compatible HTTP API. For one-off agent calls from the terminal, prefer the `ai.*` CLI capabilities documented in `guides/ai.md`. For full-duplex OpenAI Realtime, streaming ASR/TTS, simultaneous interpretation, or other WebSocket sessions, read `guides/ws_gateway.md`.
+
+## Contents
+
+- [Choose CLI capabilities or the Gateway](#choose-cli-capabilities-or-the-gateway)
+- [Base URLs and authentication](#base-urls-and-authentication)
+- [Claude Code and Anthropic setup](#claude-code-and-anthropic-setup)
+- [OpenAI-compatible setup](#openai-compatible-setup)
+- [Select a model in the URL](#select-a-model-in-the-url)
+- [Supported endpoints](#supported-endpoints)
+- [Routing strategies](#routing-strategies)
+- [Provider affinity](#provider-affinity)
+- [Streaming and protocol translation](#streaming-and-protocol-translation)
+- [Routing and billing headers](#routing-and-billing-headers)
+- [Image, video, and rerank endpoints](#image-video-and-rerank-endpoints)
+- [Known limitations](#known-limitations)
+- [Error handling and security](#error-handling-and-security)
+
+## Choose CLI capabilities or the Gateway
+
+Use CLI capabilities when an agent needs to make a small number of direct calls and consume JSON:
+
+```bash
+npx xapi-to call ai.text.chat.auto \
+  --input '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+Use the AI Gateway when:
+
+- configuring Claude Code, an Anthropic SDK, an OpenAI SDK, or another compatible client;
+- an existing application already calls `/v1/messages`, `/v1/chat/completions`, `/v1/responses`, or `/v1/embeddings`;
+- the caller needs streaming SSE responses;
+- the caller should use model normalization, protocol translation, provider health checks, and fallback without selecting an upstream manually.
+
+The Gateway is a separate HTTP interface. Do not wrap Gateway request bodies in the xAPI action format (`action_id` / `input`). Send the native Anthropic or OpenAI request body directly.
+
+## Base URLs and authentication
+
+Public host: `https://ai.xapi.to`
+
+Strategy-prefixed base URLs:
+
+| Protocol | Base URL |
+|---|---|
+| Anthropic | `https://ai.xapi.to/<strategy>` |
+| OpenAI | `https://ai.xapi.to/<strategy>/v1` |
+
+Omit `<strategy>` to use the default routes directly under `/v1`.
+
+The Gateway accepts the xAPI key through any of these headers:
+
+```text
+XAPI-Key: <XAPI_KEY>
+Authorization: Bearer <XAPI_KEY>
+x-api-key: <XAPI_KEY>
+```
+
+Use the header expected by the client library: Anthropic clients normally use `x-api-key`; OpenAI clients normally use `Authorization: Bearer`.
+
+If no key is configured, register or set one with the CLI before proceeding:
+
+```bash
+npx xapi-to register
+npx xapi-to config set apiKey=<your-key>
+```
+
+## Claude Code and Anthropic setup
+
+Configure Claude Code or another Anthropic-compatible client with an xAPI key and a strategy base URL:
+
+```bash
+export ANTHROPIC_BASE_URL="https://ai.xapi.to/quality"
+export ANTHROPIC_API_KEY="<XAPI_KEY>"
+```
+
+Direct Anthropic Messages request:
+
+```bash
+curl https://ai.xapi.to/default/v1/messages \
+  -H 'content-type: application/json' \
+  -H 'anthropic-version: 2023-06-01' \
+  -H 'x-api-key: <XAPI_KEY>' \
+  -d '{
+    "model":"deepseek-v4-pro",
+    "max_tokens":1024,
+    "messages":[{"role":"user","content":"Explain xAPI in one sentence."}]
+  }'
+```
+
+Anthropic fields such as top-level `system`, content blocks, `thinking`, `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences`, and `metadata` are accepted and routed with the request. Support at the selected upstream still depends on the model.
+
+## OpenAI-compatible setup
+
+For clients that honor the standard OpenAI environment variables:
+
+```bash
+export OPENAI_BASE_URL="https://ai.xapi.to/default/v1"
+export OPENAI_API_KEY="<XAPI_KEY>"
+```
+
+Direct Chat Completions request:
+
+```bash
+curl https://ai.xapi.to/cost/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <XAPI_KEY>' \
+  -d '{
+    "model":"deepseek-v4-flash",
+    "messages":[{"role":"user","content":"Hello"}]
+  }'
+```
+
+List currently routable canonical models:
+
+```bash
+curl https://ai.xapi.to/v1/models
+```
+
+Use the returned model ID in subsequent requests. A model can only be routed when an active provider exposes a compatible endpoint and input modality.
+
+## Select a model in the URL
+
+For strategy-aware endpoints, the segment before `/v1` can be either a routing strategy or a model ID. When it is not one of the reserved strategies `default`, `cost`, `speed`, or `quality`, the Gateway treats it as the model, overwrites any `model` value in the request body, and uses the default strategy.
+
+```bash
+curl https://ai.xapi.to/gpt-4o/v1/chat/completions \
+  -H 'authorization: Bearer <XAPI_KEY>' \
+  -H 'content-type: application/json' \
+  -d '{"model":"ignored","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+This also works for Anthropic Messages, OpenAI Responses, and embeddings. Use it only for model IDs that fit in one URL path segment. For IDs containing `/`, keep the model in the JSON body and use a strategy-prefixed or unprefixed `/v1` route.
+
+## Supported endpoints
+
+| Interface | Method and path | Strategy prefix |
+|---|---|---|
+| Anthropic Messages | `POST /v1/messages` | Optional |
+| OpenAI Chat Completions | `POST /v1/chat/completions` | Optional |
+| OpenAI Responses | `POST /v1/responses` | Optional |
+| Embeddings | `POST /v1/embeddings` | Optional |
+| Model discovery | `GET /v1/models` | Optional |
+| Image generation | `POST /v1/images/generations` | No |
+| Video generation | `POST /v1/videos` | No |
+| Rerank | `POST /v1/rerank` | No |
+
+For strategy-aware endpoints, insert a strategy before `/v1`, for example `/cost/v1/responses`. Without a prefix, the Gateway uses `default`.
+
+## Routing strategies
+
+Accepted strategies:
+
+| Strategy | Current behavior |
+|---|---|
+| `default` | Prefer protocol-compatible zero-translation candidates, then configured provider priority and weighted distribution. |
+| `cost` | Prefer the lowest effective cost, adjusted by recent provider success rate; near-equal candidates fall back to default ordering. |
+| `speed` | Accepted, but currently uses the same candidate ordering as `default`. |
+| `quality` | Accepted, but currently uses the same candidate ordering as `default`. |
+
+All strategies apply the active-provider gate, model and modality compatibility checks, provider health checks, circuit breaking, and eligible-provider fallback. Do not promise distinct latency or quality optimization for `speed` or `quality` until their dedicated rankers are implemented.
+
+## Provider affinity
+
+After a successful request, the Gateway remembers the serving provider for one hour and promotes it for later requests with the same strategy, model, and affinity identity. The identity is selected in this order:
+
+- Anthropic Messages: `metadata.user_id`, then the xAPI key;
+- OpenAI Chat Completions: `prompt_cache_key`, then `user`, then the xAPI key;
+- other interfaces, including Responses and embeddings: the xAPI key.
+
+Affinity is isolated between routing strategies and only changes candidate order. It does not bypass health, circuit-breaker, model, modality, or active-provider checks, so clients must not rely on a provider remaining fixed for the full hour.
+
+## Streaming and protocol translation
+
+Set `"stream": true` in Chat Completions, Responses, or Messages requests to receive an SSE stream in the requested protocol.
+
+The Gateway can route across providers with different upstream protocols. When translation is available, it converts the request and response while preserving the inbound Anthropic or OpenAI interface. Model-specific features such as tool calling, thinking, images, or structured output still depend on the selected model and available adapter.
+
+Client-side validation errors normally stop immediately. Provider reliability failures such as authentication/configuration failures, rate limits, timeouts, and server errors may trigger fallback to another eligible provider.
+
+## Routing and billing headers
+
+Successful routed responses can include:
+
+| Header | Meaning |
+|---|---|
+| `X-Routing-Provider` | Provider that served the final response. |
+| `X-Routing-Attempts` | Number of candidates attempted. |
+| `X-Routing-Fallback` | `true` when a later candidate succeeded. |
+| `X-Routing-Translated` | Present when protocol translation was used. |
+| `X-XAPI-Cost` | Aggregated USD cost for the request attempts. |
+| `X-XAPI-Cost-Unit` | Cost currency, currently `USD`. |
+| `X-XAPI-Billing` | Billing status. |
+| `X-XAPI-Billing-Type` | Billing mode, such as `PER_TOKEN` or `ASYNC`. |
+
+Do not use provider names as a stable application contract. Provider selection can change with availability, configuration, pricing, and routing policy.
+
+## Image, video, and rerank endpoints
+
+These endpoints are direct Gateway interfaces and do not use a strategy prefix.
+
+### Images
+
+```bash
+curl https://ai.xapi.to/v1/images/generations \
+  -H 'authorization: Bearer <XAPI_KEY>' \
+  -H 'content-type: application/json' \
+  -H 'X-Provider: gpt88' \
+  -d '{"model":"gpt-image-2","prompt":"A moonlit mountain lake"}'
+```
+
+Image provider selection is hard-pinned with `X-Provider` and has no fallback. The default is `gpt88`; `skyimage` is also available, but the model must be compatible with the selected provider.
+
+### Videos
+
+```bash
+curl https://ai.xapi.to/v1/videos \
+  -H 'authorization: Bearer <XAPI_KEY>' \
+  -H 'content-type: application/json' \
+  -H 'X-Provider: openrouter' \
+  -d '{"model":"bytedance/seedance-2.0-fast","prompt":"A cat playing piano in a jazz bar"}'
+```
+
+The current video provider is `openrouter`, which is also the default and is hard-pinned with no fallback.
+
+Image and video generation are asynchronous. A successful submit returns a `task_id`, `status`, and `poll_url`. Follow the authenticated `poll_url`, or poll the same task through the CLI:
+
+```bash
+npx xapi-to task wait <task_id> --interval 2s --timeout 10m
+```
+
+### Rerank
+
+```bash
+curl https://ai.xapi.to/v1/rerank \
+  -H 'authorization: Bearer <XAPI_KEY>' \
+  -H 'content-type: application/json' \
+  -d '{"model":"<rerank-model>","query":"What is xAPI?","documents":["...","..."]}'
+```
+
+Rerank currently routes directly through OpenRouter rather than the strategy-based candidate pool.
+
+## Known limitations
+
+- `POST /v1/messages/count_tokens` is not implemented and currently returns `404`.
+- `speed` and `quality` are accepted strategy names but currently use default ordering.
+- Image and video endpoints submit asynchronous tasks; they do not return final media in the initial response.
+- Image/video provider selection is hard-pinned and does not use chat-style fallback.
+- Text-to-speech and speech-to-text are not exposed as HTTP AI Gateway routes. Use `ai.audio.generate` and `ai.audio.transcribe` through the xAPI CLI for synchronous calls, or `guides/ws_gateway.md` for provider-native streaming sessions.
+- Model and feature availability is dynamic. Use `GET /v1/models` and handle unsupported-model or modality errors.
+- Path-selected models must fit in one URL path segment; otherwise send the model in the body.
+
+## Error handling and security
+
+- **401 / authentication error** → verify that the xAPI key is sent in one supported authentication header.
+- **Model not found** → use `GET /v1/models` and select a currently routable model ID.
+- **No candidates / 503** → no active provider currently serves that model and protocol combination; retry later or choose another model.
+- **Unsupported modality** → choose a model that accepts the request's text, image, or other input type.
+- **All providers failed** → retry with backoff; changing strategy may reorder candidates but cannot make an unavailable model routable.
+- **Async task failed or expired** → inspect the poll result and resubmit when appropriate.
+
+Never send the xAPI key to a domain outside `*.xapi.to`. Do not print, persist, or share the key, payment URLs, or authenticated polling URLs.

package/skills/xapi/guides/crypto.md

@@ -0,0 +1,197 @@
+# Crypto Guide
+
+Complete guide for crypto/on-chain data via xAPI — token price & market data, holders, security, OHLCV, wallet analytics, DEX pairs, CEX spot prices, and news.
+
+All crypto endpoints are **built-in capabilities** (`--source capability`). Pass parameters with `--input` as a JSON object.
+
+## Contents
+
+- [Addressing models](#the-two-addressing-models-read-this-first)
+- [Chains](#chains)
+- [Token data](#token-data-by-contract-address)
+- [Wallet analytics](#wallet-analytics-by-wallet-address)
+- [Transactions and DEX pairs](#transaction-and-dex-pair)
+- [CEX spot data](#cex-spot-data-by-symbol)
+- [News](#news)
+- [Symbol-to-contract workflow](#common-workflow-from-symbol-to-on-chain-data)
+- [Pagination](#cursor-pagination)
+- [Error handling](#error-handling)
+
+## The two addressing models (read this first)
+
+Crypto endpoints split into two families by how you identify the asset:
+
+| Family | Identify by | Endpoints | Use when |
+|--------|-------------|-----------|----------|
+| **On-chain** | **contract / wallet / pool address** + `chain` | `crypto.token.*`, `crypto.wallet.*`, `crypto.tx.*`, `crypto.dex.*` | You have (or can resolve) a contract address on a specific chain |
+| **CEX** | **symbol** (BTC, ETH, …) | `crypto.cex.*` | You only have a ticker symbol and want a centralized-exchange spot price |
+
+**Common mistake:** do NOT pass a symbol like `"BTC"` as the `token` of `crypto.token.price` — that field is a **contract address**. For "how much is BTC worth?" use `crypto.cex.price` with `{"symbol":"BTC"}`. If the user gives you a name/symbol and you need on-chain data, first resolve it to an address with `crypto.token.search` (see workflow below).
+
+## Chains
+
+`chain` accepts these canonical values (default `bsc`):
+
+`eth` · `bsc` · `solana` · `base` · `arbitrum` · `polygon` · `optimism` · `avalanche`
+
+Common aliases are normalized automatically: `ethereum`/`ether` → `eth`, `bnb`/`bnb-chain`/`binance`/`binance-smart-chain` → `bsc`, `sol` → `solana`.
+
+All on-chain endpoints accept an optional `provider` to pin a specific upstream and **disable automatic fallback**. By default the gateway aggregates several upstreams (e.g. moralis / birdeye / dexscreener, depending on chain and endpoint) and falls back on failure. The valid `provider` values differ per endpoint — run `npx xapi-to get <id>` to see the exact enum. Only pin a provider for debugging or when you need a specific source.
+
+## Token data (by contract address)
+
+### Price + 24h market data
+
+```bash
+npx xapi-to call crypto.token.price \
+  --input '{"token":"0x55d398326f99059ff775485246999027b3197955","chain":"bsc"}'
+```
+
+Returns `data.priceUsd`, `symbol`, `name`, plus 24h change / volume / liquidity / market cap (fields depend on the resolving provider).
+
+### Full overview (metadata + price + market in one call) — preferred
+
+```bash
+npx xapi-to call crypto.token.overview \
+  --input '{"token":"0x55d398326f99059ff775485246999027b3197955","chain":"bsc"}'
+```
+
+Prefer `crypto.token.overview` over the deprecated `crypto.token.metadata` — it returns name/symbol/decimals/logo **and** price/market data in a single request.
+
+> `crypto.token.metadata` still works but is **deprecated**; migrate to `crypto.token.overview`.
+
+### OHLCV candles
+
+```bash
+npx xapi-to call crypto.token.ohlcv \
+  --input '{"token":"0x...","chain":"bsc","interval":"1h","limit":100}'
+```
+
+`interval` defaults to `1d`; valid values are `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`. `limit` is the number of candles. (Same interval set applies to `crypto.cex.ohlcv`.)
+
+### Holders / top traders / security
+
+```bash
+# Top holders (optional limit)
+npx xapi-to call crypto.token.holders --input '{"token":"0x...","chain":"bsc","limit":50}'
+
+# Top traders of the token
+npx xapi-to call crypto.token.top_traders --input '{"token":"0x...","chain":"bsc"}'
+
+# Security check (honeypot, buy/sell tax, ownership, etc.)
+npx xapi-to call crypto.token.security --input '{"token":"0x...","chain":"bsc"}'
+```
+
+Run `crypto.token.security` before treating any token as tradeable — it flags honeypots and abnormal taxes.
+
+`crypto.token.holders` is paginated. When the response contains `data.next_cursor`, pass it back unchanged:
+
+```bash
+npx xapi-to call crypto.token.holders \
+  --input '{"token":"0x...","chain":"bsc","limit":50,"cursor":"<next_cursor>"}'
+```
+
+Moralis supports holder pagination on EVM chains and Birdeye supports it on Solana. The cursor pins the provider that issued it.
+
+### Trending tokens (chain-level, no address needed)
+
+```bash
+npx xapi-to call crypto.token.trending --input '{"chain":"bsc","limit":20}'
+```
+
+### Search tokens by name / symbol / address
+
+```bash
+npx xapi-to call crypto.token.search --input '{"query":"PEPE","limit":10}'
+```
+
+`query` can be a name, symbol, pair, or address. Results include contract addresses you can feed into the other `crypto.token.*` endpoints.
+
+## Wallet analytics (by wallet address)
+
+```bash
+# Current token balances
+npx xapi-to call crypto.wallet.balance --input '{"address":"0x...","chain":"bsc"}'
+
+# Realized/unrealized profit & loss
+npx xapi-to call crypto.wallet.pnl --input '{"address":"0x...","chain":"bsc"}'
+
+# Transaction history (optional limit)
+npx xapi-to call crypto.wallet.history --input '{"address":"0x...","chain":"bsc","limit":50}'
+```
+
+Typical wallet-analysis flow: `wallet.balance` (what they hold) → `wallet.pnl` (how they're doing) → `wallet.history` (recent activity).
+
+`crypto.wallet.balance` and `crypto.wallet.history` are paginated when served by Moralis. Read `data.next_cursor` and pass it back as `cursor` for the next page. `crypto.wallet.pnl` is not paginated.
+
+## Transaction and DEX pair
+
+```bash
+# Decode a single transaction
+npx xapi-to call crypto.tx.detail --input '{"txHash":"0x...","chain":"bsc"}'
+
+# DEX pair / pool stats by pair contract address
+npx xapi-to call crypto.dex.pair --input '{"pair":"0x...","chain":"bsc"}'
+```
+
+Note `crypto.dex.pair` takes the **pool/pair contract address** (not a token address).
+
+## CEX spot data by symbol
+
+Use these when you only have a ticker and want a centralized-exchange price.
+
+```bash
+# Spot price + 24h change/volume/high/low
+npx xapi-to call crypto.cex.price --input '{"symbol":"BTC"}'
+
+# CEX OHLCV candles
+npx xapi-to call crypto.cex.ohlcv --input '{"symbol":"BTC","interval":"1d","limit":100}'
+```
+
+`symbol` accepts a bare ticker (`BTC`, `ETH`) or a full pair (`BTCUSDT`, `BTC-USDT`). For a bare symbol you may pass `quote` (default `USDT`).
+
+## News
+
+```bash
+# Latest crypto news, optionally scoped to a coin
+npx xapi-to call crypto.news --input '{"symbol":"BTC","limit":20}'
+```
+
+All parameters are optional; omit `symbol` for general market news.
+
+## Common workflow from symbol to on-chain data
+
+The user gives you a token name or symbol but you need on-chain metrics (holders, security, liquidity):
+
+```bash
+# 1. Resolve the symbol/name to a contract address + chain
+npx xapi-to call crypto.token.search --input '{"query":"PEPE"}'
+#    → pick the right result, read its contract address and chain
+
+# 2. Query on-chain endpoints with that address
+npx xapi-to call crypto.token.overview --input '{"token":"0x6982...","chain":"eth"}'
+npx xapi-to call crypto.token.security --input '{"token":"0x6982...","chain":"eth"}'
+```
+
+For a plain "what's the price of BTC" question with no on-chain requirement, skip all of this and use `crypto.cex.price`.
+
+## Cursor Pagination
+
+Three crypto capabilities expose cursor pagination:
+
+| Capability | Next cursor field | Next request input | Paging providers |
+|---|---|---|---|
+| `crypto.token.holders` | `data.next_cursor` | `cursor` | Moralis (EVM), Birdeye (Solana) |
+| `crypto.wallet.balance` | `data.next_cursor` | `cursor` | Moralis |
+| `crypto.wallet.history` | `data.next_cursor` | `cursor` | Moralis |
+
+The cursor is an opaque `<provider>:<native>` value. Do not parse, edit, or combine it with a different explicit `provider`; pass it back unchanged. A cursor pins requests to its issuing provider, so pagination deliberately does not fall back to a different upstream. Stop when `next_cursor` is null or absent.
+
+`crypto.token.trending` and `crypto.token.top_traders` are top-N list capabilities, not cursor-paginated feeds.
+
+## Error handling
+
+- **Unsupported chain** → use one of the canonical chain values listed above (or a known alias).
+- **`token`/`address` looks like a symbol** → it must be a contract/wallet address; resolve via `crypto.token.search`, or switch to `crypto.cex.*` for symbol-based pricing.
+- **Empty / partial fields** → different upstream providers return different field sets; pin a `provider` or try `crypto.token.overview` for the most complete payload.
+- **Invalid or mismatched cursor** → pass `next_cursor` back unchanged and do not force a different provider; start again without `cursor` if the original cursor is unavailable.