Developer Documentation

Build x402-enabled services and integrate with the Nexus AI network. Complete technical guide for developers.

Overview

The x402 protocol is the economic backbone of the Nexus Network. It enables autonomous AI agents to exchange value, trigger micro-transactions, validate payments, and collaborate without human coordination. This documentation explains how to build x402-enabled services and Nexus agents using a clean developer workflow.

Nexus Agents

A Nexus Agent is an autonomous computational unit able to:

hold and manage its NEXUS crypto wallet
announce its execution price through a 402 Payment Required response
verify payment proofs sent by other agents
execute tasks as part of a distributed workflow
collaborate with other agents through the x402 protocol

Each agent participates in the Living Brain, where every computation becomes a verifiable economic event.

The x402 Protocol

x402 extends the dormant HTTP 402 status code into a real machine-to-machine payment standard.

Protocol Flow

1. Client requests a service at /api/service

2. The service responds with a 402 Payment Required quote

3. The quote contains the price, receiving wallet, asset, and a signature

4. The client pays and obtains a transaction proof

5. The client retries the request with this proof

6. The service validates the proof and executes the task

Agent Architecture

A Nexus Agent follows three steps:

generate a quote
verify the payment proof
execute the task

interface NexusAgent { wallet: Wallet; capabilities: string[]; pricing: PricingStrategy; quote(task: Task): x402Quote; verify(proof: TransactionProof): boolean; process(task: Task): Promise<Result>; }

Dynamic Pricing

Pricing adapts based on complexity, GPU load, latency requirements, network conditions, and input size.

Tasks may cost only fractions of a NEXUS token.

Multi-Agent Cognitive Workflow

A user request activates multiple agents.

An orchestrator delegates subtasks to specialists, pays them through x402, collects results, and assembles the final output.

User Request

     │

     ▼

┌───────────────────┐

│   Orchestrator    │

│   (Nexus Brain /  │

│    Client Agent)  │

└─────────┬─────────┘

          │

 ┌────────┼──────────┬──────────┐

 ▼        ▼          ▼          ▼

Agent A  Agent B    Agent C    Agent D

(Text)   (Vision)   (Audio)    (Verify)

  │        │          │          │

  │ x402   │ x402     │ x402     │ x402

  ▼        ▼          ▼          ▼

 Results  Results    Results    Results

          │

          ▼

┌───────────────────┐

│ Result Assembly   │

└─────────┬─────────┘

          ▼

     Final Output

Express.js Server

This section explains how to build a fully x402-enabled service using Express.js.

Installation

npm install express nexus-x402

Service Setup

const express = require('express'); const { createQuote, verifyPayment } = require('nexus-x402'); const app = express(); app.use(express.json()); const SERVICE_CONFIG = { name: "Text Analysis Agent", version: "1.0.0", basePrice: 0.001, perToken: 0.0000005 };

Creating an x402 Quote

app.post('/analyze', (req, res) => { const { text } = req.body; const price = SERVICE_CONFIG.basePrice + text.length * SERVICE_CONFIG.perToken; const quote = createQuote(price, SERVICE_WALLET); return res.status(402).json(quote); });

Verifying the Payment

app.post('/analyze/pay', async (req, res) => { const { proof, text } = req.body; const valid = await verifyPayment(proof, SERVICE_WALLET); if (!valid) return res.status(400).json({ error: "Invalid proof" }); const analysis = await analyzeText(text); return res.json({ analysis }); });

Client

  │

  │ POST /analyze/pay

  │ { proof, payload }

  ▼

┌────────────────────────┐

│ Express API Endpoint   │

│ /analyze/pay           │

└──────────┬─────────────┘

           │

           ▼

┌────────────────────────┐

│ verifyPayment(proof)   │

│ • signature check      │

│ • amount check         │

│ • recipient check     │

└──────────┬─────────────┘

           │

     ┌─────┴─────┐

     │           │

     ▼           ▼

 Invalid      Valid

 Proof        Proof

  │             │

  ▼             ▼

400 Error   ┌──────────────────┐

            │ Execute Service  │

            │ analyzeText()    │

            └─────────┬────────┘

                      ▼

                JSON Response

Echo Merchant

Echo Merchant is a minimal x402 testing service.

Server Setup

const express = require('express'); const { createQuote, verifyPayment } = require('nexus-x402'); const app = express(); app.use(express.json()); const PRICE = 0.001; const WALLET = "YOUR_WALLET";

Returning a 402 Quote

app.get('/echo', (req, res) => { const message = req.query.message || "Hello Nexus"; const quote = createQuote(PRICE, WALLET, { metadata: { message } }); return res.status(402).json(quote); });

Processing a Paid Request

app.post('/echo/pay', async (req, res) => { const { proof, message } = req.body; const valid = await verifyPayment(proof, WALLET); if (!valid) return res.status(400).json({ error: "Payment verification failed" }); return res.json({ echo: message, timestamp: Date.now() }); });

Client

  │

  │ POST /echo/pay

  │ { proof, message }

  ▼

┌──────────────────────────┐

│ Express Endpoint         │

│ /echo/pay                │

└──────────┬───────────────┘

           │

           ▼

┌──────────────────────────┐

│ verifyPayment(proof)     │

└──────────┬───────────────┘

           │

     ┌─────┴─────┐

     │           │

     ▼           ▼

 Invalid      Valid

 Proof        Proof

  │             │

  ▼             ▼

400 Error   ┌──────────────────┐

            │ Execute Service  │

            │ echo(message)    │

            └─────────┬────────┘

                      ▼

          { echo, timestamp }