Ӿ402Nano Facilitator

Quick Start

Start accepting Nano payments in minutes. No account required — the facilitator works out of the box.

1. 1

   No signup needed

   The facilitator is permissionless. Start using it immediately — no account, no API key.

2. 2

   Install the SDK

   Use @x402/next for built-in Next.js middleware and route handler support, or @x402/core for manual verify/settle in any server framework.

3. 3

   Verify, settle, serve

   When a client sends a payment signature, forward it to the facilitator for verification and on-chain settlement. Optionally create an account later for usage analytics.

FACILITATOR_URL=https://x402nano.org/facilitator

Payment Flow

The x402 protocol adds a payment layer to standard HTTP requests. Here is the full flow for a Nano payment:

1. 1

   Client requests a protected resource

   The client makes a standard HTTP request to your API endpoint.

2. 2

   Server returns 402 Payment Required

   The response includes a PAYMENT-REQUIRED header containing the Base64-encoded payment requirements: accepted schemes, price, network and the recipient Nano address.

3. 3

   Client signs a Nano block and computes PoW

   The client constructs a Nano send block for the specified amount to the recipient address, signs it with its private key, and generates proof of work.

4. 4

   Client retries with payment signature

   The client retries the original request with the Base64-encoded payment payload in the PAYMENT-SIGNATURE header.

5. 5

   Server verifies and settles via facilitator

   Your server forwards the payment payload to this facilitator. The facilitator validates the signed block and broadcasts it to the Nano network for settlement. The outcome is returned in the PAYMENT-RESPONSE header. Once confirmed, your server serves the protected content.

SDK Reference

Use @x402/next for first-class Next.js integration with middleware and route handler support, or @x402/core for manual verify/settle in any server framework.

npm install @x402/next @x402/core

import { paymentProxy, x402ResourceServer } from '@x402/next'
import { HTTPFacilitatorClient } from '@x402/core/server'

const facilitator = new HTTPFacilitatorClient({
  url: 'https://x402nano.org/facilitator',
})
const server = new x402ResourceServer(facilitator)

export const proxy = paymentProxy(
  {
    '/premium': {
      accepts: {
        scheme: 'exact',
        network: 'nano:mainnet',
        price: '0.001',
        payTo: 'nano_1your_address_here',
      },
      description: 'Access to premium content',
    },
  },
  server,
)

export const config = {
  matcher: ['/premium/:path*'],
}

// app/api/ai-chat/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { withX402 } from '@x402/next'

const handler = async (req: NextRequest) => {
  // Your API logic
  return NextResponse.json({ message: 'Hello from paid API' })
}

export const POST = withX402(
  handler,
  {
    accepts: {
      scheme: 'exact',
      network: 'nano:mainnet',
      price: '0.0001',
      payTo: 'nano_1your_address_here',
    },
    description: 'AI chat completion',
  },
  server, // your configured x402ResourceServer
)

npm install @x402/core

import { HTTPFacilitatorClient } from '@x402/core/server'

const facilitator = new HTTPFacilitatorClient({
  url: 'https://x402nano.org/facilitator'
})

const verifyResult = await facilitator.verify(
  paymentPayload,
  paymentRequirements,
)

if (verifyResult.isValid) {
  const settleResult = await facilitator.settle(paymentPayload, paymentRequirements)
  if (settleResult.success) {
    // Payment settled — serve protected content
  }
} else {
  // Payment invalid: verifyResult.invalidReason
}

// Express example
app.get('/api/data', async (req, res) => {
  const paymentPayload = req.headers['payment-signature']
  if (!paymentPayload) {
    return res.status(402).json(paymentRequirements)
  }

  const { isValid } = await facilitator.verify(paymentPayload, paymentRequirements)
  if (!isValid) return res.status(400).json({ error: 'Invalid payment' })

  const { success } = await facilitator.settle(paymentPayload, paymentRequirements)
  if (!success) return res.status(500).json({ error: 'Settlement failed' })

  res.json({ data: 'premium content' })
})

Authentication

API keys are optional. The facilitator works without authentication. Include an API key to enable usage analytics in your dashboard.

x-api-key: x402n_your_api_key_here

Authorization: Bearer x402n_your_api_key_here

AI Agents

x402 was designed with machine-to-machine payments in mind. An AI agent can autonomously discover, pay for, and consume API endpoints without human intervention.

Rate Limits

To ensure fair usage and protect the network, the following rate limits apply per IP address:

Error Handling

All errors return a consistent JSON format. Check the HTTP status code and message for debugging.