/algorand-x402-python

x402-avm Python Package Reference

Detailed reference for the x402-avm Python package covering package structure, extras, async/sync variants, signer protocols, registration functions, constants, utilities, and algosdk encoding.

Package Structure

The package is published on PyPI as x402-avm but all imports use the x402 namespace:

x402/
  __init__.py                  # x402Client, x402ClientSync, x402Facilitator, etc.
  server.py                    # x402ResourceServer, x402ResourceServerSync
  schemas.py                   # AssetAmount, Network, PaymentRequirements, etc.
  http/
    __init__.py                # HTTPFacilitatorClient, HTTPFacilitatorClientSync, PaymentOption, etc.
    types.py                   # RouteConfig, RoutesConfig, FacilitatorConfig
    clients/
      __init__.py              # Lazy imports for httpx/requests
      httpx.py                 # x402HttpxClient, wrapHttpxWithPayment, etc.
      requests.py              # x402_requests, wrapRequestsWithPayment, etc.
    middleware/
      __init__.py              # Lazy imports for fastapi/flask
      fastapi.py               # PaymentMiddlewareASGI, payment_middleware, etc.
      flask.py                 # PaymentMiddleware, payment_middleware, etc.
  mechanisms/
    avm/
      __init__.py              # Re-exports constants
      constants.py             # Network IDs, USDC config, algod URLs
      signer.py                # ClientAvmSigner, FacilitatorAvmSigner Protocols
      utils.py                 # Address validation, encoding, network utils
      exact/
        __init__.py            # ExactAvmClientScheme, ExactAvmServerScheme, etc.
        register.py            # register_exact_avm_client, register_exact_avm_server, etc.
    evm/                       # EVM mechanism (same structure)
    svm/                       # SVM mechanism (same structure)

Extras

Installation examples:

pip install "x402-avm[avm]"
pip install "x402-avm[fastapi,avm]"
pip install "x402-avm[flask,avm]"
pip install "x402-avm[httpx,avm]"
pip install "x402-avm[requests,avm]"
pip install "x402-avm[avm,httpx,requests]"

Async vs Sync Component Table

ClientAvmSigner Protocol

Defined in x402.mechanisms.avm.signer. Structural typing -- no inheritance required.

class ClientAvmSigner(Protocol):
    @property
    def address(self) -> str:
        """58-character Algorand address."""
        ...

    def sign_transactions(
        self,
        unsigned_txns: list[bytes],
        indexes_to_sign: list[int],
    ) -> list[bytes | None]:
        """Sign specified transactions in a group.

        Args:
            unsigned_txns: Raw msgpack-encoded unsigned transactions.
            indexes_to_sign: Indexes this signer should sign.

        Returns:
            Parallel list: signed bytes at signed indexes, None elsewhere.
        """
        ...

Implementation Notes

• unsigned_txns contains raw msgpack bytes, not base64 strings
• Convert at boundary: base64.b64encode(txn_bytes).decode() before msgpack_decode
• Transaction.sign(key) expects base64-encoded private key string
• Convert back: base64.b64decode(msgpack_encode(signed)) to return raw bytes

FacilitatorAvmSigner Protocol

Defined in x402.mechanisms.avm.signer. Required for facilitator services.

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: ...

Implementation Patterns

Registration Functions

register_exact_avm_client(client, signer, networks=None, algod_url=None)

Registers AVM payment scheme on an x402 client.

register_exact_avm_server(server)

Registers AVM scheme on a resource server.

register_exact_avm_facilitator(facilitator, signer, networks)

Registers AVM scheme on a facilitator.

Constants

Defined in x402.mechanisms.avm.constants:

Network Identifiers

USDC Configuration

Algod Endpoints

Transaction Limits

Utility Functions

Defined in x402.mechanisms.avm.utils:

algosdk Encoding Notes (v2.11.1)

The Python algosdk has different encoding conventions than TypeScript algosdk:

Boundary conversions:

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

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

Environment Variables

Private Key Format

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

• First 32 bytes: Ed25519 seed (private key)
• Last 32 bytes: Ed25519 public key
• Address derivation: encoding.encode_address(secret_key[32:])

Payment Flow

Client -> Resource Server -> Facilitator -> Algorand Network
  |          |                  |                |
  | 1. GET   |                  |                |
  |--------->|                  |                |
  | 2. 402   |                  |                |
  |<---------|                  |                |
  | 3. Build |                  |                |
  |   payload|                  |                |
  | 4. GET + |                  |                |
  | PAYMENT- |                  |                |
  | SIGNATURE|                  |                |
  |--------->| 5. verify()      |                |
  |          |----------------->| 6. simulate    |
  |          |                  |--------------->|
  |          |                  |<---------------|
  |          |<-----------------|                |
  |          | 7. settle()      |                |
  |          |----------------->| 8. sign + send |
  |          |                  |--------------->|
  |          |                  |<---------------|
  |          |<-----------------| 9. txId        |
  | 10. 200  |                  |                |
  |<---------|                  |                |

Testing Notes

• Use Algorand TestNet for development with free test ALGO from the Algorand Faucet
• USDC on TestNet uses ASA ID 10458941 -- ensure receiver has opted in
• Simulation (simulate_group) validates transactions without submitting
• Algorand has instant finality -- once confirmed, transactions are permanent
• AlgoNode public endpoints require no authentication token

External Resources

• x402-avm on PyPI
• x402-avm GitHub Repository
• x402-avm Examples
• x402 Algorand Documentation
• Algorand Developer Portal
• py-algorand-sdk Documentation
• Coinbase x402 Specification