x402-avm/core and @x402-avm/avm Reference

@x402-avm/core and @x402-avm/avm Reference

Detailed API reference for the x402-avm TypeScript SDK packages.

Dependencies

{
  "dependencies": {
    "@x402-avm/core": "latest",
    "@x402-avm/avm": "latest",
    "algosdk": "^3.0.0"
  }
}

For browser wallet integration:

{
  "dependencies": {
    "@txnlab/use-wallet": "^4.0.0",
    "@txnlab/use-wallet-react": "^4.0.0"
  }
}

Package Exports: @x402-avm/core

Package Exports: @x402-avm/avm

x402Client

The client automatically handles HTTP 402 responses by creating payment payloads and retrying.

import { x402Client } from "@x402-avm/core/client";

const client = new x402Client({
  schemes: [],  // Populated via registerExactAvmScheme
});

Methods

Lifecycle

1. Client sends request to resource URL
2. Server responds with 402 Payment Required + PaymentRequired body
3. Client selects a matching PaymentRequirements (filtered by policies)
4. Registered scheme creates and signs payment
5. Client retries with X-PAYMENT header containing signed payload

PaymentPolicy

type PaymentPolicy = (
  version: number,
  requirements: PaymentRequirements[],
) => PaymentRequirements[];

Policies receive the full list of PaymentRequirements from the 402 response and return a filtered subset. If the filtered list is empty, the client cannot pay.

x402ResourceServer

Transport-agnostic server that creates 402 responses and processes payments.

import { x402ResourceServer } from "@x402-avm/core/server";

const server = new x402ResourceServer(facilitatorClient);

Methods

x402HTTPResourceServer

Adds HTTP route matching on top of x402ResourceServer.

import { x402HTTPResourceServer } from "@x402-avm/core/server";

const httpServer = new x402HTTPResourceServer(facilitatorClient, { routes });

Methods

Route Configuration

interface RouteConfig {
  path: string;          // Route pattern (supports * wildcard)
  config: ResourceConfig;
  description?: string;
  mimeType?: string;
}

interface ResourceConfig {
  scheme: "exact";
  payTo: string;
  price: {
    asset: string;
    amount: string;
    extra?: { name: string; decimals: number };
  };
  network: string;
  maxTimeoutSeconds: number;
}

HTTPFacilitatorClient

Communicates with a remote facilitator service over HTTP.

import { HTTPFacilitatorClient } from "@x402-avm/core/server";

const client = new HTTPFacilitatorClient({
  url: string;
  headers?: Record<string, string>;
});

Methods

x402Facilitator

Local facilitator that verifies and settles payments directly.

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

const facilitator = new x402Facilitator();

Methods

registerExactAvmScheme

Three variants exist for client, server, and facilitator.

Client Registration

import { registerExactAvmScheme } from "@x402-avm/avm/exact/client";

registerExactAvmScheme(client, {
  signer: ClientAvmSigner;        // Required: signer implementation
  algodConfig?: {                   // Optional: Algod configuration
    algodUrl?: string;
  };
  networks?: string[];              // Optional: restrict to specific networks
  policies?: PaymentPolicy[];       // Optional: payment policies
});

Server Registration

import { registerExactAvmScheme } from "@x402-avm/avm/exact/server";

registerExactAvmScheme(server, {
  networks?: string[];              // Optional: restrict to specific networks
});

// Default: registers for all Algorand networks (algorand:*)
registerExactAvmScheme(server);

Facilitator Registration

import { registerExactAvmScheme } from "@x402-avm/avm/exact/facilitator";

registerExactAvmScheme(facilitator, {
  signer: FacilitatorAvmSigner;    // Required: facilitator signer
  networks: string | string[];      // Required: supported network(s)
});

ClientAvmSigner Interface

interface ClientAvmSigner {
  address: string;
  signTransactions(
    txns: Uint8Array[],
    indexesToSign?: number[],
  ): Promise<(Uint8Array | null)[]>;
}

Compatible with @txnlab/use-wallet's signTransactions function. The indexesToSign parameter allows selective signing in atomic groups (e.g., sign only the payment transaction, leave the fee payer unsigned for the facilitator).

FacilitatorAvmSigner Interface

interface FacilitatorAvmSigner {
  getAddresses(): readonly string[];
  signTransaction(txn: Uint8Array, senderAddress: string): Promise<Uint8Array>;
  getAlgodClient(network: Network): unknown;
  simulateTransactions(txns: Uint8Array[], network: Network): Promise<unknown>;
  sendTransactions(signedTxns: Uint8Array[], network: Network): Promise<string>;
  waitForConfirmation(txId: string, network: Network, waitRounds?: number): Promise<unknown>;
}

Method Details

Type Guard

import { isAvmSignerWallet } from "@x402-avm/avm";

// Returns true if the object has { address: string, signTransactions: Function }
isAvmSignerWallet(wallet): wallet is ClientAvmSigner;

Constants

Network Identifiers

V1/V2 Mapping

USDC Configuration

Algod Endpoints

Transaction Limits

Address Validation

Utility Functions

Address Validation

isValidAlgorandAddress(address: string): boolean

Full validation including format check and algosdk checksum verification.

Amount Conversion

convertToTokenAmount(amount: string, decimals: number): string
convertFromTokenAmount(amount: string, decimals: number): string

Convert between human-readable decimal amounts and atomic integer units.

Transaction Encoding/Decoding

encodeTransaction(txnBytes: Uint8Array): string          // Uint8Array -> base64
decodeTransaction(base64Str: string): Uint8Array          // base64 -> Uint8Array
decodeSignedTransaction(base64Str: string): SignedTransaction
decodeUnsignedTransaction(base64Str: string): Transaction

Network Utilities

getNetworkFromCaip2(caip2: string): "testnet" | "mainnet" | null
isAlgorandNetwork(network: string): boolean    // Recognizes both V1 and CAIP-2
isTestnetNetwork(network: string): boolean
v1ToCaip2(v1Name: string): string
caip2ToV1(caip2: string): string
createAlgodClient(network: string, url?: string, token?: string): Algodv2

Transaction Inspection

getSenderFromTransaction(txnBytes: Uint8Array, isSigned: boolean): string
getTransactionId(txnBytes: Uint8Array): string
hasSignature(txnBytes: Uint8Array): boolean
getGenesisHashFromTransaction(txnBytes: Uint8Array): string
validateGroupId(txnBytesArray: Uint8Array[]): boolean
assignGroupId(txns: Transaction[]): Transaction[]

Type Definitions

PaymentRequirements (V2)

interface PaymentRequirements {
  scheme: "exact";
  network: string;            // CAIP-2 identifier
  maxAmountRequired: string;  // Atomic units as string
  resource: string;           // URL of the resource
  description: string;
  mimeType: string;
  payTo: string;              // Receiver address
  maxTimeoutSeconds: number;
  asset: string;              // ASA ID ("0" for native ALGO)
  outputSchema: unknown;
  extra?: {
    name: string;             // Token name (e.g., "USDC")
    decimals: number;         // Token decimals (e.g., 6)
  };
}

PaymentPayload

interface PaymentPayload {
  x402Version: 2;
  scheme: "exact";
  network: string;
  payload: {
    paymentGroup: string[];   // base64-encoded msgpack transaction bytes
    paymentIndex: number;     // Index of the payment transaction
  };
}

PaymentRequired

interface PaymentRequired {
  x402Version: 2;
  resource: {
    url: string;
    description: string;
    mimeType: string;
  };
  accepts: PaymentRequirements[];
  error: string;
}

Fee Abstraction Flow

Fee abstraction uses Algorand atomic transaction groups and pooled fees:

1. Client creates a 2-transaction atomic group:
   • Transaction 0: USDC/ALGO transfer from client to resource owner (fee = 0)
   • Transaction 1: Self-payment by fee payer address (fee covers both transactions)
2. Client signs only Transaction 0 (their payment)
3. Client sends both transactions in paymentGroup array
4. Facilitator validates the fee payer transaction:
   • Must be a self-payment (from == to)
   • Amount must be 0
   • No rekey, close-to, or other dangerous operations
   • Fee must be within MAX_REASONABLE_FEE
5. Facilitator signs Transaction 1 and submits the atomic group
6. Atomic execution ensures all-or-nothing on-chain

Security Guarantees

• Fee payer transaction validated for safety (no value extraction)
• Atomic group ensures both transactions succeed or both fail
• Maximum fee cap prevents excessive fee draining
• Group ID consistency validated before submission

Environment Variables

Private Key Format

The AVM_PRIVATE_KEY is a Base64-encoded 64-byte key:

• Bytes 0-31: Ed25519 seed (private key)
• Bytes 32-63: Ed25519 public key
• Address derivation: algosdk.encodeAddress(secretKey.slice(32))

Testing

Use Algorand TestNet for development:

1. Get testnet ALGO from the Algorand Dispenser
2. Opt in to USDC TestNet ASA (ID: 10458941)
3. Get testnet USDC from TestNet USDC Dispenser
4. Use ALGORAND_TESTNET_CAIP2 as the network identifier

Import Summary

External Links

• x402-avm Examples Repository
• x402-avm Documentation
• algosdk TypeScript Documentation
• CAIP-2 Specification
• Algorand Atomic Transfers
• @txnlab/use-wallet Documentation