Facinet

JavaScript SDK and CLI tool for the x402 Facilitator Network

Make gasless USDC payments and manage facilitators on the x402 decentralized payment network powered by Avalanche.

Features

• 💳 Make Payments - Gasless USDC transfers via ERC-3009
• 🎲 Random Facilitator Selection - Fair distribution across network
• 🌐 Multi-Platform - Works in browser (MetaMask) and Node.js
• 🚀 Easy Integration - Simple SDK for developers
• 📊 CLI Tool - Command-line interface for payments and management
• 🔐 Secure - Wallet management with encryption
• ⚡ Fast - Built on Avalanche for sub-second finality

Installation

As a Library (SDK)

npm install facinet

As a CLI Tool

npm install -g facinet

SDK Usage

Browser (with MetaMask)

import { Facinet } from 'facinet';

// Initialize SDK
const facinet = new Facinet({
  network: 'avalanche', // or 'ethereum', 'polygon'
});

// Make a payment (MetaMask will prompt for signature)
const result = await facinet.pay({
  amount: '1',                              // Amount in USDC
  recipient: '0xYourMerchantAddress',       // Where you want to receive payment
});

console.log('Payment successful!', result.txHash);
console.log('Processed by:', result.facilitator.name);

Node.js (with Private Key)

import { Facinet } from 'facinet';

// Initialize with private key
const facinet = new Facinet({
  privateKey: process.env.PRIVATE_KEY,
  network: 'avalanche',
});

// Make a payment
const result = await facinet.pay({
  amount: '5',
  recipient: '0xYourMerchantAddress',
});

console.log('Transaction:', result.txHash);

Quick One-Liner

import { Facinet } from 'facinet';

// Quick payment without creating instance
await Facinet.quickPay({
  amount: '1',
  recipient: '0xMerchantAddress',
  privateKey: process.env.PRIVATE_KEY,
});

Get Available Facilitators

const facinet = new Facinet();

// Get all active facilitators
const facilitators = await facinet.getFacilitators();
console.log(`${facilitators.length} active facilitators`);

// Get a random facilitator
const randomFacilitator = await facinet.selectRandomFacilitator();
console.log('Selected:', randomFacilitator.name);

SDK Configuration Options

interface FacinetConfig {
  apiUrl?: string;       // Default: 'https://x402-avalanche-chi.vercel.app'
  privateKey?: string;   // For Node.js (not needed in browser)
  network?: 'avalanche' | 'ethereum' | 'polygon';  // Default: 'avalanche'
  rpcUrl?: string;       // Custom RPC URL (optional)
}

TypeScript Support

Facinet is written in TypeScript and includes full type definitions:

import type {
  FacinetConfig,
  PaymentParams,
  PaymentResult,
  Facilitator
} from 'facinet';

const config: FacinetConfig = {
  network: 'avalanche',
};

const params: PaymentParams = {
  amount: '1',
  recipient: '0x...',
};

React Example

import { useState } from 'react';
import { Facinet } from 'facinet';

function PaymentButton() {
  const [loading, setLoading] = useState(false);
  const [txHash, setTxHash] = useState('');

  const handlePayment = async () => {
    setLoading(true);
    try {
      const facinet = new Facinet({ network: 'avalanche' });

      const result = await facinet.pay({
        amount: '1',
        recipient: '0xYourMerchantAddress',
      });

      setTxHash(result.txHash);
      alert('Payment successful!');
    } catch (error) {
      console.error('Payment failed:', error);
      alert('Payment failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handlePayment} disabled={loading}>
        {loading ? 'Processing...' : 'Pay 1 USDC'}
      </button>
      {txHash && (
        <p>Transaction: <a href={`https://testnet.snowtrace.io/tx/${txHash}`} target="_blank">
          {txHash.slice(0, 10)}...
        </a></p>
      )}
    </div>
  );
}

How SDK Payments Work

1. Initialize SDK - Create Facinet instance with your config
2. Random Facilitator - SDK automatically picks random active facilitator
3. Sign Authorization - User signs ERC-3009 authorization (gasless!)
4. Facilitator Executes - Facilitator submits transaction and pays gas
5. Payment Complete - USDC transferred to YOUR merchant address

Key Point: The recipient you specify in pay() is where YOU receive payment. The SDK automatically handles facilitator selection and gas payment.

CLI Usage

Quick Start

1. Connect Your Wallet

facinet connect

Choose to either:

• Enter your private key (for testing)
• Generate a new wallet

2. Make a Payment

facinet pay --amount 1 --to 0xRecipientAddress

The CLI will automatically:

• Select a random active facilitator
• Sign the payment authorization
• Submit to the facilitator network
• Show transaction details

3. List Active Facilitators

facinet facilitator list

See all active facilitators in the network with their stats.

4. Check Facilitator Status

facinet facilitator status fac_xyz123

View detailed information about a specific facilitator.

Commands

Connection

facinet connect

Connect your wallet to Facinet. Options:

• Enter existing private key
• Generate new wallet

Config is saved to ~/.facinet/config.json

Payment Commands

facinet pay

Make a payment via the x402 facilitator network.

Options:

• -a, --amount <amount> - Payment amount in USDC (default: 1)
• -t, --to <address> - Recipient Ethereum address
• -c, --chain <chain> - Blockchain network (default: avalanche)
• -n, --network <url> - Custom API URL

Examples:

# Pay 1 USDC to recipient
facinet pay --to 0x123...

# Pay custom amount
facinet pay --amount 5 --to 0x456...

# Use custom API endpoint
facinet pay --to 0x789... --network https://my-api.com

Facilitator Commands

facinet facilitator create

Create a new facilitator (requires 1 USDC registration fee).

Options:

• -n, --name <name> - Facilitator name
• -r, --recipient <address> - Payment recipient address
• -u, --url <url> - API URL (default: http://localhost:3000)

Example:

facinet facilitator create --name "MyNode" --recipient 0xABC...

Important: Save the facilitator wallet private key shown after creation!

facinet facilitator list

List all active facilitators in the network.

Options:

• -u, --url <url> - API URL (default: http://localhost:3000)

Example:

facinet facilitator list

facinet facilitator status <id>

Check the status of a specific facilitator.

Arguments:

• <id> - Facilitator ID (e.g., fac_xyz123)

Options:

• -u, --url <url> - API URL

Example:

facinet facilitator status fac_NdIk4EytdaIYHRK1

facinet facilitator balance <id>

Check the AVAX gas balance of a facilitator.

Arguments:

• <id> - Facilitator ID

Options:

• -u, --url <url> - API URL

Example:

facinet facilitator balance fac_NdIk4EytdaIYHRK1

Configuration

Facinet stores configuration in ~/.facinet/config.json:

{
  "privateKey": "0x...",
  "address": "0x...",
  "network": "avalanche-fuji",
  "apiUrl": "http://localhost:3000"
}

Supported Networks

• Avalanche (Fuji Testnet) - Default
• Ethereum (Sepolia Testnet)
• More chains coming soon

How It Works

1. Random Selection - CLI picks a random active facilitator from the network
2. Sign Authorization - You sign an ERC-3009 payment authorization (gasless for you!)
3. Facilitator Executes - The facilitator submits the transaction and pays gas
4. Payment Complete - USDC transferred on-chain, access granted

Development

Build from Source

# Clone repository
git clone https://github.com/your-repo/x402.git
cd x402/packages/facinet

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Test commands
facinet --help

Project Structure

facinet/
├── src/
│   ├── sdk/
│   │   ├── Facinet.ts    # Main SDK class
│   │   └── types.ts      # TypeScript types
│   ├── commands/
│   │   ├── connect.ts    # Wallet connection
│   │   ├── pay.ts        # Payment processing
│   │   └── facilitator.ts # Facilitator management
│   ├── utils/
│   │   ├── config.ts     # Configuration management
│   │   └── api.ts        # API client
│   ├── sdk.ts            # SDK exports
│   └── index.ts          # CLI entry point
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Security

• Private keys are stored encrypted in ~/.facinet/config.json
• Never share your private key or config file
• Use test wallets for testnet development
• Backup your private keys securely

Troubleshooting

"No wallet connected"

Run facinet connect first to set up your wallet.

"No active facilitators available"

The network has no active facilitators. Create one with:

facinet facilitator create

"Insufficient USDC"

You need USDC in your wallet. On testnet:

1. Get AVAX from faucet
2. Swap AVAX → USDC

API connection errors

Check that your API URL is correct:

facinet pay --network https://your-api-url.com

Examples

Complete Payment Flow

# 1. Connect wallet
facinet connect

# 2. List available facilitators
facinet facilitator list

# 3. Make payment
facinet pay --amount 1 --to 0x1234567890123456789012345678901234567890

# Output:
# ✅ Payment processed successfully!
# Facilitator: Xavier
# Amount: 1 USDC
# Recipient: 0x123...

Create and Monitor Facilitator

# 1. Create facilitator
facinet facilitator create --name "MyNode"

# 2. Fund with AVAX (send to facilitator wallet address)
# ...

# 3. Check status
facinet facilitator status fac_abc123

# 4. Monitor balance
facinet facilitator balance fac_abc123

Resources

• x402 Protocol
• Documentation
• Avalanche Docs
• Report Issues

License

MIT © x402 Team

Built with x402 on Avalanche ⚡