Ӿ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

How payments work

x402 adds a payment layer to standard HTTP requests. Here is the entire life of a Nano payment — five steps, no human in the loop.

1.Client requests a protected resource

GET /premium

A standard HTTP request hits your API endpoint. No payment yet.

2.Server answers 402 Payment Required

402 PAYMENT REQUIRED

The response carries a PAYMENT-REQUIRED header with the payment terms: scheme, price, network, and recipient.

3.Client signs a Nano block

nano:mainnet · 0.001 Ӿ

The client builds a Nano send block for the exact amount, signs it with its private key, and computes proof of work.

4.Client retries with the receipt

PAYMENT-SIGNATURE

The original request is replayed with the signed payment payload in the PAYMENT-SIGNATURE header.

5.Facilitator verifies and settles

/facilitator/verify → /facilitator/settle

Your server forwards the payload to the facilitator, which validates it and broadcasts the block to the Nano network. Once confirmed, the protected content is served.

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "nano:mainnet",
      "asset": "nano",
      "price": "0.001",
      "payTo": "nano_3hxq...e3g9",
      "maxTimeoutSeconds": 300,
      "description": "Access to premium API"
    }
  ]
}

Endpoint reference

Three HTTP endpoints. All accept JSON and return JSON. API keys are optional — see Authentication.

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "nano:mainnet"
    }
  ],
  "extensions": [],
  "signers": {
    "nano:*": []
  }
}

curl https://x402nano.org/facilitator/supported

{
  "paymentPayload": {
    "x402Version": 2,
    "scheme": "exact",
    "network": "nano:mainnet",
    "payload": {
      "signature": "..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "nano:mainnet",
    "asset": "nano",
    "price": "0.001",
    "payTo": "nano_3hx...e3g9",
    "maxTimeoutSeconds": 300
  }
}

{
  "isValid": true,
  "payer": "nano_1q..."
}

curl -X POST https://x402nano.org/facilitator/verify \
  -H "content-type: application/json" \
  -d '{"paymentPayload":{...},"paymentRequirements":{...}}'

{
  "paymentPayload": {
    "x402Version": 2,
    "scheme": "exact",
    "network": "nano:mainnet",
    "payload": {
      "signature": "..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "nano:mainnet",
    "asset": "nano",
    "price": "0.001",
    "payTo": "nano_3hx...e3g9",
    "maxTimeoutSeconds": 300
  }
}

{
  "success": true,
  "transaction": "F2E5F...9C1",
  "network": "nano:mainnet",
  "payer": "nano_1q..."
}

SDKs

Use @x402/next for first-class Next.js integration, 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
)

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

Rate limits

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

Errors

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

{
  "error": "Bad Request",
  "message": "Missing required fields: paymentPayload and paymentRequirements."
}

FAQ