Ӿ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

   Choose an integration path

   Use @x402/core for a high-level resource server SDK, or use the lightweight x402NanoClient to call verify/settle directly with timeouts, typed errors, and a built-in verify-and-settle workflow. Both work — pick what fits your stack.

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

There are two ways to integrate with this facilitator. Choose the approach that fits your architecture.

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
}

import { x402NanoClient } from '@/lib/x402'

const facilitator = new x402NanoClient({
  endpoint: 'https://x402nano.org',
  apiKey: process.env.FACILITATOR_API_KEY, // optional
  authMode: 'x-api-key',
  timeoutMs: 10_000,
  headers: {
    'x-service-name': 'my-agent',
  },
})

import { X402NanoClientError } from '@/lib/x402'

try {
  const result = await facilitator.verifyAndSettle(
    paymentPayload,
    paymentRequirements,
    {
      retries: 1,
      retryDelayMs: 500,
    },
  )

  if (!result.ok) {
    // Payment invalid: result.verify.invalidReason
    return
  }

  // Payment settled — serve protected content
  console.log(result.settle)
} catch (error) {
  if (error instanceof X402NanoClientError) {
    console.error(error.status, error.retryAfter, error.responseBody)
  }
}

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.