npm package: @genesis-tech/x402-hydra-facilitator
Description: x402 Hydra Facilitator Protocol Implementation - Payment verification and settlement for EVM and SVM networks
Latest version: 0.7.2

# @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](https://github.com/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

```bash
# 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

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

## Quick Start

### Basic Usage

```typescript
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

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

## Package Exports

### Main Export

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

### Type Definitions

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

### Facilitator Functions

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

### Payment Schemes

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

### Shared Utilities

```typescript
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:**
```typescript
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:**
```typescript
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

```typescript
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](https://github.com/Hydraprotocol402/Hydra-Facilitator/tree/main/examples) 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

```bash
# 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`](https://www.npmjs.com/package/@genesis-tech/x402-hydra-gateway) - HTTP client for routing to facilitator nodes

## License

Apache-2.0

## Support

- **Issues**: [GitHub Issues](https://github.com/Hydraprotocol402/Hydra-Facilitator/issues)
- **Documentation**: [GitHub Repository](https://github.com/Hydraprotocol402/Hydra-Facilitator)