Service Discovery

Overview

The x402 Gateway exposes several discovery endpoints that require no authentication. AI agents can call these at startup to understand what services are available, what models exist, and how much things cost — then dynamically decide how to proceed.

SDK Discovery Module

import { createX402Client } from '@zan_team/x402';

// Discovery works even without preAuth
const client = await createX402Client({
  gatewayUrl: 'https://x402.zan.top',
  privateKey: '0x...',
});

// All discovery calls are unauthenticated
const health = await client.discovery.health();
const { providers } = await client.discovery.listProviders();
const { networks } = await client.discovery.listNetworks();
const { bundles } = await client.discovery.listBundles();
const { models } = await client.discovery.listAiModels();

Endpoints

`GET /llms.txt` — LLM-readable service description

A plain-text document designed to be loaded into an LLM's context window. Contains authentication methods, available services, credit endpoints, supported chains, and usage instructions in a format optimized for language models.

curl https://x402.zan.top/llms.txt

Use case: Agent loads this once at startup to understand the full platform capability without needing structured API exploration.

`GET /.well-known/x402.json` — x402 capability declaration

Standard x402 protocol discovery document declaring the gateway's capabilities.

curl https://x402.zan.top/.well-known/x402.json

{
  "name": "x402 Gateway Platform",
  "version": "1.0.0",
  "description": "Universal API monetization via x402 protocol",
  "auth": { "type": "SIWE/SIWS", "endpoint": "/auth" },
  "providers": [
    { "id": "zan-rpc", "name": "ZAN Multi-chain RPC", "type": "rpc" },
    { "id": "zan-ai", "name": "ZAN AI Service", "type": "ai" }
  ],
  "bundles": [
    { "name": "default", "credits": 100000, "price": "0.015" }
  ]
}

`GET /providers` — Service list

Returns all registered service providers with their routes and billing info.

curl https://x402.zan.top/providers

{
  "providers": [
    {
      "id": "zan-rpc",
      "name": "ZAN Multi-chain RPC",
      "type": "PROXY",
      "description": "Multi-chain JSON-RPC proxy",
      "routes": [{ "path": "/rpc/{ecosystem}/{network}", "method": "POST" }]
    },
    {
      "id": "zan-ai",
      "name": "ZAN AI Service",
      "type": "PROXY",
      "description": "AI model inference proxy",
      "routes": []
    }
  ]
}

The zan-ai provider does not expose routes through the standard provider mechanism. AI models are accessed via the dedicated POST /ai/{model} endpoint.

`GET /networks` — Supported blockchain networks

Lists all supported ecosystems and networks for the Node Service.

curl https://x402.zan.top/networks

{
  "networks": [
    { "ecosystem": "eth", "network": "mainnet", "providerId": "zan-rpc" },
    { "ecosystem": "eth", "network": "sepolia", "providerId": "zan-rpc" },
    { "ecosystem": "solana", "network": "mainnet", "providerId": "zan-rpc" },
    { "ecosystem": "base", "network": "mainnet", "providerId": "zan-rpc" }
  ]
}

`GET /v1/discovery/ai` — AI model catalog

Returns the real-time model catalog with per-token pricing. This data is dynamically fetched from upstream and reflects the currently available models.

curl https://x402.zan.top/v1/discovery/ai

{
  "result": "OK",
  "msg": "SUCCESS",
  "data": {
    "models": [
      {
        "id": "deepseek-v4-flash",
        "inputPricePerToken": "0.000000140",
        "outputPricePerToken": "0.000000280"
      },
      {
        "id": "claude-opus-4-6",
        "inputPricePerToken": "0.000005000",
        "outputPricePerToken": "0.000025000"
      },
      {
        "id": "qwen3.7-max",
        "inputPricePerToken": "0.000001650",
        "outputPricePerToken": "0.000004951"
      }
    ]
  }
}

`GET /credits/bundles` — Available credit packages

Lists credit bundles that can be purchased.

curl https://x402.zan.top/credits/bundles

{
  "bundles": [
    {
      "name": "default",
      "credits": 100000,
      "price": "0.015",
      "description": "~5,000 RPC calls",
      "pricing": {
        "mainnet": { "usdc": "0.015", "credits": 100000 },
        "testnet": { "usdc": "1", "credits": 100000 }
      }
    }
  ]
}

`GET /health` — Health check

Simple health probe.

curl https://x402.zan.top/health

{ "status": "ok", "uptime": 3600 }

Agent discovery patterns

Startup discovery

An agent should discover capabilities once at startup:

async function discoverServices(client) {
  // 1. What chains are available?
  const { networks } = await client.discovery.listNetworks();
  console.log(`Available chains: ${networks.length}`);

  // 2. What AI models can I use?
  const { models } = await client.discovery.listAiModels();
  console.log(`Available models: ${models.length}`);

  // 3. What does it cost?
  const { bundles } = await client.discovery.listBundles();
  console.log(`Credit price: ${bundles[0].price} USDC for ${bundles[0].credits} credits`);

  return { networks, models, bundles };
}

Dynamic model selection

Choose the most cost-effective model at runtime:

async function cheapestModel(client) {
  const { models } = await client.discovery.listAiModels();

  // Sort by output price (most cost-sensitive dimension)
  const sorted = models.sort((a, b) =>
    parseFloat(a.outputPricePerToken) - parseFloat(b.outputPricePerToken)
  );

  return sorted[0].id; // cheapest model
}

const model = await cheapestModel(client);
const response = await client.chat(model, {
  messages: [{ role: 'user', content: 'Hello' }],
});

Cache strategy

Model catalogs are refreshed from upstream every 5 minutes. For agents making frequent calls:

let modelCache = null;
let cacheTime = 0;
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getModels(client) {
  if (!modelCache || Date.now() - cacheTime > CACHE_TTL) {
    const { models } = await client.discovery.listAiModels();
    modelCache = models;
    cacheTime = Date.now();
  }
  return modelCache;
}

Using llms.txt for LLM agents

If your agent is powered by an LLM (e.g., LangChain ReAct agent), you can load llms.txt into its context to teach it about the gateway:

const response = await fetch('https://x402.zan.top/llms.txt');
const serviceDescription = await response.text();

// Add to agent's system prompt
const systemPrompt = `You have access to the following blockchain services:\n\n${serviceDescription}`;

Next steps

Quick Start — Get running in 5 minutes
SDK Reference — Full DiscoveryModule API
Node Service — Available chains and methods
AI Models — Model catalog and pricing

Overview

SDK Discovery Module

Endpoints

GET /llms.txt — LLM-readable service description

GET /.well-known/x402.json — x402 capability declaration

GET /providers — Service list

GET /networks — Supported blockchain networks

GET /v1/discovery/ai — AI model catalog

GET /credits/bundles — Available credit packages

GET /health — Health check