/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());

// Facilitator
import { x402Facilitator } from "@x402/core/facilitator";
import { ExactAvmScheme } from "@x402/avm/exact/facilitator";
import { toFacilitatorAvmSigner, ALGORAND_TESTNET_CAIP2 } from "@x402/avm";

const avmSigner = toFacilitatorAvmSigner(secretKeyBase64);
const facilitator = new x402Facilitator()
  .register(ALGORAND_TESTNET_CAIP2, new ExactAvmScheme(avmSigner));

The register builder also accepts a glob pattern (e.g. "algorand:*") when you want one scheme to handle all Algorand networks. Use the exported CAIP-2 constants (ALGORAND_TESTNET_CAIP2, ALGORAND_MAINNET_CAIP2) when targeting a single network.

Network identifiers

Always use the ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2 constants from @x402/avm — never hardcode the CAIP-2 string. The value changed in @x402/avm 2.20.0 to the 32-char CAIP-2 reference form (algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe for TestNet, algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k for MainNet); earlier releases used the full base64 genesis hash. The Python x402-avm package (2.0.2) still uses the full genesis hash form, so a TypeScript client/server paired with a Python facilitator (or vice-versa) will not match on network until both sides use the same form. As a mitigation, register with the "algorand:*" glob on the client and server so either form is accepted.

Project setup

Node examples assume ESM ("type": "module" in package.json). Recommended tsconfig.json: "module": "NodeNext", "moduleResolution": "NodeNext", "target": "ES2022", "strict": true, "types": ["node"]. @x402/* packages ship both ESM and CJS builds.

TypeScript algosdk Encoding

TypeScript algosdk works with raw Uint8Array directly — no conversion needed. This matches the @txnlab/use-wallet ecosystem standard. Encoding/decoding to/from base64 happens only at protocol boundaries (PAYMENT-SIGNATURE header serialization).

Reference Guide

Navigate to the appropriate reference based on your task. Each topic has three files:

• {name}.md — Step-by-step implementation guide
• {name}-reference.md — API details and type signatures
• {name}-examples.md — Complete, runnable code samples

Explaining x402 for TypeScript

Understand @x402/* TypeScript package structure, signer interfaces (ClientAvmSigner, FacilitatorAvmSigner), registration patterns, builder patterns, constants, and utilities.

• explain-algorand-x402-typescript.md — Package ecosystem explanation
• explain-algorand-x402-typescript-reference.md — API reference for @x402/* packages
• explain-algorand-x402-typescript-examples.md — TypeScript pattern examples

Building Clients

Build HTTP clients with @x402/fetch or @x402/axios that automatically handle 402 payments. Covers wrapFetchWithPayment, wrapAxiosWithPayment, ClientAvmSigner for browser wallets or Node.js private keys.

• create-typescript-x402-client.md — Client creation guide
• create-typescript-x402-client-reference.md — Fetch/Axios API reference
• create-typescript-x402-client-examples.md — Client code examples

Building Servers

Build payment-protected servers with @x402/express or @x402/hono middleware. Covers route pricing, multi-network support (AVM+EVM+SVM), 402 responses, and dynamic pricing.

• create-typescript-x402-server.md — Server creation guide
• create-typescript-x402-server-reference.md — Express/Hono middleware API reference
• create-typescript-x402-server-examples.md — Server code examples

Building Next.js Apps

Build fullstack Next.js apps with @x402/next payment protection using paymentProxy and withX402. Covers App Router integration, middleware-level protection, and per-endpoint control. Requires Next.js 16.2.6+ and the @x402/paywall peer dependency (npm install @x402/next @x402/paywall).

• create-typescript-x402-nextjs.md — Next.js integration guide
• create-typescript-x402-nextjs-reference.md — Next.js API reference
• create-typescript-x402-nextjs-examples.md — Next.js code examples

Building Facilitators and Bazaar Discovery

Build facilitator services that verify and settle Algorand payments on-chain with @x402/avm. Covers FacilitatorAvmSigner, Express.js facilitator servers, and Bazaar discovery extension for API cataloging (bazaarResourceServerExtension, withBazaar, declare_discovery_extension on servers).

• create-typescript-x402-facilitator.md — Facilitator creation guide (includes Bazaar setup in Step 5)
• create-typescript-x402-facilitator-reference.md — Facilitator + Bazaar API reference
• create-typescript-x402-facilitator-examples.md — Facilitator + Bazaar code examples

Building Paywalls

Build browser paywall UIs with server-side middleware and client-side wallet integration (Pera, Defly, Lute) using @x402/avm. Covers PaywallBuilder, avmPaywall, multi-network paywalls.

• create-typescript-x402-paywall.md — Paywall creation guide
• create-typescript-x402-paywall-reference.md — Paywall API reference
• create-typescript-x402-paywall-examples.md — Paywall code examples

Low-Level SDK Usage

Use @x402/core and @x402/avm packages directly for custom integrations. Covers payment policies, AVM signer interfaces, transaction groups, fee abstraction, and low-level primitives.

• use-typescript-x402-core-avm.md — Core SDK usage guide
• use-typescript-x402-core-avm-reference.md — Core/AVM API reference
• use-typescript-x402-core-avm-examples.md — Core SDK code examples

TypeScript Package Quick Reference

How to Use This Skill

1. Start here to understand which reference you need
2. Read the {name}.md file for step-by-step implementation guidance
3. Consult {name}-reference.md for API details
4. Use {name}-examples.md for complete, runnable code samples