skilld
All skills
algorand-devrel avatar

/algorand-x402-python

@a0546cc
by Algorand Developer Relationsalgorand-devrel/algorand-agent-skills33 stars
16

Builds x402 HTTP-native payment applications on Algorand using Python. Covers clients (httpx, requests), servers (FastAPI, Flask), facilitators, Bazaar discovery, and the x402-avm library. Use when implementing x402 payment flows in Python, creating payment-gated APIs, building x402 facilitators, or integrating the x402-avm package.

Ask your Agent

Use this Skill: https://skilld.dev/gh/algorand-devrel/algorand-agent-skills/algorand-x402-python

This session only. Nothing lands on disk.

referencesuse-python-x402-core-avm-reference.md

≈3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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 PAYMENT-SIGNATURE 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

Values as of x402-avm 2.0.2; note the TypeScript @x402/avm package ≥2.20.0 uses the 32-char form algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe — a TS server/client and a Python facilitator (or vice-versa) will not match until x402-avm adopts the same form. Always use the constants in code rather than hardcoding the string.

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[fastapi,avm]"
pip install "x402-avm[flask,avm]"

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

External Resources

Source: SKILL.md on GitHub

Third-party checks

2 warnings16d3 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides documentation and Python code examples for implementing the x402 payment protocol on the Algorand blockchain, using the x402-avm package.

  • Socket16d

    2 alerts: gptAnomaly

  • Snyk16d

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at a0546cc. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 3 weeks ago

README badge

README badge for algorand-devrel/algorand-agent-skills/algorand-x402-python