x402-avm TypeScript Reference

x402-avm TypeScript Reference

Package Ecosystem

@x402-avm/core

The core package provides protocol-agnostic base classes and types.

Key Exports:

@x402-avm/avm

The AVM mechanism package provides Algorand-specific signer interfaces, constants, utilities, and scheme registration.

Signer Interfaces:

Registration Functions (from subpaths):

Constants:

Utility Functions:

@x402-avm/express

Express.js middleware for payment-gated routes.

@x402-avm/hono

Hono middleware for payment-gated routes. Same API as Express but returns Hono MiddlewareHandler.

@x402-avm/next

Next.js middleware for payment-gated routes.

@x402-avm/fetch

Fetch API wrapper that automatically handles 402 responses.

@x402-avm/axios

Axios interceptor that automatically handles 402 responses.

@x402-avm/paywall

Browser paywall UI component shown when a user visits a protected route in a browser.

@x402-avm/extensions

Protocol extensions (bazaar marketplace, custom schemes).

ClientAvmSigner Interface (Detailed)

interface ClientAvmSigner {
  /**
   * The 58-character Algorand address of the signer.
   * Used to identify which transactions belong to this signer.
   */
  address: string;

  /**
   * Sign one or more transactions from an atomic group.
   *
   * @param txns - Array of unsigned transactions as raw msgpack Uint8Array bytes.
   *               Each element is a complete unsigned transaction.
   * @param indexesToSign - Optional array of zero-based indexes indicating which
   *                        transactions this signer should sign. If not provided,
   *                        the signer should sign all transactions.
   * @returns Array of the same length as txns. Each element is either:
   *          - Uint8Array: the signed transaction bytes (for indexes that were signed)
   *          - null: for indexes that were not signed (e.g., fee payer txn)
   */
  signTransactions(
    txns: Uint8Array[],
    indexesToSign?: number[],
  ): Promise<(Uint8Array | null)[]>;
}

Compatibility: This interface matches @txnlab/use-wallet's signTransactions function signature, allowing direct bridging from wallet to signer.

FacilitatorAvmSigner Interface (Detailed)

interface FacilitatorAvmSigner {
  /**
   * Get all Algorand addresses this facilitator manages.
   * These are the fee payer addresses used for fee abstraction.
   * Only transactions from these addresses will be signed by the facilitator.
   */
  getAddresses(): readonly string[];

  /**
   * Sign a single unsigned transaction.
   *
   * @param txn - Raw msgpack bytes of the unsigned transaction
   * @param senderAddress - The Algorand address of the transaction sender
   * @returns Raw msgpack bytes of the signed transaction
   */
  signTransaction(txn: Uint8Array, senderAddress: string): Promise<Uint8Array>;

  /**
   * Get an Algod client for the specified network.
   * Used for fetching transaction parameters and other on-chain queries.
   *
   * @param network - CAIP-2 network identifier
   * @returns algosdk.Algodv2 instance (typed as unknown to avoid algosdk dependency in types)
   */
  getAlgodClient(network: Network): unknown;

  /**
   * Simulate a transaction group before submission.
   * Must use allowEmptySignatures: true for unsigned fee payer transactions.
   *
   * @param txns - Array of transaction bytes (mix of signed and unsigned)
   * @param network - CAIP-2 network identifier
   * @returns Simulation result from the Algod API
   */
  simulateTransactions(txns: Uint8Array[], network: Network): Promise<unknown>;

  /**
   * Submit fully signed transactions to the Algorand network.
   * All transactions in the group must be signed at this point.
   *
   * @param signedTxns - Array of signed transaction bytes
   * @param network - CAIP-2 network identifier
   * @returns Transaction ID of the submitted group
   */
  sendTransactions(signedTxns: Uint8Array[], network: Network): Promise<string>;

  /**
   * Wait for a transaction to be confirmed on-chain.
   *
   * @param txId - Transaction ID to wait for
   * @param network - CAIP-2 network identifier
   * @param waitRounds - Number of rounds to wait (default: 4)
   * @returns Confirmation result
   */
  waitForConfirmation(
    txId: string,
    network: Network,
    waitRounds?: number,
  ): Promise<unknown>;
}

Route Configuration Types

// RoutesConfig: maps "METHOD /path" to RouteConfig
type RoutesConfig = Record<string, RouteConfig>;

interface RouteConfig {
  accepts: PaymentOption | PaymentOption[];
  resource?: string;
  description?: string;
  mimeType?: string;
  customPaywallHtml?: string;
  unpaidResponseBody?: (context: any) => { contentType: string; body: any };
  extensions?: Record<string, unknown>;
}

interface PaymentOption {
  scheme: string;          // "exact"
  payTo: string;           // Algorand address (58 chars)
  price: Price;            // "$0.01" or DynamicPrice function
  network: string;         // CAIP-2 identifier
  maxTimeoutSeconds?: number;
  extra?: Record<string, unknown>;
}

Testing Notes

Running a Local Stack

1. Start facilitator on port 4020 with AVM_PRIVATE_KEY env var
2. Start resource server on port 4021 with FACILITATOR_URL=http://localhost:4020
3. Run client with AVM_PRIVATE_KEY and RESOURCE_SERVER_URL=http://localhost:4021

Using the Online Facilitator

Set FACILITATOR_URL=https://facilitator.goplausible.xyz in the resource server to avoid running a local facilitator.

Algorand Testnet Resources

• Fund accounts: Algorand Testnet Dispenser
• Explorer: Allo Explorer Testnet
• Algod: https://testnet-api.algonode.cloud
• USDC ASA ID: 10458941

Design Considerations

Why Signer Separation?

The SDK defines interfaces (ClientAvmSigner, FacilitatorAvmSigner) but never imports algosdk. This means:

• The SDK core has zero algosdk dependency
• Any wallet library can provide signers (Pera, Defly, Kibisis, etc.)
• Server-side code can use algosdk directly
• The @txnlab/use-wallet ecosystem works out of the box

Why Raw Bytes?

The SDK passes Uint8Array between all methods. This:

• Matches @txnlab/use-wallet's signTransactions signature
• Avoids double-encoding/decoding
• Keeps the protocol layer independent of algosdk types
• Base64 encoding only happens at the HTTP boundary (X-PAYMENT header)

Why Unconditional Registration?

AVM scheme registration is never conditional on environment variables. This ensures:

• AVM is always available as a payment option
• No silent failures when env vars are missing
• Parity with EVM and SVM treatment

External Resources

• @x402-avm/core on npm
• @x402-avm/avm on npm
• @x402-avm/express on npm
• @x402-avm/hono on npm
• @x402-avm/next on npm
• @x402-avm/fetch on npm
• @x402-avm/axios on npm
• @x402-avm/paywall on npm
• @x402-avm/extensions on npm
• GoPlausible x402-avm Examples
• GoPlausible x402-avm Documentation
• @txnlab/use-wallet
• algosdk TypeScript