x402-avm Python Core and AVM Mechanism Reference

Detailed API reference for the x402-avm Python package core components and AVM mechanism.

tools-only Updated Sep 29, 2026 7 repo stars

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add tools-only/x402-avm-python-core-and-avm-mechanism-reference

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/tools-only/x402-avm-python-core-and-avm-mechanism-reference.svg)](https://skillmd.com/skills/tools-only/x402-avm-python-core-and-avm-mechanism-reference)

Trust & safety

2 of 3 audits passed

Last audited Sep 23, 2026 · commit f5973ba

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

x402-avm Python Core and AVM Mechanism Reference

Detailed API reference for the x402-avm Python package core components and AVM mechanism.

Core Package Exports

Client Components

Export	Import	Description
`x402Client`	`from x402 import x402Client`	Async client that handles 402 responses automatically
`x402ClientSync`	`from x402 import x402ClientSync`	Synchronous variant of x402Client

Server Components

Export	Import	Description
`x402ResourceServer`	`from x402 import x402ResourceServer`	Async resource server with payment middleware
`x402ResourceServerSync`	`from x402 import x402ResourceServerSync`	Synchronous variant

Facilitator Components

Export	Import	Description
`x402Facilitator`	`from x402 import x402Facilitator`	Async facilitator for payment verification and settlement
`x402FacilitatorSync`	`from x402 import x402FacilitatorSync`	Synchronous variant

Schema Types

Export	Import	Description
`PaymentRequirements`	`from x402.schemas import PaymentRequirements`	V2 payment requirements structure
`PaymentPayload`	`from x402.schemas import PaymentPayload`	Payment payload sent in X-PAYMENT header
`Network`	`from x402.schemas import Network`	Network identifier type (CAIP-2 string)

AVM Mechanism Exports

Signer Protocols

Export	Import	Description
`ClientAvmSigner`	`from x402.mechanisms.avm.signer import ClientAvmSigner`	Protocol for client-side transaction signing
`FacilitatorAvmSigner`	`from x402.mechanisms.avm.signer import FacilitatorAvmSigner`	Protocol for facilitator-side operations

Scheme Classes

Export	Import	Description
`ExactAvmScheme`	`from x402.mechanisms.avm.exact import ExactAvmScheme`	Base AVM exact payment scheme
`ExactAvmClientScheme`	`from x402.mechanisms.avm.exact import ExactAvmClientScheme`	Client-specific scheme
`ExactAvmServerScheme`	`from x402.mechanisms.avm.exact import ExactAvmServerScheme`	Server-specific scheme
`ExactAvmFacilitatorScheme`	`from x402.mechanisms.avm.exact import ExactAvmFacilitatorScheme`	Facilitator-specific scheme

Registration Functions

Function	Import	Description
`register_exact_avm_client`	`from x402.mechanisms.avm.exact import register_exact_avm_client`	Register AVM on a client
`register_exact_avm_server`	`from x402.mechanisms.avm.exact import register_exact_avm_server`	Register AVM on a server
`register_exact_avm_facilitator`	`from x402.mechanisms.avm.exact import register_exact_avm_facilitator`	Register AVM on a facilitator

Constants Reference

Network Identifiers

Constant	Value	Import
`ALGORAND_MAINNET_CAIP2`	`"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="`	`from x402.mechanisms.avm.constants import ALGORAND_MAINNET_CAIP2`
`ALGORAND_TESTNET_CAIP2`	`"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="`	`from x402.mechanisms.avm.constants import ALGORAND_TESTNET_CAIP2`
`SUPPORTED_NETWORKS`	`[MAINNET_CAIP2, TESTNET_CAIP2]`	`from x402.mechanisms.avm.constants import SUPPORTED_NETWORKS`

Genesis Hashes

Constant	Value
`MAINNET_GENESIS_HASH`	`"wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="`
`TESTNET_GENESIS_HASH`	`"SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="`

V1 Compatibility

Constant	Value	Description
`V1_NETWORKS`	`["algorand-mainnet", "algorand-testnet"]`	Legacy network names
`V1_TO_V2_NETWORK_MAP`	`{"algorand-mainnet": CAIP2, ...}`	V1 to CAIP-2 mapping
`V2_TO_V1_NETWORK_MAP`	`{CAIP2: "algorand-mainnet", ...}`	CAIP-2 to V1 mapping

USDC Configuration

Constant	Value	Description
`USDC_MAINNET_ASA_ID`	`31566704`	Mainnet USDC ASA ID
`USDC_TESTNET_ASA_ID`	`10458941`	Testnet USDC ASA ID
`DEFAULT_DECIMALS`	`6`	USDC decimal places

Transaction Limits

Constant	Value	Description
`MAX_GROUP_SIZE`	`16`	Maximum transactions in an atomic group
`MIN_TXN_FEE`	`1000`	Minimum transaction fee in microAlgos

Algod Endpoints

Constant	Value	Description
`FALLBACK_ALGOD_MAINNET`	`"https://mainnet-api.algonode.cloud"`	Default mainnet Algod URL
`FALLBACK_ALGOD_TESTNET`	`"https://testnet-api.algonode.cloud"`	Default testnet Algod URL
`MAINNET_ALGOD_URL`	`env ALGOD_MAINNET_URL` or fallback	Resolved mainnet URL
`TESTNET_ALGOD_URL`	`env ALGOD_TESTNET_URL` or fallback	Resolved testnet URL
`MAINNET_INDEXER_URL`	`env` or AlgoNode	Mainnet indexer URL
`TESTNET_INDEXER_URL`	`env` or AlgoNode	Testnet indexer URL

NETWORK_CONFIGS Structure

NETWORK_CONFIGS = {
    ALGORAND_TESTNET_CAIP2: {
        "algod_url": "https://testnet-api.algonode.cloud",
        "indexer_url": "https://testnet-idx.algonode.cloud",
        "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
        "genesis_id": "testnet-v1.0",
        "default_asset": {"asa_id": 10458941, "name": "USDC", "decimals": 6},
    },
    ALGORAND_MAINNET_CAIP2: {
        "algod_url": "https://mainnet-api.algonode.cloud",
        "indexer_url": "https://mainnet-idx.algonode.cloud",
        "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
        "genesis_id": "mainnet-v1.0",
        "default_asset": {"asa_id": 31566704, "name": "USDC", "decimals": 6},
    },
}

Utility Functions Reference

Address Validation

Function	Signature	Description
`is_valid_address`	`(address: str) -> bool`	Validate 58-character Algorand address

Amount Conversion

Function	Signature	Description
`to_atomic_amount`	`(amount: float, decimals: int = 6) -> int`	Convert decimal to atomic units
`from_atomic_amount`	`(amount: int, decimals: int = 6) -> float`	Convert atomic units to decimal

Transaction Encoding/Decoding

Function	Signature	Description
`decode_transaction_bytes`	`(raw_bytes: bytes) -> DecodedTransactionInfo`	Decode raw msgpack transaction
`decode_base64_transaction`	`(b64_str: str) -> DecodedTransactionInfo`	Decode base64-encoded transaction
`decode_payment_group`	`(payment_group: list[str], payment_index: int) -> DecodedGroupInfo`	Decode a full payment group
`encode_transaction_group`	`(raw_bytes_list: list[bytes]) -> list[str]`	Encode transaction list to base64

DecodedTransactionInfo Fields

Field	Type	Description
`type`	`str`	Transaction type: `"pay"`, `"axfer"`, `"appl"`, etc.
`sender`	`str`	Sender Algorand address
`receiver`	`str` or `None`	Receiver address (payments/transfers)
`fee`	`int`	Transaction fee in microAlgos
`is_signed`	`bool`	Whether the transaction is signed
`asset_amount`	`int` or `None`	Asset amount (for asset transfers)
`asset_id`	`int` or `None`	ASA ID (for asset transfers)

DecodedGroupInfo Fields

Field	Type	Description
`transactions`	`list[DecodedTransactionInfo]`	All decoded transactions
`group_id`	`str`	Base64-encoded group ID
`total_fee`	`int`	Sum of all transaction fees
`has_fee_payer`	`bool`	Whether a fee payer transaction is detected
`fee_payer_index`	`int` or `None`	Index of the fee payer transaction

Network Utilities

Function	Signature	Description
`normalize_network`	`(network: str) -> str`	Convert V1 name or CAIP-2 to CAIP-2
`is_valid_network`	`(network: str) -> bool`	Check if network is supported
`get_network_config`	`(network: str) -> dict`	Get full network configuration
`get_usdc_asa_id`	`(network: str) -> int`	Get USDC ASA ID for network
`get_genesis_hash`	`(network: str) -> str`	Get genesis hash for network
`network_from_genesis_hash`	`(hash: str) -> str`	Resolve CAIP-2 from genesis hash

Security Validation

Function	Signature	Description
`validate_no_security_risks`	`(info: DecodedTransactionInfo) -> str or None`	Check for rekey, close-to, blocked types
`validate_fee_payer_transaction`	`(info: DecodedTransactionInfo, expected_fee_payer: str) -> str or None`	Validate fee payer txn structure
`is_blocked_transaction_type`	`(type: str) -> bool`	Check if transaction type is blocked

Encoding Boundary Patterns

The Python algosdk (v2.11.1) uses base64 strings at API boundaries, while the x402 SDK protocol uses raw bytes internally:

Direction	Pattern
Raw bytes to algosdk	`encoding.msgpack_decode(base64.b64encode(raw_bytes).decode("utf-8"))`
algosdk to raw bytes	`base64.b64decode(encoding.msgpack_encode(obj))`
Sign transaction	`txn_obj.sign(base64.b64encode(secret_key).decode())`
Address from key	`encoding.encode_address(secret_key[32:])`

Comparison with TypeScript algosdk

Operation	Python algosdk	TypeScript algosdk
Decode unsigned txn	`msgpack_decode(base64_string)`	`decodeUnsignedTransaction(Uint8Array)`
Encode txn	`msgpack_encode(obj)` returns base64	`txn.toByte()` returns `Uint8Array`
Sign	`txn.sign(base64_key_string)`	`signTransaction(txn, Uint8Array)`

Fee Abstraction Flow

Fee abstraction uses Algorand atomic transaction groups with pooled fees:

Step 1: Create 2-txn atomic group
  Txn 0: USDC transfer (sender -> receiver, fee = 0)
  Txn 1: Self-payment (fee_payer -> fee_payer, fee = 2 * MIN_TXN_FEE)

Step 2: Assign group ID
  gid = calculate_group_id([txn_0, txn_1])
  txn_0.group = gid
  txn_1.group = gid

Step 3: Client signs Txn 0, leaves Txn 1 unsigned
Step 4: Client sends paymentGroup = [signed_txn_0, unsigned_txn_1]
Step 5: Facilitator signs Txn 1, submits atomic group
Step 6: Both execute atomically (all-or-nothing)

Security guarantees:

Fee payer Txn 1 must be a self-payment (receiver == sender) with amount == 0
No rekey, close-to, or other dangerous fields
Fee is capped at a reasonable maximum
Atomic group ensures all-or-nothing execution

Installation

# Core + AVM mechanism
pip install "x402-avm[avm]"

# With web framework
pip install "x402-avm[avm,fastapi]"
pip install "x402-avm[avm,flask]"

# Multi-chain
pip install "x402-avm[all]"

External Resources

---name: x402-avm-python-core-and-avm-mechanism-referencedescription: Detailed API reference for the x402-avm Python package core components and AVM mechanism.---# x402-avm Python Core and AVM Mechanism ReferenceDetailed API reference for the x402-avm Python package core components and AVM mechanism.## Core Package Exports### Client Components| Export | Import | Description ||--------|--------|-------------|| `x402Client` | `from x402 import x402Client` | Async client that handles 402 responses automatically || `x402ClientSync` | `from x402 import x402ClientSync` | Synchronous variant of x402Client |### Server Components| Export | Import | Description ||--------|--------|-------------|| `x402ResourceServer` | `from x402 import x402ResourceServer` | Async resource server with payment middleware || `x402ResourceServerSync` | `from x402 import x402ResourceServerSync` | Synchronous variant |### Facilitator Components| Export | Import | Description ||--------|--------|-------------|| `x402Facilitator` | `from x402 import x402Facilitator` | Async facilitator for payment verification and settlement || `x402FacilitatorSync` | `from x402 import x402FacilitatorSync` | Synchronous variant |### Schema Types| Export | Import | Description ||--------|--------|-------------|| `PaymentRequirements` | `from x402.schemas import PaymentRequirements` | V2 payment requirements structure || `PaymentPayload` | `from x402.schemas import PaymentPayload` | Payment payload sent in X-PAYMENT header || `Network` | `from x402.schemas import Network` | Network identifier type (CAIP-2 string) |---## AVM Mechanism Exports### Signer Protocols| Export | Import | Description ||--------|--------|-------------|| `ClientAvmSigner` | `from x402.mechanisms.avm.signer import ClientAvmSigner` | Protocol for client-side transaction signing || `FacilitatorAvmSigner` | `from x402.mechanisms.avm.signer import FacilitatorAvmSigner` | Protocol for facilitator-side operations |### Scheme Classes| Export | Import | Description ||--------|--------|-------------|| `ExactAvmScheme` | `from x402.mechanisms.avm.exact import ExactAvmScheme` | Base AVM exact payment scheme || `ExactAvmClientScheme` | `from x402.mechanisms.avm.exact import ExactAvmClientScheme` | Client-specific scheme || `ExactAvmServerScheme` | `from x402.mechanisms.avm.exact import ExactAvmServerScheme` | Server-specific scheme || `ExactAvmFacilitatorScheme` | `from x402.mechanisms.avm.exact import ExactAvmFacilitatorScheme` | Facilitator-specific scheme |### Registration Functions| Function | Import | Description ||----------|--------|-------------|| `register_exact_avm_client` | `from x402.mechanisms.avm.exact import register_exact_avm_client` | Register AVM on a client || `register_exact_avm_server` | `from x402.mechanisms.avm.exact import register_exact_avm_server` | Register AVM on a server || `register_exact_avm_facilitator` | `from x402.mechanisms.avm.exact import register_exact_avm_facilitator` | Register AVM on a facilitator |---## Constants Reference### Network Identifiers| Constant | Value | Import ||----------|-------|--------|| `ALGORAND_MAINNET_CAIP2` | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` | `from x402.mechanisms.avm.constants import ALGORAND_MAINNET_CAIP2` || `ALGORAND_TESTNET_CAIP2` | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` | `from x402.mechanisms.avm.constants import ALGORAND_TESTNET_CAIP2` || `SUPPORTED_NETWORKS` | `[MAINNET_CAIP2, TESTNET_CAIP2]` | `from x402.mechanisms.avm.constants import SUPPORTED_NETWORKS` |### Genesis Hashes| Constant | Value ||----------|-------|| `MAINNET_GENESIS_HASH` | `"wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` || `TESTNET_GENESIS_HASH` | `"SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |### V1 Compatibility| Constant | Value | Description ||----------|-------|-------------|| `V1_NETWORKS` | `["algorand-mainnet", "algorand-testnet"]` | Legacy network names || `V1_TO_V2_NETWORK_MAP` | `{"algorand-mainnet": CAIP2, ...}` | V1 to CAIP-2 mapping || `V2_TO_V1_NETWORK_MAP` | `{CAIP2: "algorand-mainnet", ...}` | CAIP-2 to V1 mapping |### USDC Configuration| Constant | Value | Description ||----------|-------|-------------|| `USDC_MAINNET_ASA_ID` | `31566704` | Mainnet USDC ASA ID || `USDC_TESTNET_ASA_ID` | `10458941` | Testnet USDC ASA ID || `DEFAULT_DECIMALS` | `6` | USDC decimal places |### Transaction Limits| Constant | Value | Description ||----------|-------|-------------|| `MAX_GROUP_SIZE` | `16` | Maximum transactions in an atomic group || `MIN_TXN_FEE` | `1000` | Minimum transaction fee in microAlgos |### Algod Endpoints| Constant | Value | Description ||----------|-------|-------------|| `FALLBACK_ALGOD_MAINNET` | `"https://mainnet-api.algonode.cloud"` | Default mainnet Algod URL || `FALLBACK_ALGOD_TESTNET` | `"https://testnet-api.algonode.cloud"` | Default testnet Algod URL || `MAINNET_ALGOD_URL` | `env ALGOD_MAINNET_URL` or fallback | Resolved mainnet URL || `TESTNET_ALGOD_URL` | `env ALGOD_TESTNET_URL` or fallback | Resolved testnet URL || `MAINNET_INDEXER_URL` | `env` or AlgoNode | Mainnet indexer URL || `TESTNET_INDEXER_URL` | `env` or AlgoNode | Testnet indexer URL |### NETWORK_CONFIGS Structure```pythonNETWORK_CONFIGS = { ALGORAND_TESTNET_CAIP2: { "algod_url": "https://testnet-api.algonode.cloud", "indexer_url": "https://testnet-idx.algonode.cloud", "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", "genesis_id": "testnet-v1.0", "default_asset": {"asa_id": 10458941, "name": "USDC", "decimals": 6}, }, ALGORAND_MAINNET_CAIP2: { "algod_url": "https://mainnet-api.algonode.cloud", "indexer_url": "https://mainnet-idx.algonode.cloud", "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=", "genesis_id": "mainnet-v1.0", "default_asset": {"asa_id": 31566704, "name": "USDC", "decimals": 6}, },}```---## Utility Functions Reference### Address Validation| Function | Signature | Description ||----------|-----------|-------------|| `is_valid_address` | `(address: str) -> bool` | Validate 58-character Algorand address |### Amount Conversion| Function | Signature | Description ||----------|-----------|-------------|| `to_atomic_amount` | `(amount: float, decimals: int = 6) -> int` | Convert decimal to atomic units || `from_atomic_amount` | `(amount: int, decimals: int = 6) -> float` | Convert atomic units to decimal |### Transaction Encoding/Decoding| Function | Signature | Description ||----------|-----------|-------------|| `decode_transaction_bytes` | `(raw_bytes: bytes) -> DecodedTransactionInfo` | Decode raw msgpack transaction || `decode_base64_transaction` | `(b64_str: str) -> DecodedTransactionInfo` | Decode base64-encoded transaction || `decode_payment_group` | `(payment_group: list[str], payment_index: int) -> DecodedGroupInfo` | Decode a full payment group || `encode_transaction_group` | `(raw_bytes_list: list[bytes]) -> list[str]` | Encode transaction list to base64 |### DecodedTransactionInfo Fields| Field | Type | Description ||-------|------|-------------|| `type` | `str` | Transaction type: `"pay"`, `"axfer"`, `"appl"`, etc. || `sender` | `str` | Sender Algorand address || `receiver` | `str` or `None` | Receiver address (payments/transfers) || `fee` | `int` | Transaction fee in microAlgos || `is_signed` | `bool` | Whether the transaction is signed || `asset_amount` | `int` or `None` | Asset amount (for asset transfers) || `asset_id` | `int` or `None` | ASA ID (for asset transfers) |### DecodedGroupInfo Fields| Field | Type | Description ||-------|------|-------------|| `transactions` | `list[DecodedTransactionInfo]` | All decoded transactions || `group_id` | `str` | Base64-encoded group ID || `total_fee` | `int` | Sum of all transaction fees || `has_fee_payer` | `bool` | Whether a fee payer transaction is detected || `fee_payer_index` | `int` or `None` | Index of the fee payer transaction |### Network Utilities| Function | Signature | Description ||----------|-----------|-------------|| `normalize_network` | `(network: str) -> str` | Convert V1 name or CAIP-2 to CAIP-2 || `is_valid_network` | `(network: str) -> bool` | Check if network is supported || `get_network_config` | `(network: str) -> dict` | Get full network configuration || `get_usdc_asa_id` | `(network: str) -> int` | Get USDC ASA ID for network || `get_genesis_hash` | `(network: str) -> str` | Get genesis hash for network || `network_from_genesis_hash` | `(hash: str) -> str` | Resolve CAIP-2 from genesis hash |### Security Validation| Function | Signature | Description ||----------|-----------|-------------|| `validate_no_security_risks` | `(info: DecodedTransactionInfo) -> str or None` | Check for rekey, close-to, blocked types || `validate_fee_payer_transaction` | `(info: DecodedTransactionInfo, expected_fee_payer: str) -> str or None` | Validate fee payer txn structure || `is_blocked_transaction_type` | `(type: str) -> bool` | Check if transaction type is blocked |---## Encoding Boundary PatternsThe Python `algosdk` (v2.11.1) uses base64 strings at API boundaries, while the x402 SDK protocol uses raw bytes internally:| Direction | Pattern ||-----------|---------|| Raw bytes to algosdk | `encoding.msgpack_decode(base64.b64encode(raw_bytes).decode("utf-8"))` || algosdk to raw bytes | `base64.b64decode(encoding.msgpack_encode(obj))` || Sign transaction | `txn_obj.sign(base64.b64encode(secret_key).decode())` || Address from key | `encoding.encode_address(secret_key[32:])` |### Comparison with TypeScript algosdk| Operation | Python algosdk | TypeScript algosdk ||-----------|---------------|-------------------|| Decode unsigned txn | `msgpack_decode(base64_string)` | `decodeUnsignedTransaction(Uint8Array)` || Encode txn | `msgpack_encode(obj)` returns base64 | `txn.toByte()` returns `Uint8Array` || Sign | `txn.sign(base64_key_string)` | `signTransaction(txn, Uint8Array)` |---## Fee Abstraction FlowFee abstraction uses Algorand atomic transaction groups with pooled fees:```Step 1: Create 2-txn atomic group Txn 0: USDC transfer (sender -> receiver, fee = 0) Txn 1: Self-payment (fee_payer -> fee_payer, fee = 2 * MIN_TXN_FEE)Step 2: Assign group ID gid = calculate_group_id([txn_0, txn_1]) txn_0.group = gid txn_1.group = gidStep 3: Client signs Txn 0, leaves Txn 1 unsignedStep 4: Client sends paymentGroup = [signed_txn_0, unsigned_txn_1]Step 5: Facilitator signs Txn 1, submits atomic groupStep 6: Both execute atomically (all-or-nothing)```**Security guarantees:**- Fee payer Txn 1 must be a self-payment (receiver == sender) with amount == 0- No rekey, close-to, or other dangerous fields- Fee is capped at a reasonable maximum- Atomic group ensures all-or-nothing execution---## Installation```bash# Core + AVM mechanismpip install "x402-avm[avm]"# With web frameworkpip install "x402-avm[avm,fastapi]"pip install "x402-avm[avm,flask]"# Multi-chainpip install "x402-avm[all]"```---## External Resources- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)- [x402-avm AVM Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)- [algosdk Python SDK](https://py-algorand-sdk.readthedocs.io/)- [Algorand Developer Portal](https://developer.algorand.org/)- [CAIP-2 Chain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)

tools-only/X-Skills/tree/main/development/600-reference_e336e402 commit f5973ba2a8

Frequently asked questions

npx skillmds@latest add tools-only/x402-avm-python-core-and-avm-mechanism-reference