Nexus Docs

Facilitator

The Nexus Facilitator is the core payment processing engine that handles blockchain transactions, payment verification, and settlement.

It uses your own facilitator server wallet to settle payments and receive funds.

How It Works

Loading

Getting Started

The Nexus Facilitator is available at:

https://nexus-api.thirdweb.com

Authentication

All requests to the Facilitator require authentication using your wallet secret:

headers: {
  "Authorization": "Bearer <YOUR_WALLET_SECRET>"
}

You can obtain your wallet secret from the Nexus Dashboard under your account settings.

Available Endpoints

The Facilitator provides the following endpoints:

  • /verify - Verify a payment without settling it
  • /settle - Verify and settle a payment
  • /list - List all endpoints and their pricing
  • /supported - Get supported chains and tokens

Integration Methods

There are two main ways to integrate the Nexus Facilitator into your API:

Method 1: Using settlePayment() (recommended)

The settlePayment() helper function provides a simple way to verify and settle payments anywhere in your endpoints or middleware.

Installation

npm install @thirdweb-dev/nexus

Usage

import { settlePayment, createFacilitator } from "@thirdweb-dev/nexus";
import { arbitrumSepolia } from "thirdweb/chains";

// Initialize the facilitator with your wallet secret
const facilitator = createFacilitator({
  walletSecret: "<YOUR_WALLET_SECRET>",
});

export async function GET(request: Request) {
  // Extract payment data from the request header
  const paymentData = request.headers.get("x-payment");

  // Verify and settle the payment
  const result = await settlePayment({
    resourceUrl: "https://api.example.com/premium-content",
    method: "GET"
    paymentData,
    network: "137", // or any chain id
    price: "$0.10", // or specific token address and amount
    facilitator, // Pass the configured facilitator
  });

  // Check if payment was successful
  if (result.status === 200) {
    // Payment successful - return premium content
    return Response.json({ data: "premium content" });
  } else {
    // Payment failed - return error response
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}

Parameters

  • resourceUrl: The full URL of your API endpoint that requires payment
  • method: HTTP method (GET, POST, PUT, etc.)
  • paymentData: Payment information from the x-payment request header
  • payTo: Your facilitator wallet address that will settle and receive the payment
  • network: The blockchain network to use (e.g., base-sepolia or eip155:<CHAIN_ID> for any EIP-155 chain)
  • price: Price in USD format (e.g., "$0.10") or custom token amount. Example: 
    { amount: "100000", asset: { address: "0x..." } }
  • facilitator: The configured facilitator instance

Return Value

The settlePayment() function returns an object with:

  • status: HTTP status code (200 for success, 402 for payment required, etc.)
  • responseBody: Response body (error details or payment instructions)
  • responseHeaders: Response headers (including payment challenge headers)

Method 2: Using X402 Middleware Libraries

The Nexus Facilitator is compatible with existing X402 middleware libraries, making it easy to add payments to your API with minimal code changes.

Keep in mind that some chains and tokens are not supported by all middleware libraries.

Supported Middleware

  • x402-hono - For Hono framework
  • x402-express - For Express.js
  • x402-next - For Next.js
  • or any other X402-compatible middleware

Example with x402-hono

import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";
import { nexusFacilitator } from "@thirdweb-dev/nexus";

// Initialize the facilitator
const facilitator = createFacilitator({
  walletSecret: "<YOUR_WALLET_SECRET>",
});

const app = new Hono();

// Add payment middleware to your app
app.use(
  paymentMiddleware(
    "<YOUR_FACILITATOR_WALLET_ADDRESS>", // set the payTo as your facilitator wallet address
    {
      "/api/paywall": {
        price: "$0.01",
        network: "polygon",
        config: {
          description: "Access to paid content",
        },
      },
      "/api/premium": {
        price: "$0.05",
        network: "polygon",
        config: {
          description: "Access to premium features",
        },
      },
    },
    facilitator, // Pass the facilitator to the middleware
  ),
);

// Define your protected routes
app.get("/api/paywall", (c) => {
  return c.json({ message: "This is premium content!" });
});

app.get("/api/premium", (c) => {
  return c.json({ message: "Premium features unlocked!" });
});

export default app;

When to Use the Facilitator

Use the Facilitator when you want to:

  • Integrate payments directly into your existing API code
  • Have full control over payment logic and flow
  • Build custom middleware or authentication layers
  • Implement complex payment conditions or business logic

Use the Nexus Router when you want to:

  • Quickly add payments to existing APIs without code changes
  • Use a hosted solution for payment handling
  • Benefit from automatic request forwarding and caching

Next Steps