x402-fuel

MVP: x402 payment protocol for Fuel Network - HTTP-native payments

Overview

x402-fuel enables pay-per-request APIs on Fuel Network. Users sign transactions off-chain, and a facilitator server submits them to the network, without the merchant server having to interact with the blockchain and have to deal with network requirements.

Installation

npm install x402-fuel fuels

Quick Start

import { Wallet, Provider } from 'fuels';
import { wrapFetchWithPayment, createFuelSigner } from 'x402-fuel';

const provider = await Provider.create('https://testnet.fuel.network/v1/graphql');
const wallet = Wallet.fromPrivateKey('your-private-key', provider); // Or browser wallet
const signer = createFuelSigner(wallet);

const paymentFetch = wrapFetchWithPayment(fetch, signer, BigInt(1000000));
const response = await paymentFetch('https://api.example.com/data'); // paid api

How It Works

Architecture

1. Client requests paid resource → Server returns 402 Payment Required with payment details in X-PAYMENT-REQUIRED header
2. Client creates signed transaction → Signs a Fuel transaction transferring tokens to recipient
3. Client retries with X-PAYMENT header → Includes signed transaction in request
4. Server verifies signature → Checks signature validity
5. Server requests settlement → Sends signed transaction to facilitator and waits for confirmation
6. Facilitator submits transaction → Submits to Fuel Network and waits for txn confirmation
7. Facilitator returns settlement response → Returns transaction hash and result to server
8. Server returns content → Client receives 200 OK with paid data and X-PAYMENT-RESPONSE header containing Base64-encoded settlement details

Core Components

Payment Header Creation

The createPaymentHeader() function (src/payment.ts) creates a signed payment:

• Builds a Fuel ScriptTransactionRequest with coin output to recipient
• Assembles transaction with user's wallet as fee payer
• Signs the transaction and extracts witness signature
• Signs a message with sender's wallet to prove intent and prevent tampering
• Returns PaymentHeader with transaction and signatures

Payment Verification

The verifyPaymentHeader() function verifies payments server-side:

• Recreates the signed message from payment data
• Recovers signer address from signature using Signer.recoverAddress()
• Compares with claimed sender address
• Validates timestamp (rejects if >1 hour old or future-dated)

Facilitator Settlement

The facilitator server (facilitator-server/src/index.ts) receives signed transactions and:

• Verifies payment signatures
• Reconstructs transaction request from payment header
• Submits transaction to Fuel Network
• Waits for txn confirmation
• Returns settlement response with transaction hash and result