/algorand-x402-python

x402 Python HTTP Client Reference

Detailed API reference for httpx (async) and requests (sync) client integrations in the x402-avm Python package.

httpx APIs

All httpx APIs are in x402.http.clients.httpx. They use x402Client (async).

x402HttpxClient(x402_client, **kwargs)

Convenience class extending httpx.AsyncClient with built-in payment transport.

Returns: httpx.AsyncClient subclass with payment handling.

Usage:

async with x402HttpxClient(x402, timeout=30.0) as client:
    response = await client.get(url)

wrapHttpxWithPayment(x402_client, **httpx_kwargs)

Factory function that creates a new httpx.AsyncClient with payment transport.

Returns: httpx.AsyncClient (standard instance, not subclass).

wrapHttpxWithPaymentFromConfig(config, **httpx_kwargs)

Creates an httpx.AsyncClient from a x402ClientConfig (builds x402Client internally).

Returns: httpx.AsyncClient with payment transport.

x402_httpx_transport(client, transport=None)

Low-level function that returns an x402AsyncTransport for manual httpx.AsyncClient construction.

Returns: x402AsyncTransport (an httpx.AsyncBaseTransport).

x402AsyncTransport

The transport implementation that intercepts 402 responses and handles payments.

Behavior:

1. Sends the original request via the underlying transport
2. If response is 402, parses PaymentRequirements from headers/body
3. Creates payment payload via the registered scheme
4. Retries request with PAYMENT-SIGNATURE header
5. If retry also returns 402, passes through as-is (no infinite loop)

requests APIs

All requests APIs are in x402.http.clients.requests. They use x402ClientSync (sync).

x402_requests(client, **adapter_kwargs)

Creates a new requests.Session with payment adapter pre-configured.

Returns: requests.Session with payment handling for https:// and http://.

wrapRequestsWithPayment(session, client, **adapter_kwargs)

Wraps an existing requests.Session with payment adapter.

Returns: Same requests.Session (mutated in place). Mounts adapter for https:// and http://.

wrapRequestsWithPaymentFromConfig(session, config, **adapter_kwargs)

Wraps a session from a x402ClientConfig (builds x402ClientSync internally).

Returns: Same requests.Session with payment handling.

x402_http_adapter(client, **kwargs)

Low-level function that returns an x402HTTPAdapter for manual session.mount().

Returns: x402HTTPAdapter (a requests.adapters.HTTPAdapter).

x402HTTPAdapter

The adapter implementation that intercepts 402 responses and handles payments.

Runtime check: Raises TypeError if passed an async x402Client instead of x402ClientSync.

Behavior:

1. Sends the original request via the standard HTTPAdapter
2. If response is 402, parses PaymentRequirements from headers/body
3. Creates payment payload synchronously via the registered scheme
4. Clones request with PAYMENT-SIGNATURE header and Payment-Retry: 1 marker
5. Retries request; if retry returns 402, passes through as-is

ClientAvmSigner Implementation

The signer protocol that both httpx and requests clients depend on:

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

Encoding Boundaries

The x402 SDK passes raw msgpack bytes. Python algosdk (v2.11.1) uses base64 strings. The conversion happens inside sign_transactions():

Complete Implementation

import base64
from algosdk import encoding


class AlgorandSigner:
    def __init__(self, secret_key: bytes, address: str):
        self._secret_key = secret_key
        self._address = address

    @property
    def address(self) -> str:
        return self._address

    def sign_transactions(
        self,
        unsigned_txns: list[bytes],
        indexes_to_sign: list[int],
    ) -> list[bytes | None]:
        sk_b64 = base64.b64encode(self._secret_key).decode()
        result: list[bytes | None] = []
        for i, txn_bytes in enumerate(unsigned_txns):
            if i in indexes_to_sign:
                txn = encoding.msgpack_decode(
                    base64.b64encode(txn_bytes).decode()
                )
                signed = txn.sign(sk_b64)
                result.append(
                    base64.b64decode(encoding.msgpack_encode(signed))
                )
            else:
                result.append(None)
        return result

Registration Functions

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

Registers AVM payment scheme on an x402 client (works with both async and sync).

Network Registration Behavior

By default, register_exact_avm_client registers:

• V2: "algorand:*" wildcard (matches any Algorand CAIP-2 network)
• V1: All legacy network names ("algorand-mainnet", "algorand-testnet")

For specific networks:

from x402.mechanisms.avm import ALGORAND_TESTNET_CAIP2

register_exact_avm_client(x402, signer, networks=ALGORAND_TESTNET_CAIP2)

Error Classes

httpx Errors

requests Errors

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

1. The HTTP client sends a GET request to the resource URL
2. If the server returns HTTP 402, the transport/adapter intercepts the response
3. It parses the PaymentRequired data from response headers (V2) or body (V1)
4. The registered ExactAvmScheme creates an atomic transaction group (ASA transfer) and signs it via the signer
5. Payment headers are added to a retry request
6. The server validates payment and returns the resource

Sync vs Async Comparison

pip Install Commands

# httpx (async) + Algorand
pip install "x402-avm[httpx,avm]"

# requests (sync) + Algorand
pip install "x402-avm[requests,avm]"

# Both clients + Algorand
pip install "x402-avm[httpx,requests,avm]"

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

External Resources

• x402-avm on PyPI
• x402-avm Examples Repository
• x402 Algorand Documentation
• httpx Documentation
• requests Documentation
• py-algorand-sdk Documentation
• Coinbase x402 Specification