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