x402 Algorand (AVM) Reference

x402 Algorand (AVM) Reference

Architecture Overview

x402 is an HTTP-native payment protocol built on the HTTP 402 status code. The Algorand (AVM) implementation is a first-class citizen alongside EVM (Ethereum) and SVM (Solana), providing identical treatment in registration, configuration, and usage patterns.

Component Architecture

                    +-----------------+
                    |    Client       |
                    | (fetch/axios)   |
                    +--------+--------+
                             |
                    HTTP Request + X-PAYMENT header
                             |
                    +--------v--------+
                    | Resource Server |
                    | (express/hono/  |
                    |  next/fastapi/  |
                    |  flask)         |
                    +--------+--------+
                             |
                    HTTP to Facilitator
                             |
                    +--------v--------+
                    |   Facilitator   |
                    | (verify/settle) |
                    +--------+--------+
                             |
                    Algorand Network
                    (simulate/send)

Payment Flow (Detailed)

1. Client requests a protected resource -- receives 402 Payment Required with PaymentRequirements in the response body
2. Client inspects PaymentRequirements: scheme, network, asset, amount, payTo, extra (feePayer, decimals)
3. Client builds an atomic transaction group:
   • Without fee abstraction: single ASA transfer transaction
   • With fee abstraction: 2-transaction group (fee payer + ASA transfer)
4. Client signs its own transactions, encodes all as base64 msgpack strings
5. Client retries the request with X-PAYMENT header containing the payload
6. Resource Server forwards to the Facilitator for verification
7. Facilitator runs verify(): validates structure, decodes transactions, checks security (no rekey, no close-to, no keyreg), validates payment amount/receiver/asset, signs fee payer, simulates on-chain
8. Facilitator runs settle(): re-verifies, signs facilitator transactions, submits atomic group, returns txId
9. Resource Server grants access and returns the protected resource

Security Checks (Facilitator Verify)

The facilitator performs these security checks on every transaction in the group:

• No keyreg (key registration) transactions allowed
• No rekeyTo unless balanced sandwich pattern (A to B then B to A)
• No closeRemainderTo or assetCloseTo fields (prevents account draining)
• Fee payer must be in facilitator-managed addresses
• Fee payer transaction must be pay type, amount=0, no close-to, no rekey
• Fee must not exceed MAX_REASONABLE_FEE (10 Algo / 10,000,000 microAlgos)
• Group size must not exceed 16 transactions
• Group ID must be consistent across all transactions

TypeScript Package Ecosystem

Core and Mechanism Packages

Server Middleware Packages

Client Packages

Extensions and UI Packages

Python Package Ecosystem

The Python SDK is distributed as a single package with extras:

Python Extras

Network Identifiers

CAIP-2 Format (V2 -- Primary)

V1 Format (Legacy -- Still Supported)

Automatic mapping between V1 and V2 formats is available through V1_TO_CAIP2 and CAIP2_TO_V1 dictionaries.

Constants Reference

Environment Variables

Resource Server

Facilitator

Client

SDK (Optional Overrides)

Next.js Reference Site

Private Key Format

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

• Bytes 0-31: Ed25519 seed (private key material)
• Bytes 32-63: Ed25519 public key
• Address derivation: algosdk.encodeAddress(secretKey.slice(32)) (TypeScript) or encode_address(secret_key[32:]) (Python)

Testing

Manual Testing Flow

1. Start a facilitator on port 4020
2. Start a resource server on port 4021 pointing to the facilitator
3. Run a client that hits the resource server
4. Verify: client receives 402, pays, receives 200 with data

Online Facilitator

Use the public GoPlausible facilitator for testing without running your own: https://facilitator.goplausible.xyz

Algorand Testnet

• Algod: https://testnet-api.algonode.cloud
• Indexer: https://testnet-idx.algonode.cloud
• USDC ASA ID: 10458941
• Fund testnet accounts via the Algorand Testnet Dispenser

Design Decisions

Signer Separation

Protocol definitions (interfaces) live in the SDK packages (@x402-avm/avm / x402-avm). Concrete implementations using algosdk live in example code. This keeps the SDK core free of algosdk dependencies and allows any wallet library to provide signers.

Raw Bytes Protocol

The SDK passes raw msgpack bytes (Uint8Array) between methods. This matches the @txnlab/use-wallet ecosystem standard. Encoding/decoding to/from base64 happens only at protocol boundaries (X-PAYMENT header serialization).

TypeScript vs Python algosdk Encoding

• TypeScript algosdk: Works with raw Uint8Array directly -- no conversion needed
• Python algosdk: msgpack_decode() expects base64 strings, msgpack_encode() returns base64 strings. Boundary conversion: msgpack_decode(base64.b64encode(raw_bytes).decode()) / base64.b64decode(msgpack_encode(obj))

External Resources

• GoPlausible x402-avm Documentation
• GoPlausible x402-avm Examples Repository
• Coinbase x402 Protocol
• Coinbase x402 Algorand Spec (Merged)
• Coinbase x402 PR #361
• CAIP-2 Specification
• Algorand Developer Portal
• algosdk TypeScript
• algosdk Python
• @txnlab/use-wallet