algorand-x402-python

x402 on Algorand - Python

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

Python Quick Start

The x402-avm package on PyPI bundles core protocol, AVM mechanism, HTTP clients, and server middleware. Pick the extras you need:

# AVM only (no HTTP client/server)
pip install "x402-avm[avm]"

# Server middleware (pick one)
pip install "x402-avm[fastapi,avm]"    # FastAPI async
pip install "x402-avm[flask,avm]"      # Flask sync

# HTTP clients (pick one)
pip install "x402-avm[httpx,avm]"      # Async with httpx
pip install "x402-avm[requests,avm]"   # Sync with requests

# Bazaar discovery extension
pip install "x402-avm[extensions,avm]"

# Everything
pip install "x402-avm[all]"

Distribution name is x402-avm but the import root is x402 (not x402_avm).

Warning: Do not install the canonical PyPI x402 package in the same environment as x402-avm — both unpack into the same site-packages/x402 directory, and canonical x402 contains no AVM mechanism. Keep them in separate environments.

Register AVM Scheme

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

# Client
from x402 import x402Client
from x402.mechanisms.avm.exact import ExactAvmScheme

client = x402Client()
client.register("algorand:*", ExactAvmScheme(signer=my_signer))

# Server
from x402.server import x402ResourceServer
from x402.mechanisms.avm.exact import ExactAvmServerScheme

server = x402ResourceServer()
server.register("algorand:*", ExactAvmServerScheme())

# Facilitator
from x402 import x402Facilitator
from x402.mechanisms.avm import ALGORAND_TESTNET_CAIP2
from x402.mechanisms.avm.exact import ExactAvmFacilitatorScheme

facilitator = x402Facilitator()
facilitator.register([ALGORAND_TESTNET_CAIP2], ExactAvmFacilitatorScheme(signer=my_signer))

x402Facilitator.register takes a list of networks, while x402Client.register and x402ResourceServer.register take a single string (glob "algorand:*" is fine there). Passing a bare string to the facilitator silently iterates it into single-character networks.