---
name: xona-x402-api
description: Access Xona's AI-powered x402 payment-gated API endpoints for image generation, video creation, audio synthesis, token analytics, Tokens API (tokens.xyz) data, and AI persona extraction - paid per-request in USDC on Solana, Base, SKALE (on Base), or X Layer.
---

# Xona x402 API – Endpoint Reference

Base URL: `https://api.xona-agent.com`

All endpoints below are payment-gated using the [x402 protocol](https://x402.org) (HTTP 402 Payment Required). Payment is in **USDC** on **Solana mainnet**, **Base mainnet (EVM)**, **SKALE on Base**, or **X Layer (OKX L2)**.

---

## How x402 Works

```
Client                          Server                         Blockchain
  |                               |                               |
  |── 1. POST /image/designer ──▶|                               |
  |                               |                               |
  |◀── 2. 402 Payment Required ──|                               |
  |   (PAYMENT-REQUIRED header    |                               |
  |    + JSON: accepts, resource) |                               |
  |                               |                               |
  |── 3. Sign payment with wallet |                               |
  |                               |                               |
  |── 4. Retry with ─────────────▶|                               |
  |   PAYMENT-SIGNATURE header    |── 5. Verify & settle ────────▶|
  |                               |                               |
  |◀── 6. 200 OK + result ───────|◀── settlement confirmed ──────|
```

1. Send a normal HTTP request to any x402 endpoint.
2. Server responds `402` with a `PAYMENT-REQUIRED` header and a JSON body containing `accepts` (price, network, asset), `resource`, and `x402Version`.
3. Your client signs a USDC payment using the wallet private key.
4. Retry the same request with the `PAYMENT-SIGNATURE` header attached.
5. Server verifies the signature on-chain and settles the payment.
6. Server returns the result.

### Discovery

- `GET /x402-resources` — returns the full JSON list of all available x402 resources with schemas and pricing (no auth required).
- `GET /.well-known/x402` — x402 discovery document with version, resources, and ownership proofs.

---

## Client Code Examples

### Solana (TypeScript / Browser)

Dependencies: `@x402/core`, `@x402/svm`, `@solana/signers`, `bs58`

```typescript
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { toClientSvmSigner } from "@x402/svm";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { createKeyPairSignerFromBytes } from "@solana/signers";
import bs58 from "bs58";

const BASE_URL = "https://api.xona-agent.com";
const RPC_URL = "https://api.mainnet-beta.solana.com";

async function callX402(endpoint: string, body: object, solanaPrivateKey: string) {
  const secretKeyBytes = bs58.decode(solanaPrivateKey);
  const keypairSigner = await createKeyPairSignerFromBytes(secretKeyBytes);
  const svmSigner = toClientSvmSigner(keypairSigner);

  const scheme = new ExactSvmScheme(svmSigner, { rpcUrl: RPC_URL });
  const coreClient = new x402Client().register("solana:*", scheme);
  const httpClient = new x402HTTPClient(coreClient);

  const url = `${BASE_URL}${endpoint}`;

  // Step 1: Initial request
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (response.status !== 402) return response;

  // Step 2: Handle 402 — sign and retry
  const responseBody = await response.json();
  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => response.headers.get(name),
    responseBody
  );
  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);

  return fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...paymentHeaders },
    body: JSON.stringify(body),
  });
}

// Usage
const res = await callX402("/image/designer", { prompt: "A sunset over mountains" }, PRIVATE_KEY);
const data = await res.json();
console.log(data.image_url);
```

### Base / EVM (TypeScript / Browser)

Dependencies: `@x402/core`, `@x402/evm`, `viem`

```typescript
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const BASE_URL = "https://api.xona-agent.com";

async function callX402Evm(endpoint: string, body: object, evmPrivateKey: `0x${string}`) {
  const account = privateKeyToAccount(evmPrivateKey);
  const evmScheme = new ExactEvmScheme(account);
  const coreClient = new x402Client().register("eip155:8453", evmScheme);
  const httpClient = new x402HTTPClient(coreClient);

  // Use /base-main/ prefix for EVM endpoints
  const url = `${BASE_URL}/base-main${endpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (response.status !== 402) return response;

  const responseBody = await response.json();
  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => response.headers.get(name),
    responseBody
  );
  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);

  return fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...paymentHeaders },
    body: JSON.stringify(body),
  });
}

// Usage — note: no /base-main/ prefix needed, the function adds it
const res = await callX402Evm("/image/designer", { prompt: "A sunset over mountains" }, "0x...");
const data = await res.json();
console.log(data.image_url);
```

### SKALE on Base (TypeScript / Browser)

Dependencies: `@x402/core`, `@x402/evm`, `viem`

```typescript
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const BASE_URL = "https://api.xona-agent.com";

async function callX402Skale(endpoint: string, body: object, evmPrivateKey: `0x${string}`) {
  const account = privateKeyToAccount(evmPrivateKey);
  const evmScheme = new ExactEvmScheme(account);
  const coreClient = new x402Client().register("eip155:1187947933", evmScheme);
  const httpClient = new x402HTTPClient(coreClient);

  // Use /base/ prefix for SKALE endpoints
  const url = `${BASE_URL}/base${endpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (response.status !== 402) return response;

  const responseBody = await response.json();
  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => response.headers.get(name),
    responseBody
  );
  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);

  return fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...paymentHeaders },
    body: JSON.stringify(body),
  });
}

// Usage — note: no /base/ prefix needed, the function adds it
const res = await callX402Skale("/image/designer", { prompt: "A sunset over mountains" }, "0x...");
const data = await res.json();
console.log(data.image_url);
```

### X Layer (TypeScript / Browser)

Dependencies: `@x402/core`, `@x402/evm`, `viem`

```typescript
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const BASE_URL = "https://api.xona-agent.com";

async function callX402XLayer(endpoint: string, body: object, evmPrivateKey: `0x${string}`) {
  const account = privateKeyToAccount(evmPrivateKey);
  const evmScheme = new ExactEvmScheme(account);
  const coreClient = new x402Client().register("eip155:196", evmScheme);
  const httpClient = new x402HTTPClient(coreClient);

  // Use /xlayer/ prefix for X Layer endpoints
  const url = `${BASE_URL}/xlayer${endpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (response.status !== 402) return response;

  const responseBody = await response.json();
  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => response.headers.get(name),
    responseBody
  );
  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);

  return fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...paymentHeaders },
    body: JSON.stringify(body),
  });
}

// Usage — note: no /xlayer/ prefix needed, the function adds it
const res = await callX402XLayer("/image/designer", { prompt: "A sunset over mountains" }, "0x...");
const data = await res.json();
console.log(data.image_url);
```

### Node.js (Server-to-Server)

Dependencies: `@x402/fetch`

```javascript
const { withX402 } = require("@x402/fetch");

const x402Fetch = withX402(fetch, {
  privateKey: process.env.SOLANA_PRIVATE_KEY,
  network: "solana-mainnet",
});

const res = await x402Fetch("https://api.xona-agent.com/image/designer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "A sunset over mountains" }),
});
```

### cURL (Manual Two-Step)

```bash
# Step 1: Get payment requirements
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.xona-agent.com/image/designer \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A sunset"}'
# Returns 402 with PAYMENT-REQUIRED header

# Step 2: Sign off-chain, then retry with the signed payload in PAYMENT-SIGNATURE header.
# In practice, use the SDK — manual signing is complex.
```

---

## Endpoints

All Solana endpoints live at the root path. For **Base mainnet**, prefix with `/base-main`; for **SKALE on Base**, prefix with `/base`; for **X Layer**, prefix with `/xlayer`. Same pricing and schemas across all networks.

### Image Endpoints

#### POST /image/creative-director

AI-powered creative research and prompt refinement using X and Google. Analyzes trends and transforms your idea into an optimized generation plan.

| | |
|---|---|
| **Price** | $0.03 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `idea` | string | Yes | Your prompt/idea for image generation |
| `reference_images` | string[] | No | Array of existing image URLs to use as references |

**Response**

| Field | Type | Description |
|---|---|---|
| `intent` | object | Analyzed user intent from the prompt |
| `research` | array | Research results from X and Google |
| `direction` | array | Generation plan with refined prompt |

---

#### POST /image/designer

AI image generation with intelligent style blending. Takes your prompt and style keywords, refines them together, and generates a high-quality image.

| | |
|---|---|
| **Price** | $0.08 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `style` | string[] | No | Style keywords to blend into the prompt |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Refined prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

#### POST /image/nano-banana-pro

AI image generation using nano-banana-pro model. High-quality image generation without style blending.

| | |
|---|---|
| **Price** | $0.20 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

#### POST /image/nano-banana

AI image generation using nano-banana model. High-quality image generation without style blending.

| | |
|---|---|
| **Price** | $0.10 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

#### POST /image/nano-banana-2

AI image generation using nano-banana-2 model with resolution-based dynamic pricing.

| | |
|---|---|
| **Price** | $0.06 (1K) / $0.10 (2K) / $0.15 (4K) USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `resolution` | string | No | Output resolution: `1k` (1024px, $0.06), `2k` (2048px, $0.10), `4k` (4096px, $0.15). Default: `1k` |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, resolution, parameters) |

---

#### POST /image/grok-imagine

AI image generation using xAI's Grok Imagine API.

| | |
|---|---|
| **Price** | $0.04 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `referenceImage` | string | No | Single reference image URL (Grok supports one image only) |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

### Image Model Endpoints

#### POST /image-model/qwen-image

AI image generation using qwen/qwen-image model.

| | |
|---|---|
| **Price** | $0.05 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs (uses first image) |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model, aspectRatio, reference_images) |

---

#### POST /image-model/seedream-4.5

AI image generation using ByteDance Seedream-4.5 model.

| | |
|---|---|
| **Price** | $0.08 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model, aspectRatio, reference_images) |

---

#### POST /image/flux-2-pro

High-quality image generation and editing with support for eight reference images using FLUX.2 Pro model.

| | |
|---|---|
| **Price** | $0.05 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

#### POST /image/flux-2-max

The highest fidelity image model from Black Forest Labs using FLUX.2 Max.

| | |
|---|---|
| **Price** | $0.08 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

#### POST /image/flux-2-flex

Max-quality image generation and editing with support for ten reference images using FLUX.2 Flex.

| | |
|---|---|
| **Price** | $0.06 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Detailed prompt description for image generation |
| `aspect_ratio` | string | No | Aspect ratio (default: `1:1`) |
| `referenceImage` | string[] | No | Array of reference image URLs for style guidance |

**Response**

| Field | Type | Description |
|---|---|---|
| `image_url` | string | Generated image URL (CDN) |
| `image_description` | string | Prompt used for generation |
| `metadata` | object | Generation metadata (model info, parameters) |

---

### Video Endpoints

#### POST /video/short-generation

AI short video generation using xAI's Grok Video API. Generates a 10-second high-quality video.

| | |
|---|---|
| **Price** | $0.50 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Prompt for video generation |
| `aspect_ratio` | string | No | Video aspect ratio |
| `image_url` | string | No | Input image URL for image-to-video generation |

**Response**

| Field | Type | Description |
|---|---|---|
| `video_url` | string | Generated video URL |
| `duration` | number | Video duration in seconds (always 10) |
| `model` | string | Model used for generation |
| `metadata` | object | Generation metadata (request_id, aspect_ratio) |

---

### Audio Endpoints

#### POST /audio/elevenlabs-music

AI music generation using ElevenLabs Music. Dynamic pricing based on duration: $1 per 120 seconds, max 3 minutes.

| | |
|---|---|
| **Price** | Up to $1.50 USDC (dynamic by duration) |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Description of the music to generate |
| `output_format` | string | No | Output format (e.g. `mp3_standard`) |
| `music_length_ms` | number | No | Duration in milliseconds (min 1000, max 180000). Price = `music_length_ms / 120000` USD |
| `force_instrumental` | boolean | No | Force instrumental output |

**Response**

| Field | Type | Description |
|---|---|---|
| `music_url` | string | Generated audio URL (CDN) |
| `duration_seconds` | number | Duration in seconds |
| `metadata` | object | Generation metadata |

---

#### POST /audio/x-text-to-speech

X.AI text-to-speech: convert text to speech (MP3).

| | |
|---|---|
| **Price** | $0.01 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes | Text to convert to speech |
| `voice_id` | string | No | Voice: `Eve`, `Ara`, `Leo`, `Rex`, or `Sal` |
| `output_format` | object | No | Optional: `codec`, `sample_rate`, `bit_rate` |

**Response**

| Field | Type | Description |
|---|---|---|
| `audio_url` | string | Generated audio URL (CDN) |
| `duration_seconds` | number | Duration in seconds |
| `metadata` | object | Generation metadata |

Free voice listing (no payment required): `GET /audio/x-text-to-speech/voices`

---

#### POST /audio/speech-to-text

Speech-to-text: transcribe audio from a URL using OpenAI GPT-4o Transcribe (Replicate).

| | |
|---|---|
| **Price** | $0.02 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `audio_file` | string | Yes | HTTPS URL of the audio file to transcribe (e.g. MP3) |
| `language` | string | No | Language code (default: `en`) |

**Response**

| Field | Type | Description |
|---|---|---|
| `text` | string | Transcribed text |
| `metadata` | object | Transcription metadata |

---

### Token Endpoints

#### GET /token/pumpfun-trending

Trending PumpFun tokens with AI-powered analysis including dominant meta summary, fresh token suggestions, and detailed token information.

| | |
|---|---|
| **Price** | $0.10 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body** — None (GET request)

**Response**

| Field | Type | Description |
|---|---|---|
| `summary` | string | AI-generated summary of dominant memecoin meta |
| `suggestions` | array | Array of 3 fresh token ideas (`idea`, `reference_ca`, `reason`) |
| `trending_tokens` | array | Array of trending tokens with `icon`, `name`, `ticker`, `mc`, `ca`, `social`, price changes (5m/1h/6h/24h), `icon_description` |
| `count` | number | Number of trending tokens returned |

---

#### GET /token/pumpfun-movers

Movers PumpFun tokens with AI-powered analysis. Same response schema as `/token/pumpfun-trending`.

| | |
|---|---|
| **Price** | $0.10 USDC |
| **Network** | Solana mainnet / Base mainnet |

---

#### POST /token/starter-kit

Generate token logo and banner automatically from a prompt. Extracts token information, generates logo, then creates a matching banner.

| | |
|---|---|
| **Price** | $0.20 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | Yes | Description of the token |
| `ca_reference` | string | No | Contract address of reference token to extract logo from |

**Response**

| Field | Type | Description |
|---|---|---|
| `token_name` | string | The token name |
| `token_ticker` | string | Token ticker symbol (uppercase) |
| `token_description` | string | Comprehensive token description |
| `logo_url` | string | Generated logo URL (CDN) |
| `banner_url` | string | Generated banner URL (CDN) |

---

#### POST /token/news

Fetch token information from Jupiter, get curated news from Syra, and generate banner and social content with Xona.

| | |
|---|---|
| **Price** | $0.50 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `token` | string | Yes | Token mint address, symbol, or name |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the operation was successful |
| `mint` | string | Token mint address from Jupiter |
| `token` | string | Token name from Jupiter |
| `ticker` | string | Token symbol from Jupiter |
| `trending_news` | object | AI-generated news: `title` (max 4 words), `tweet_draft`, `banner_url` (CDN) |

---

#### POST /token/solana-discovery

Solana token discovery via OKX Onchain OS — hot tokens, top movers, smart money signals, and top traders.

| | |
|---|---|
| **Price** | $0.01 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string | Yes | Discovery action: `hot_tokens`, `top_movers`, `search`, `smart_money`, or `top_traders` |
| `keyword` | string | No | Search keyword (for `search` action) |
| `limit` | number | No | Number of results (default: 20) |
| `timeFrame` | string | No | Time frame (default: `4`) |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the operation was successful |
| `chain` | string | Chain identifier (`solana`) |
| `action` | string | The action performed |
| `data` | array | Array of discovery results |

---

#### POST /token/solana-market

Solana token market data via OKX Onchain OS — price overview, risk analysis, holder analysis, candlesticks, and whale trades.

| | |
|---|---|
| **Price** | $0.01 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string | Yes | Market data action: `token_overview`, `token_risk`, `holder_analysis`, `candlesticks`, `whale_trades`, or `cluster_check` |
| `tokenAddress` | string | No | Token contract address |
| `tokenAddresses` | string[] | No | Array of token addresses (for `token_overview`) |
| `bar` | string | No | Candlestick interval (default: `1H`) |
| `limit` | number | No | Number of results (default: 50) |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the operation was successful |
| `chain` | string | Chain identifier (`solana`) |
| `action` | string | The action performed |
| `data` | object | Market data results |

---

#### POST /token/xlayer-discovery

X Layer token discovery via OKX Onchain OS — same actions and schema as `/token/solana-discovery` but for the X Layer chain.

| | |
|---|---|
| **Price** | $0.01 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

---

#### POST /token/xlayer-market

X Layer token market data via OKX Onchain OS — same actions and schema as `/token/solana-market` but for the X Layer chain.

| | |
|---|---|
| **Price** | $0.01 USDC |
| **Network** | Solana mainnet / Base mainnet / SKALE / X Layer |

---

### AI Endpoints

#### POST /ai/x-persona

Extract structured persona from an X (Twitter) username. Analyzes posts, profile, and communication style.

| | |
|---|---|
| **Price** | $0.05 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `x_username` | string | Yes | X (Twitter) username (with or without `@`) |

**Response**

| Field | Type | Description |
|---|---|---|
| `persona` | object | Persona information: summary, tone, core topics, beliefs |
| `style_profile` | object | Writing style and voice characteristics |
| `content_patterns` | object | Content patterns and posting behavior analysis |
| `avatar` | object | Avatar info: image type, prompt, reference images |

---

#### POST /ai/x-news

Extract latest news from an X (Twitter) username, generate draft tweet and banner.

| | |
|---|---|
| **Price** | $0.50 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `x_username` | string | Yes | X (Twitter) username (with or without `@`) |
| `x_persona` | string | No | X username to mimic persona/style for tweet draft |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the operation was successful |
| `x_username` | string | The X username |
| `trending_news` | object | AI-generated news: `title` (max 4 words), `tweet_draft`, `banner_url` (CDN) |

---

### Tokens API Endpoints (via tokens.xyz)

Proxied access to the [Tokens API](https://docs.tokens.xyz) for canonical asset data, market snapshots, risk scores, OHLCV candles, and more. All `:assetId` path params are passed in the JSON body as `assetId` instead of in the URL.

#### POST /tokens-api/search

Search assets by text query — returns canonical assets plus singleton Solana tokens with market stats.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | string | Yes | Search query (name, symbol, or mint address) |
| `limit` | number | No | Max results 1-50 (default 20) |
| `category` | string | No | Filter by asset category |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the request succeeded |
| `data` | object | Contains `query`, `results[]` with assetId, name, symbol, stats (price, liquidity, volume, marketCap, priceChange) |

---

#### POST /tokens-api/resolve

Resolve a Solana mint address or asset reference to its canonical asset ID and variant details.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `mint` | string | No | Solana mint address (base58) |
| `ref` | string | No | Asset reference — assetId, alias, mint, or `solana-<mint>`. One of `mint` or `ref` required. |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the request succeeded |
| `data` | object | Contains `assetId`, `asset` (name, symbol, category, aliases), `variant` (mint, chain, kind, trustTier, tags) |

---

#### POST /tokens-api/curated

Retrieve curated/pre-assembled asset collections with market data.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | string | No | Curated list ID or `all` (default: `all`) |
| `groupBy` | string | No | `asset` (default) or `mint` |

---

#### POST /tokens-api/market-snapshots

Bulk lookup cached market snapshots for up to 250 Solana mints in one call.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `mints` | string[] | Yes | Array of Solana mint addresses (max 250) |

---

#### POST /tokens-api/variant-markets

Batch lookup per-mint variant market snapshots for up to 50 mints.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `mints` | string[] | Yes | Array of Solana mint addresses (max 50) |

---

#### POST /tokens-api/risk-summary

Quick risk/quality assessment for a Solana mint — score, grade, label, and trust flags.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `mint` | string | Yes | Solana mint address |

**Response**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the request succeeded |
| `data` | object | Contains `score`, `grade` (A-F), `label`, `tone` (info/success/warning/danger), `isTrustedLaunch`, `hasInsufficientData` |

---

#### POST /tokens-api/asset-detail

Complete asset details — metadata, variants, market stats. Optionally include profile, risk, OHLCV, or DEX markets.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug (e.g. `solana`, `usdc`) or singleton ID (`solana-<mint>`) |
| `include` | string | No | Comma-separated: `profile`, `risk`, `ohlcv`, `markets` |
| `mint` | string | No | Specific variant mint for include computations |
| `ohlcvInterval` | string | No | Candle interval: `1m`, `5m`, `15m`, `1H`, `4H`, `1D`, `1W` |
| `ohlcvFrom` | number | No | Unix timestamp start |
| `ohlcvTo` | number | No | Unix timestamp end |

---

#### POST /tokens-api/asset-variants

List all token variants (native, wrapped, bridged, etc.) for a canonical asset.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `kind` | string | No | Filter: `native`, `wrapped`, `bridged`, `lst`, `stablecoin`, etc. |
| `trustTier` | string | No | Filter: `tier1`, `tier2`, `experimental` |

---

#### POST /tokens-api/asset-variant-market

Get the cached market snapshot for a single variant of an asset.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint (defaults to primary) |

---

#### POST /tokens-api/asset-markets

List DEX market pools for a specific mint — liquidity, volume, and protocol tokens.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint |
| `offset` | number | No | Pagination offset (default 0) |
| `limit` | number | No | Results per page 1-50 (default 10) |

---

#### POST /tokens-api/asset-ohlcv

Get OHLCV (candlestick) price data for a specific mint.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint |
| `interval` | string | No | `1m`, `5m`, `15m`, `1H`, `4H`, `1D`, `1W` (default `1H`) |
| `from` | number | No | Unix timestamp start (default: 7 days ago) |
| `to` | number | No | Unix timestamp end (default: now) |

---

#### POST /tokens-api/asset-price-chart

Canonical price history chart — uses external provider data when available, falls back to on-chain OHLCV.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |

---

#### POST /tokens-api/asset-profile

Asset profile — aggregated statistics, metadata, and external provider data.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |

---

#### POST /tokens-api/asset-tickers

Exchange ticker listings — shows where an asset trades and at what volume.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `offset` | number | No | Pagination offset (default 0) |
| `limit` | number | No | Results per page 1-50 (default 10) |
| `order` | string | No | Sort: `volume_desc` |

---

#### POST /tokens-api/asset-description

Cached description summary for a specific mint of an asset.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint |

---

#### POST /tokens-api/asset-risk-summary

Risk score summary for a specific asset variant — score, grade, and trust flags.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint |

---

#### POST /tokens-api/asset-risk-details

Comprehensive risk analysis with detailed scoring inputs.

| | |
|---|---|
| **Price** | $0.0001 USDC |
| **Network** | Solana mainnet / Base mainnet |

**Request Body**

| Field | Type | Required | Description |
|---|---|---|---|
| `assetId` | string | Yes | Canonical slug or singleton ID |
| `mint` | string | No | Specific variant mint |

---

## Multi-Network Endpoints

Every Solana endpoint above is also available on **Base mainnet**, **SKALE on Base**, and **X Layer** by prefixing the path accordingly.

| Solana Path | Base Mainnet | SKALE on Base | X Layer |
|---|---|---|---|
| `POST /image/designer` | `POST /base-main/image/designer` | `POST /base/image/designer` | `POST /xlayer/image/designer` |
| `POST /image/flux-2-pro` | `POST /base-main/image/flux-2-pro` | `POST /base/image/flux-2-pro` | `POST /xlayer/image/flux-2-pro` |
| `POST /video/short-generation` | `POST /base-main/video/short-generation` | `POST /base/video/short-generation` | `POST /xlayer/video/short-generation` |
| `GET /token/pumpfun-trending` | `GET /base-main/token/pumpfun-trending` | `GET /base/token/pumpfun-trending` | — |
| `POST /token/solana-discovery` | `POST /base-main/token/solana-discovery` | `POST /base/token/solana-discovery` | `POST /xlayer/token/solana-discovery` |
| `POST /ai/x-persona` | `POST /base-main/ai/x-persona` | `POST /base/ai/x-persona` | `POST /xlayer/ai/x-persona` |
| `POST /tokens-api/search` | `POST /base-main/tokens-api/search` | — | — |
| `POST /tokens-api/asset-ohlcv` | `POST /base-main/tokens-api/asset-ohlcv` | — | — |
| ... | ... | ... | ... |

Pricing and schemas are identical across all networks. The only difference is the payment network:

- **Solana**: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (mainnet)
- **Base mainnet**: `eip155:8453`
- **SKALE on Base**: `eip155:1187947933` (zero gas fees)
- **X Layer**: `eip155:196` (OKX L2)

---

## Quick Reference

| Endpoint | Method | Price (USDC) |
|---|---|---|
| `/image/creative-director` | POST | $0.03 |
| `/image/designer` | POST | $0.08 |
| `/image/nano-banana-pro` | POST | $0.20 |
| `/image/nano-banana` | POST | $0.10 |
| `/image/nano-banana-2` | POST | $0.06–$0.15 |
| `/image/grok-imagine` | POST | $0.04 |
| `/image/flux-2-pro` | POST | $0.05 |
| `/image/flux-2-max` | POST | $0.08 |
| `/image/flux-2-flex` | POST | $0.06 |
| `/image-model/qwen-image` | POST | $0.05 |
| `/image-model/seedream-4.5` | POST | $0.08 |
| `/video/short-generation` | POST | $0.50 |
| `/audio/elevenlabs-music` | POST | Up to $1.50 |
| `/audio/x-text-to-speech` | POST | $0.01 |
| `/audio/speech-to-text` | POST | $0.02 |
| `/token/pumpfun-trending` | GET | $0.10 |
| `/token/pumpfun-movers` | GET | $0.10 |
| `/token/starter-kit` | POST | $0.20 |
| `/token/news` | POST | $0.50 |
| `/token/solana-discovery` | POST | $0.01 |
| `/token/solana-market` | POST | $0.01 |
| `/token/xlayer-discovery` | POST | $0.01 |
| `/token/xlayer-market` | POST | $0.01 |
| `/ai/x-persona` | POST | $0.05 |
| `/ai/x-news` | POST | $0.50 |
| `/tokens-api/search` | POST | $0.0001 |
| `/tokens-api/resolve` | POST | $0.0001 |
| `/tokens-api/curated` | POST | $0.0001 |
| `/tokens-api/market-snapshots` | POST | $0.0001 |
| `/tokens-api/variant-markets` | POST | $0.0001 |
| `/tokens-api/risk-summary` | POST | $0.0001 |
| `/tokens-api/asset-detail` | POST | $0.0001 |
| `/tokens-api/asset-variants` | POST | $0.0001 |
| `/tokens-api/asset-variant-market` | POST | $0.0001 |
| `/tokens-api/asset-markets` | POST | $0.0001 |
| `/tokens-api/asset-ohlcv` | POST | $0.0001 |
| `/tokens-api/asset-price-chart` | POST | $0.0001 |
| `/tokens-api/asset-profile` | POST | $0.0001 |
| `/tokens-api/asset-tickers` | POST | $0.0001 |
| `/tokens-api/asset-description` | POST | $0.0001 |
| `/tokens-api/asset-risk-summary` | POST | $0.0001 |
| `/tokens-api/asset-risk-details` | POST | $0.0001 |

---

## Network Details

| Network | Chain ID | Path Prefix | Facilitator | Asset |
|---|---|---|---|---|
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | _(root)_ | `https://x402.dexter.cash` | USDC |
| Base mainnet | `eip155:8453` | `/base-main` | `https://facilitator.payai.network` | USDC |
| SKALE on Base | `eip155:1187947933` | `/base` | `https://x402.dexter.cash` | Bridged USDC (SKALE Bridge) |
| X Layer | `eip155:196` | `/xlayer` | `https://x402.dexter.cash` | USDC |