algorand-x402-typescript

x402 on Algorand - TypeScript

Build x402 HTTP-native payment applications on Algorand with TypeScript. Use the reference files below for detailed guidance on each component.

TypeScript Quick Start

# Core + AVM mechanism + key/signer helpers from algokit-utils
npm install @x402/core @x402/avm @algorandfoundation/algokit-utils

# Server middleware (pick one)
npm install @x402/express    # Express.js
npm install @x402/hono       # Hono
npm install @x402/next       # Next.js

# HTTP clients (pick one)
npm install @x402/fetch      # Fetch API (re-exports x402Client, wrapFetchWithPayment)
npm install @x402/axios      # Axios   (re-exports x402Client, wrapAxiosWithPayment)

# Optional: only needed for custom/manual signers (e.g., browser wallet flows)
npm install algosdk

Register AVM Scheme

Every component registers the AVM exact scheme unconditionally — no environment variable guards:

Every AVM scheme is the same class — ExactAvmScheme — exported from three subpaths (each implementing a different SchemeNetwork* interface).

// Client (x402Client is also re-exported from @x402/fetch and @x402/axios)
import { x402Client } from "@x402/core/client";
import { ExactAvmScheme } from "@x402/avm/exact/client";
import { toClientAvmSigner, ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

// secretKeyBase64 = base64 of the 64-byte algosdk secret key (seed||pubkey) — NOT a mnemonic
const avmSigner = toClientAvmSigner(secretKeyBase64);
const client = new x402Client()
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme(avmSigner));

// Server (x402ResourceServer is also re-exported from @x402/hono, @x402/express, @x402/next)
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactAvmScheme } from "@x402/avm/exact/server";
import { ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
const server = new x402ResourceServer(facilitatorClient)
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme());