Skip to content

discovery.md

Latest commit

 

History

History
309 lines (242 loc) · 5.95 KB

discovery.md

File metadata and controls

309 lines (242 loc) · 5.95 KB

x402 Discovery Network

The discovery network allows AI agents to find and use your paid API.

What is Discovery?

Discovery enables:

  • AI agents to find APIs by category, capability, or price
  • Automatic negotiation of payment terms
  • Semantic search for relevant services
  • Trust scoring based on reputation

Enabling Discovery

Basic Configuration

{
  "discovery": {
    "enabled": true,
    "categories": ["crypto", "market-data"],
    "instructions": "Real-time crypto price data"
  }
}

Full Configuration

{
  "discovery": {
    "enabled": true,
    "categories": ["crypto", "market-data", "analytics"],
    "tags": ["bitcoin", "ethereum", "prices", "real-time", "API"],
    "instructions": "Use this API to get real-time cryptocurrency prices and analytics. Supports BTC, ETH, and 1000+ tokens.",
    "capabilities": [
      "price-lookup",
      "historical-data",
      "analytics"
    ],
    "examples": [
      {
        "description": "Get Bitcoin price",
        "request": {
          "method": "GET",
          "path": "/api/price/BTC"
        },
        "response": {
          "symbol": "BTC",
          "price": 67890.12,
          "change24h": 2.5
        }
      }
    ],
    "openapi": "/api/openapi.json"
  }
}

Categories

Standard categories for API classification:

Category Description
crypto Cryptocurrency data
market-data Financial market data
analytics Data analytics
ai AI/ML services
weather Weather data
news News aggregation
social Social media data
compute Compute services
storage Storage services
search Search services

Custom Categories

You can use custom categories:

{
  "discovery": {
    "categories": ["crypto", "my-custom-category"]
  }
}

Instructions

The instructions field tells AI agents how to use your API:

{
  "discovery": {
    "instructions": "This API provides real-time cryptocurrency prices. Use GET /api/price/{symbol} to get the current price of any supported cryptocurrency. Supported symbols include BTC, ETH, SOL, and 1000+ others. The API returns price in USD, 24h change percentage, and market cap."
  }
}

Best Practices:

  • Be specific about endpoints
  • List supported parameters
  • Describe response format
  • Include rate limits
  • Mention pricing tiers

Examples

Provide usage examples for AI agents:

{
  "discovery": {
    "examples": [
      {
        "description": "Get current Bitcoin price",
        "request": {
          "method": "GET",
          "path": "/api/price/BTC"
        },
        "response": {
          "symbol": "BTC",
          "price": 67890.12
        }
      },
      {
        "description": "Get multiple prices",
        "request": {
          "method": "POST",
          "path": "/api/prices",
          "body": {
            "symbols": ["BTC", "ETH", "SOL"]
          }
        },
        "response": {
          "prices": [
            { "symbol": "BTC", "price": 67890.12 },
            { "symbol": "ETH", "price": 3456.78 }
          ]
        }
      }
    ]
  }
}

OpenAPI Integration

Link to your OpenAPI specification:

{
  "discovery": {
    "openapi": "/api/openapi.json"
  }
}

AI agents can use this for detailed endpoint information.

Registration

Automatic Registration

On deployment, your API is automatically registered:

npx @nirholas/x402-deploy deploy
# ✓ Deployed to https://my-api.vercel.app
# ✓ Registered in discovery network

Manual Registration

Register manually:

npx @nirholas/x402-deploy register --url https://my-api.com

Verify Registration

Check your registration:

npx @nirholas/x402-deploy status
# API: crypto-data-api
# URL: https://my-api.com
# Status: Active
# Categories: crypto, market-data
# Trust Score: 98

Discovery API

Search APIs

AI agents can search for APIs:

import { discoverAPIs } from "@nirholas/x402-deploy/discovery";

// Find crypto price APIs under $0.01
const apis = await discoverAPIs({
  categories: ["crypto"],
  capabilities: ["price-lookup"],
  maxPrice: "$0.01",
});

// Returns:
[
  {
    name: "crypto-data-api",
    url: "https://api.x402.dev/crypto-data",
    instructions: "Real-time crypto prices...",
    pricing: {
      "GET /api/price/*": "$0.0001"
    },
    trustScore: 98
  }
]

Query Parameters

Parameter Type Description
categories string[] Filter by categories
tags string[] Filter by tags
capabilities string[] Filter by capabilities
maxPrice string Maximum price per request
minTrustScore number Minimum trust score (0-100)
query string Semantic search query

Semantic Search

const apis = await discoverAPIs({
  query: "I need to get Bitcoin price history for the last 30 days",
});

Trust Score

APIs are assigned trust scores based on:

Factor Weight
Uptime 30%
Response time 20%
Payment reliability 25%
User ratings 15%
Age 10%

Improving Trust Score

  • Maintain high uptime (99.9%+)
  • Fast response times (<100ms)
  • Always deliver promised content
  • Get positive user reviews
  • Consistent operation over time

llms.txt Support

Your API automatically serves llms.txt for LLM discovery:

# My Crypto API

> Real-time cryptocurrency prices and analytics

## Endpoints

- GET /api/price/{symbol} - Get current price ($0.0001)
- GET /api/history/{symbol} - Get price history ($0.001)

## Payment

Accepts USDC on Arbitrum One
Wallet: 0x...

Access at: https://your-api.com/llms.txt

Opting Out

Disable discovery:

{
  "discovery": {
    "enabled": false
  }
}

Or add to robots.txt:

User-agent: x402-crawler
Disallow: /

Next Steps