Quick Start

Prerequisites

• Node.js >= 20
• npm or pnpm

Installation

git clone https://github.com/ango-ya/x402-relay.git
cd x402-relay
npm install

Configuration

Copy the example environment file:

cp .env.example .env

Key variables:

Variable	Description	Required
API_KEY	Admin API key for service management	Yes
DB_PATH	SQLite database path	No (default: ./x402-hub.db)
PORT	Server port	No (default: 3402)
SCAN_INTERVAL_MS	Discovery scan interval	No (default: 3600000)

Start the Server

# Development
npm run dev

# Production
npm run build && npm start

The API is now available at http://localhost:3402.

Verify

# Health check
curl http://localhost:3402/health

# List categories
curl http://localhost:3402/api/categories

# Search services
curl http://localhost:3402/api/services?query=AI

Connect an AI Agent (MCP)

# Start the MCP server
npm run mcp

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "x402-relay": {
      "command": "node",
      "args": ["<path-to-x402-relay>/dist/mcp-server.js"]
    }
  }
}

Next Steps

• How It Works — Understand the protocol
• Register Your API — Add your API to the catalog
• API Reference — Full endpoint documentation