API Documentation

Everything you need to integrate OrbitX402 discovery into your agent or application.

Overview

OrbitX402 is an open-source x402 discovery layer for AI agents on the Solana network. It indexes x402-enabled servers, tracks USDC transfers through facilitators, and provides LLM-powered natural language search for agents to find and consume paid API resources.

Quick Start

Add OrbitX402 discovery to your agent in one step: Fetch the skill instructions and add them to your agent's system prompt:

curl https://api.orbitx402.com/skill.md

The skill MD contains instructions, actions, and an OpenAI function-calling schema.

POST /api/discover

LLM-Powered Natural Language Search

Send a natural language query to find relevant x402 servers and resources. Uses Gemini Flash to rank results by relevance.

Param	Type	Required	Description
query	string	yes	Natural language search query (max 500 chars)

curl -X POST https://api.orbitx402.com/api/discover \
  -H "Content-Type: application/json" \
  -d '{"query": "find image generation APIs on Solana"}'

Response

{
  "query": "find image generation APIs on Solana",
  "results": [
    {
      "serverUrl": "https://api.xona-agent.com",
      "title": "Xona Agent | x402 Creative AI Agent",
      "reason": "Offers 61 image generation endpoints...",
      "relevanceScore": 95,
      "server": { "title": "...", "chains": ["solana"], "stats": {...} },
      "resources": [
        { "endpoint": "...", "slug": "image/creative-director", "method": "POST" }
      ]
    }
  ],
  "total": 3,
  "model": "gemini-2.0-flash",
  "fallback": false
}

GET /api/servers

List x402 Servers

Browse all indexed x402 servers with filtering and pagination.

Param	Type	Required	Description
chain	string	no	Filter by blockchain (solana, base, polygon)
facilitator	string	no	Filter by facilitator (dexter, payAI, relai)
search	string	no	Keyword search on title/description/URL
page	number	no	Page number (default: 1)
limit	number	no	Items per page (default: 50, max: 100)

curl "https://api.orbitx402.com/api/servers?chain=solana&search=analytics&limit=10"

GET /api/servers/detail

Server Detail + Endpoints

Get a single server with all its discovered x402 resources.

Param	Type	Required	Description
url	string	yes	Server URL (e.g., https://api.nansen.ai)

curl "https://api.orbitx402.com/api/servers/detail?url=https://api.nansen.ai"

POST /api/servers/register

Register a new x402 server to make it discoverable. The system probes your server's /.well-known/x402 discovery document to find endpoints automatically.

Param	Type	Required	Description
url	string	yes	Your server URL (must be https)
title	string	no	Server name
description	string	no	What your server does

curl -X POST https://api.orbitx402.com/api/servers/register \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com"}'

Response

{
  "success": true,
  "server": {
    "serverUrl": "https://your-server.com",
    "title": "",
    "resourceCount": 12
  },
  "message": "Registered with 12 x402 endpoints discovered"
}

Rate limited to 5 registrations per hour per IP. Add a /.well-known/x402 discovery document to your server for automatic endpoint detection.

GET /api/resources

List x402 Endpoints

Browse all discovered x402 endpoints across all servers.

Param	Type	Required	Description
server	string	no	Filter by server URL
method	string	no	Filter by HTTP method (GET, POST, etc.)
search	string	no	Keyword search
page	number	no	Page number
limit	number	no	Items per page (max: 200)

curl "https://api.orbitx402.com/api/resources?server=https://api.nansen.ai&method=POST"

GET /api/facilitators

Payment Facilitators

List x402 payment facilitators tracked on the Solana network (PayAI, Dexter, Relai).

curl https://api.orbitx402.com/api/facilitators

GET /api/transfers

Transaction History

Paginated USDC transactions through x402 facilitators on Solana.

Param	Type	Required	Description
facilitator	string	no	Filter by facilitator ID
direction	string	no	sent or received
page	number	no	Page number
limit	number	no	Items per page (max: 200)

curl "https://api.orbitx402.com/api/transfers?facilitator=dexter&limit=20"

GET /api/stats

Ecosystem Stats

Aggregated statistics: total volume, transactions, servers, endpoints, daily volume breakdown. Supports period filtering.

Param	Type	Required	Description
period	string	no	24h, 7d, 30d, or omit for all time

curl "https://api.orbitx402.com/api/stats?period=24h"