@x402-iota/facilitator

x402 Facilitator service for payment verification and settlement on IOTA blockchain.

Overview

Centralized service that:

• Verifies x402 payment signatures
• Settles payments on blockchain
• Tracks nonces to prevent replay attacks
• Manages payment state

Installation

npm install @x402-iota/facilitator @x402-iota/core ethers

Quick Start

import { X402Facilitator } from "@x402-iota/facilitator";

const facilitator = new X402Facilitator({
  rpcUrl: "https://json-rpc.evm.testnet.iotaledger.net",
  privateKey: process.env.FACILITATOR_KEY, // For settlement
  network: "iota-evm-testnet",
});

facilitator.start(3001);
console.log("Facilitator running on :3001");

API Endpoints

GET /supported-kinds

Return supported payment schemes.

curl http://localhost:3001/supported-kinds

Response:
{
  "kinds": [
    { "scheme": "exact", "network": "iota-evm-mainnet" },
    { "scheme": "exact", "network": "iota-evm-testnet" }
  ]
}

POST /verify

Verify payment signature.

curl -X POST http://localhost:3001/verify \
  -H "Content-Type: application/json" \
  -d '{
    "x402Version": 1,
    "paymentHeader": "base64...",
    "paymentRequirements": {...}
  }'

Response:
{
  "isValid": true,
  "invalidReason": null
}

POST /settle

Settle payment on blockchain.

curl -X POST http://localhost:3001/settle \
  -H "Content-Type: application/json" \
  -d '{
    "x402Version": 1,
    "paymentHeader": "base64...",
    "paymentRequirements": {...}
  }'

Response:
{
  "success": true,
  "error": null,
  "txHash": "0x...",
  "networkId": "8822"
}

Configuration

interface FacilitatorOptions {
  rpcUrl: string; // IOTA EVM RPC
  privateKey: string; // Facilitator wallet key
  network: Network; // IOTA network
  port?: number; // Port (default: 3001)
  nonceStorage?: Storage; // Custom nonce storage
}

Deployment

Local Testing

# Start facilitator
npm run dev

# In another terminal, test
curl http://localhost:3001/supported-kinds

Production

# Build
npm run build

# Start with environment variables
FACILITATOR_KEY=0x... npm start

Docker

FROM node:18-alpine

WORKDIR /app
COPY . .
RUN npm ci && npm run build

ENV FACILITATOR_KEY=$FACILITATOR_KEY
ENV IOTA_RPC_URL=https://json-rpc.evm.iotaledger.net

EXPOSE 3001
CMD ["npm", "start"]

Environment Variables

# Required
FACILITATOR_KEY=0x...              # Private key for settlements
IOTA_RPC_URL=https://...           # RPC endpoint

# Optional
PORT=3001
NETWORK=iota-evm-mainnet
LOG_LEVEL=info

Nonce Management

Prevent replay attacks:

// Tracks used nonces
const usedNonces = new Set();

// Check nonce before settlement
if (usedNonces.has(nonce)) {
  throw new Error("Nonce already used");
}

usedNonces.add(nonce);

Related Packages

• @x402-iota/core - Core types
• @x402-iota/server-express - Express middleware
• @x402-iota/server-nextjs - Next.js middleware

License

MIT