B4
Blocky402

Introduction to Blocky402

Understanding the x402 protocol and Blocky402’s role as an open facilitator

What is x402?

The x402 protocol is an open standard for HTTP-native payments using stablecoins. It extends the HTTP 402 status code (Payment Required) to enable pay-per-request APIs without intermediaries.

Key Protocol Features

  • Protocol-native: Built on standard HTTP status codes
  • Stablecoin payments: USDC, USDT support across chains
  • Trust-minimized: On-chain verification, no custody
  • Cross-chain: Works across multiple blockchain networks
  • No intermediaries: Direct peer-to-peer payments

What is Blocky402?

Blocky402 is an open-source facilitator for the x402 protocol. It provides the infrastructure to verify and settle x402 payments across multiple blockchain networks.

Facilitator Role

A facilitator in the x402 ecosystem:

  • Verifies payment signatures and validity
  • Settles payments on-chain by broadcasting transactions
  • Supports multiple networks and payment schemes
  • Operates independently from other facilitators

Why Use Blocky402?

  1. Open Source: MIT licensed, fully auditable code
  2. Self-Hostable: Run your own instance for maximum control
  3. Multi-Chain: Supports 5+ blockchain networks
  4. Testnet Ready: Fully operational testnet for development
  5. Protocol Compliant: Implements the x402 standard correctly
  6. Independent: Not tied to any single provider

How It Works

1. API Returns 402

When a client requests a paid resource, the API server returns HTTP 402 with payment requirements:

HTTP/1.1 402 Payment Required
WWW-Authenticate: x402 scheme="exact" network="hedera:testnet" ...

2. Client Creates Payment

The client uses an x402 client SDK (@x402/hedera, @x402/evm, or @x402/svm) to sign a v2 PaymentPayload. The example below uses Hedera — the HTTP envelope is identical for every family; only the signer and the inner payload shape change.

import { ExactHederaScheme } from '@x402/hedera/exact/client';
import { createClientHederaSigner, PrivateKey } from '@x402/hedera';
 
const signer = createClientHederaSigner(
  '0.0.7326075',                                       // payer account id
  PrivateKey.fromStringECDSA(walletPrivateKey),
  { network: 'hedera:testnet' },
);
const scheme = new ExactHederaScheme(signer);
const signed = await scheme.createPaymentPayload(2, requirements);
 
const paymentPayload = {
  x402Version: 2,
  scheme: 'exact',
  network: 'hedera:testnet',
  accepted: requirements,
  payload: signed.payload, // { transaction: 'base64-encoded-TransferTransaction' }
};

3. Verify with Blocky402

The client sends the payment to Blocky402 for verification:

const response = await fetch('http://localhost:3002/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    x402Version: 2,
    paymentPayload,
    paymentRequirements: requirements,
  }),
});

4. Settle on Blockchain

If valid, Blocky402 settles the payment on-chain:

const response = await fetch('http://localhost:3002/settle', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    x402Version: 2,
    paymentPayload,
    paymentRequirements: requirements,
  }),
});
// Returns { success, transaction, network, payer, ... }

5. Access Granted

The client retries the original request with the payment proof (paymentPayload as base64 in the X-PAYMENT header per the x402 transport spec):

const xPayment = Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
const data = await fetch('https://api.example.com/data', {
  headers: { 'X-PAYMENT': xPayment },
});

Supported Networks

Testnet (Available Now):

  • Polygon Amoy
  • Solana Devnet
  • Hedera Testnet

These are the networks the hosted testnet facilitator advertises at GET /supported. Additional networks (Base, Arbitrum, Optimism, Avalanche, Ethereum) are implemented and can be enabled when self-hosting.

Mainnet (Coming Soon):

  • Base Mainnet
  • Polygon Mainnet
  • Solana Mainnet
  • Arbitrum Mainnet
  • Optimism Mainnet
  • Avalanche Mainnet
  • Hedera Mainnet

See Networks & Assets for complete network information.

Architecture

Blocky402 runs a single x402 facilitator that registers one exact scheme per network family using the official x402 SDK packages:

  • EVM networks via @x402/evm
  • SVM (Solana) networks via @x402/svm
  • Hedera networks via @x402/hedera

The system automatically routes each request to the right scheme based on the network.

Getting Started

Ready to start? Check out the Quickstart Guide to make your first payment.

For detailed API documentation, see the API Reference.

Learn More