@x402-avm/core

Core implementation of the x402 payment protocol for TypeScript/JavaScript applications. Provides transport-agnostic client, server and facilitator components.

Installation

pnpm install @x402-avm/core

Quick Start

Client Usage

import { x402Client } from "@x402-avm/core/client";
import { x402HTTPClient } from "@x402-avm/core/http";
import { ExactAvmScheme } from "@x402-avm/avm/exact/client";

// Create core client and register payment schemes
const coreClient = new x402Client()
  .register("algorand:*", new ExactAvmScheme(avmSigner));

// Wrap with HTTP client for header encoding/decoding
const client = new x402HTTPClient(coreClient);

// Make a request
const response = await fetch('https://api.example.com/protected');

if (response.status === 402) {
  // Extract payment requirements from response
  const paymentRequired = client.getPaymentRequiredResponse(
    (name) => response.headers.get(name),
    await response.json()
  );
  
  // Create and send payment
  const paymentPayload = await client.createPaymentPayload(paymentRequired);
  
  const paidResponse = await fetch('https://api.example.com/protected', {
    headers: client.encodePaymentSignatureHeader(paymentPayload),
  });
  
  // Get settlement confirmation
  const settlement = client.getPaymentSettleResponse(
    (name) => paidResponse.headers.get(name)
  );
  console.log('Transaction:', settlement.transaction);
}

Server Usage

import { x402ResourceServer, HTTPFacilitatorClient } from "@x402-avm/core/server";
import { x402HTTPResourceServer } from "@x402-avm/core/http";
import { ExactAvmScheme } from "@x402-avm/avm/exact/server";

// Connect to facilitator
const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://facilitator.goplausible.xyz",
});

// Create resource server with payment schemes
const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", new ExactAvmScheme());

// Initialize (fetches supported kinds from facilitator)
await resourceServer.initialize();

// Configure routes with payment requirements
const routes = {
  "GET /api/data": {
    accepts: {
      scheme: "exact",
      network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
      payTo: avmAddress,
      price: "$0.01",
    },
    description: "Premium data access",
    mimeType: "application/json",
  },
};

// Create HTTP server wrapper
const httpServer = new x402HTTPResourceServer(resourceServer, routes);

Facilitator Usage

import { x402Facilitator } from "@x402-avm/core/facilitator";
import { ExactAvmScheme } from "@x402-avm/avm/exact/facilitator";

const facilitator = new x402Facilitator();

// Register Algorand scheme implementation
facilitator.register("algorand:*", new ExactAvmScheme(avmSigner));

// Verify payment
const verifyResult = await facilitator.verify(paymentPayload, paymentRequirements);

if (verifyResult.isValid) {
  // Settle payment
  const settleResult = await facilitator.settle(paymentPayload, paymentRequirements);
  console.log('Transaction:', settleResult.transaction);
}

Route Configuration

Routes use the accepts field to define payment options:

const routes = {
  // Single payment option
  "GET /api/data": {
    accepts: {
      scheme: "exact",
      network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
      payTo: avmAddress,
      price: "$0.01",
    },
    description: "Data endpoint",
    mimeType: "application/json",
  },

  // Multiple payment options (AVM + EVM + SVM)
  "POST /api/*": {
    accepts: [
      {
        scheme: "exact",
        network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
        payTo: avmAddress,
        price: "$0.05",
      },
      {
        scheme: "exact",
        network: "eip155:8453",
        payTo: evmAddress,
        price: "$0.05",
      },
      {
        scheme: "exact",
        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
        payTo: svmAddress,
        price: "$0.05",
      },
    ],
  },
};

Client Configuration

Use fromConfig() for declarative setup:

const client = x402Client.fromConfig({
  schemes: [
    { network: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", client: new ExactAvmScheme(avmSigner) },
    { network: "eip155:8453", client: new ExactEvmScheme(evmSigner) },
    { network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", client: new ExactSvmScheme(svmSigner) },
  ],
  policies: [
    // Filter by max price
    (version, reqs) => reqs.filter(r => BigInt(r.amount) < BigInt("1000000")),
  ],
});

Lifecycle Hooks

Client Hooks

client
  .onBeforePaymentCreation(async (ctx) => {
    console.log('Creating payment for:', ctx.selectedRequirements.network);
    // Return { abort: true, reason: '...' } to cancel
  })
  .onAfterPaymentCreation(async (ctx) => {
    console.log('Payment created:', ctx.paymentPayload);
  })
  .onPaymentCreationFailure(async (ctx) => {
    console.error('Payment failed:', ctx.error);
    // Return { recovered: true, payload: ... } to recover
  });

Server Hooks

resourceServer
  .onBeforeVerify(async (ctx) => { /* ... */ })
  .onAfterVerify(async (ctx) => { /* ... */ })
  .onBeforeSettle(async (ctx) => { /* ... */ })
  .onAfterSettle(async (ctx) => { /* ... */ });

Facilitator Hooks

facilitator
  .onBeforeVerify(async (ctx) => { console.log('Before verify', ctx); })
  .onAfterVerify(async (ctx) => { console.log('After verify', ctx); })
  .onVerifyFailure(async (ctx) => { console.log('Verify failure', ctx); })
  .onBeforeSettle(async (ctx) => { console.log('Before settle', ctx); })
  .onAfterSettle(async (ctx) => { console.log('After settle', ctx); })
  .onSettleFailure(async (ctx) => { console.log('Settle failure', ctx); });

HTTP Headers

v2 Protocol (Current)

| Header | Description | |--------|-------------| | PAYMENT-SIGNATURE | Base64-encoded payment payload | | PAYMENT-REQUIRED | Base64-encoded payment requirements | | PAYMENT-RESPONSE | Base64-encoded settlement response |

v1 Protocol (Legacy)

| Header | Description | |--------|-------------| | X-PAYMENT | Base64-encoded payment payload | | X-PAYMENT-RESPONSE | Base64-encoded settlement response |

Network Pattern Matching

Register handlers for network families using wildcards:

// All Algorand networks
server.register("algorand:*", new ExactAvmScheme());

// Specific network takes precedence
server.register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", new ExactAvmScheme());

Types

type Network = `${string}:${string}`; // e.g., "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="

type PaymentRequirements = {
  scheme: string;
  network: Network;
  asset: string;
  amount: string;
  payTo: string;
  maxTimeoutSeconds: number;
  extra: Record<string, unknown>;
};

type PaymentPayload = {
  x402Version: number;
  resource: ResourceInfo;
  accepted: PaymentRequirements;
  payload: Record<string, unknown>;
  extensions?: Record<string, unknown>;
};

type PaymentRequired = {
  x402Version: number;
  error?: string;
  resource: ResourceInfo;
  accepts: PaymentRequirements[];
  extensions?: Record<string, unknown>;
};

Framework Integration

For framework-specific middleware, use:

• @x402-avm/express - Express.js middleware
• @x402-avm/hono - Hono middleware
• @x402-avm/next - Next.js integration
• @x402-avm/axios - Axios interceptor
• @x402-avm/fetch - Fetch wrapper

Implementation Packages

For blockchain-specific implementations:

• @x402-avm/avm - Algorand blockchain
• @x402-avm/evm - Ethereum and EVM-compatible chains
• @x402-avm/svm - Solana blockchain

Examples

See the examples directory for complete examples.

Contributing

Contributions welcome! See Contributing Guide.