@genesis-tech/x402-hydra-facilitator

Payment verification and settlement service for EVM and SVM networks. Zero-custody architecture for blockchain payments in the x402 Hydra payment protocol.

Version: 0.7.0
License: Apache-2.0
Repository: Hydraprotocol402/Hydra-Facilitator

Overview

The facilitator is an optional but recommended service that simplifies payment verification and settlement between clients (buyers) and servers (sellers) in the x402 protocol. Unlike traditional payment processors, the facilitator does not hold funds or act as a custodian. It performs verification and execution of onchain transactions based on signed payloads provided by clients.

Core Responsibilities

1. Verify payments: Confirm that client payment payloads meet server payment requirements
2. Settle payments: Submit validated payments to the blockchain and monitor for confirmation
3. Provide responses: Return verification and settlement results to servers

Features

• ✅ Multi-chain support: Works with EVM and SVM (Solana) networks
• ✅ Payment verification: Validates payment payloads against requirements without requiring blockchain transactions
• ✅ Payment settlement: Submits verified payments to the blockchain and waits for confirmation
• ✅ Type-safe: Full TypeScript support with comprehensive type definitions
• ✅ Scheme-agnostic: Extensible architecture supporting multiple payment schemes (currently "exact")
• ✅ Zero-custody: Never holds funds, only facilitates onchain transactions

Installation

# Using npm
npm install @genesis-tech/x402-hydra-facilitator

# Using pnpm
pnpm add @genesis-tech/x402-hydra-facilitator

# Using yarn
yarn add @genesis-tech/x402-hydra-facilitator

Install Latest from Main Branch

npm install @genesis-tech/x402-hydra-facilitator@next

Quick Start

Basic Usage

import { verify, settle } from "@genesis-tech/x402-hydra-facilitator";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import type { PaymentPayload, PaymentRequirements } from "@genesis-tech/x402-hydra-facilitator/types";

// Create a connected client for EVM networks (read-only for verification)
const client = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

// Payment requirements from the server
const requirements: PaymentRequirements = {
  scheme: "exact",
  network: "base-sepolia",
  amount: "1000000", // 1 USDC (6 decimals)
  asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia
  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
};

// Payment payload from the client (signed)
const payload: PaymentPayload = {
  // ... payment payload with signature
};

// Verify the payment
const verificationResult = await verify(client, payload, requirements);

if (verificationResult.isValid) {
  console.log("Payment is valid. Payer:", verificationResult.payer);
  
  // Settle the payment (requires a signer wallet)
  const signer = createWalletClient({ /* ... */ });
  const settlementResult = await settle(signer, payload, requirements);
  
  if (settlementResult.success) {
    console.log("Payment settled:", settlementResult.transaction);
  }
} else {
  console.error("Payment invalid:", verificationResult.invalidReason);
}

Using Type Definitions

import type {
  PaymentPayload,
  PaymentRequirements,
  VerifyResponse,
  SettleResponse,
  X402Config,
} from "@genesis-tech/x402-hydra-facilitator/types";

Package Exports

Main Export

import { verify, settle } from "@genesis-tech/x402-hydra-facilitator";

Type Definitions

import type {
  PaymentPayload,
  PaymentRequirements,
  VerifyResponse,
  SettleResponse,
  X402Config,
} from "@genesis-tech/x402-hydra-facilitator/types";

Facilitator Functions

import { verify, settle } from "@genesis-tech/x402-hydra-facilitator/facilitator";

Payment Schemes

import { verify as verifyExactEvm, settle as settleExactEvm } from "@genesis-tech/x402-hydra-facilitator/schemes";

Shared Utilities

import { getUsdcChainConfigForChain } from "@genesis-tech/x402-hydra-facilitator/shared/evm";

API Reference

verify(client, payload, requirements, config?)

Verifies a payment payload against payment requirements.

Parameters:

• client: ConnectedClient | Signer - Blockchain client (read-only for EVM, signer for SVM)
• payload: PaymentPayload - Signed payment payload from client
• requirements: PaymentRequirements - Payment requirements from server
• config?: X402Config - Optional configuration (custom RPC URLs, etc.)

Returns: Promise<VerifyResponse>

Example:

const result = await verify(client, payload, requirements);
if (result.isValid) {
  console.log("Valid payment from:", result.payer);
} else {
  console.error("Invalid:", result.invalidReason);
}

settle(signer, payload, requirements, config?)

Settles a verified payment on the blockchain.

Parameters:

• signer: Signer - Signer wallet for blockchain transactions
• payload: PaymentPayload - Verified payment payload
• requirements: PaymentRequirements - Payment requirements
• config?: X402Config - Optional configuration

Returns: Promise<SettleResponse>

Example:

const result = await settle(signer, payload, requirements);
if (result.success) {
  console.log("Transaction:", result.transaction);
  console.log("Network:", result.network);
  console.log("Payer:", result.payer);
} else {
  console.error("Settlement failed:", result.errorReason);
}

Supported Networks

EVM Networks

• base-sepolia - Base Sepolia testnet
• base - Base mainnet
• sepolia - Ethereum Sepolia testnet
• ethereum - Ethereum mainnet
• Additional EVM networks can be added

SVM Networks

• solana-devnet - Solana devnet
• solana-mainnet - Solana mainnet
• Additional SVM networks can be added

Configuration

Custom RPC URLs

import { X402Config } from "@genesis-tech/x402-hydra-facilitator/types";

const config: X402Config = {
  evmConfig: {
    rpcUrl: "https://custom-rpc.example.com",
  },
  svmConfig: {
    rpcUrl: "https://custom-solana-rpc.example.com",
  },
};

const result = await verify(client, payload, requirements, config);

Architecture

The facilitator follows a zero-custody architecture:

1. Client creates a signed payment payload
2. Server requests payment verification from facilitator
3. Facilitator verifies the payload (no blockchain transaction yet)
4. Server requests payment settlement from facilitator
5. Facilitator submits the transaction to blockchain
6. Facilitator waits for confirmation and returns result

The facilitator never holds funds - it only verifies signatures and executes onchain transactions based on signed payloads.

Examples

See the examples directory for complete implementations:

• NestJS Facilitator: Full NestJS service implementation
• Express Service: Example resource server using the facilitator
• Gateway: HTTP client for routing to facilitator nodes

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

# Format code
pnpm format

Related Packages

• @genesis-tech/x402-hydra-gateway - HTTP client for routing to facilitator nodes

License

Apache-2.0

Support

• Issues: GitHub Issues
• Documentation: GitHub Repository