x402-avm Python Package for Algorand

The x402-avm Python package provides Algorand (AVM) payment protocol support through a modular extras system, Protocol-based signer interfaces, and async/sync variants for every component.

Prerequisites

Before using this skill, ensure:

1. Python 3.10+ is installed
2. pip is available for package installation
3. Understanding of x402 protocol — client sends request, gets 402, creates payment, retries with payment header

Core Concept: Extras-Based Installation

The x402-avm package uses pip extras to install only what you need. The package name on PyPI is x402-avm but all imports use from x402... (not from x402_avm...).

# Minimal AVM support
pip install "x402-avm[avm]"

# Server frameworks
pip install "x402-avm[fastapi,avm]"
pip install "x402-avm[flask,avm]"

# HTTP clients
pip install "x402-avm[httpx,avm]"
pip install "x402-avm[requests,avm]"

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

Core Workflow: Signer Protocol Pattern

The key insight is that x402 defines Protocol classes (structural typing) for signers. Your implementation does not need to inherit — it just needs matching methods.

Private Key (env var)
        |
        v
Signer Implementation (satisfies Protocol)
        |
        v
register_exact_avm_client(x402_client, signer)
        |
        v
HTTP Client (httpx or requests) handles 402 automatically

How to Proceed

Step 1: Choose Your Extras

Step 2: Understand Async vs Sync Variants

Every core class has both async and sync variants. Using the wrong variant causes runtime errors.

Step 3: Implement a Signer

For clients, implement ClientAvmSigner:

from x402.mechanisms.avm.signer import ClientAvmSigner

# Protocol -- just match this shape:
class ClientAvmSigner(Protocol):
    @property
    def address(self) -> str: ...
    def sign_transactions(self, unsigned_txns: list[bytes], indexes_to_sign: list[int]) -> list[bytes | None]: ...

For facilitators, implement FacilitatorAvmSigner:

from x402.mechanisms.avm.signer import FacilitatorAvmSigner

# Protocol -- match this shape:
class FacilitatorAvmSigner(Protocol):
    def get_addresses(self) -> list[str]: ...
    def sign_transaction(self, txn_bytes: bytes, fee_payer: str, network: str) -> bytes: ...
    def sign_group(self, group_bytes: list[bytes], fee_payer: str, indexes_to_sign: list[int], network: str) -> list[bytes]: ...
    def simulate_group(self, group_bytes: list[bytes], network: str) -> None: ...
    def send_group(self, group_bytes: list[bytes], network: str) -> str: ...
    def confirm_transaction(self, txid: str, network: str, rounds: int = 4) -> None: ...

Step 4: Handle algosdk Encoding Boundaries

This is the most common source of bugs. The x402 SDK passes raw msgpack bytes between methods, but Python algosdk (v2.11.1) works with base64 strings:

Boundary conversion:

import base64
from algosdk import encoding

# Raw bytes -> algosdk object (DECODE)
b64_string = base64.b64encode(raw_bytes).decode("utf-8")
txn_obj = encoding.msgpack_decode(b64_string)

# algosdk object -> raw bytes (ENCODE)
b64_string = encoding.msgpack_encode(txn_obj)
raw_bytes = base64.b64decode(b64_string)

Step 5: Register and Use

from x402 import x402Client
from x402.mechanisms.avm.exact import register_exact_avm_client

signer = MyClientSigner(os.environ["AVM_PRIVATE_KEY"])
client = x402Client()
register_exact_avm_client(client, signer)
# Now use with httpx or requests client wrappers

Important Rules / Guidelines

1. Always use base64 boundaries — msgpack_decode expects base64 string, not raw bytes
2. Match async/sync variants — FastAPI uses x402Client, Flask uses x402ClientSync
3. Private key format — AVM_PRIVATE_KEY is Base64-encoded 64 bytes (32-byte seed + 32-byte pubkey)
4. Address derivation — encode_address(secret_key[32:]) extracts address from public key portion
5. Import as x402 — install as x402-avm but import as from x402...
6. Protocol typing — no inheritance needed, just match the method signatures

Common Errors / Troubleshooting

References / Further Reading

• REFERENCE.md – Detailed API reference for all Python components
• EXAMPLES.md – Complete code examples
• x402-avm on PyPI
• x402-avm Examples Repository
• x402 Algorand Documentation