使用x402-avm Python核心和AVM机制直接使用x402-avm Python包核心组件和AVM机制来构建Algorand上的自定义支付集成。

先决条件

在使用此技能之前，请确保：

Python 3.10+ 已安装
x402-avm包 可用：pip install "x402-avm[avm]"
了解x402支付流程 —— 客户端发送支付，服务器返回402，协调者验证/结算

核心架构

x402-avm Python SDK有两个层次：

x402-avm 核心                          AVM机制
+----------------------------------+   +----------------------------------+
| x402Client / x402ClientSync      |   | ClientAvmSigner (协议)       |
| x402ResourceServer / ...Sync     |   | FacilitatorAvmSigner (协议)  |
| x402Facilitator / ...Sync        |   | ExactAvmScheme                   |
| schemas, types                   |   | 常量，工具                     |
+----------------------------------+   +----------------------------------+
         |                                        |
         +--- register_exact_avm_* ---------------+

如何进行

第1步：安装包

# 核心 + AVM机制
pip install "x402-avm[avm]"

# 带Web框架
pip install "x402-avm[avm,fastapi]"
pip install "x402-avm[avm,flask]"

第2步：理解签名协议

SDK定义了签名协议（结构化类型 —— 不需要继承）。

ClientAvmSigner —— 为进行支付的客户端：

from x402.mechanisms.avm.signer import ClientAvmSigner

class ClientAvmSigner(Protocol):
    @property
    def address(self) -> str:
        "58字符的Algorand地址。"
        ...

    def sign_transactions(
        self,
        unsigned_txns: list[bytes],
        indexes_to_sign: list[int],
    ) -> list[bytes | None]:
        "签名指定的交易组。"
        ...

FacilitatorAvmSigner —— 为验证/结算支付的协调者：

from x402.mechanisms.avm.signer import FacilitatorAvmSigner

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

第3步：使用常量

from x402.mechanisms.avm.constants import (
    ALGORAND_TESTNET_CAIP2,     # "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="
    ALGORAND_MAINNET_CAIP2,     # "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="
    USDC_TESTNET_ASA_ID,        # 10458941
    USDC_MAINNET_ASA_ID,        # 31566704
    MIN_TXN_FEE,                # 1000
    MAX_GROUP_SIZE,             # 16
    NETWORK_CONFIGS,
)

第4步：使用工具函数

from x402.mechanisms.avm.utils import (
    is_valid_address,
    to_atomic_amount,
    from_atomic_amount,
    decode_transaction_bytes,
    normalize_network,
    get_usdc_asa_id,
)

# 验证地址
is_valid_address("AAAA...")  # True/False

# 转换金额
to_atomic_amount(1.50)     # 1500000
from_atomic_amount(100000) # 0.1

# 解码交易
info = decode_transaction_bytes(raw_txn_bytes)
print(info.type, info.sender, info.fee, info.is_signed)

第5步：注册方案

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

client = x402Client()
register_exact_avm_client(client, signer)

# 现在client.fetch()自动处理402响应
response = await client.fetch("https://api.example.com/paid-resource")

第6步：理解费用抽象

费用抽象使用Algorand的原子交易组和池化费用：

交易0：USDC转账（客户端 -> 资源所有者，费用 = 0）
交易1：自付款（费用支付者 -> 费用支付者，费用覆盖两个交易）

客户端签名交易0，协调者签名交易1
两个交易原子性执行（全部或无）

重要规则/指南

签名者分离 —— 协议定义位于SDK中（signer.py），实现位于示例中。SDK核心中没有algosdk导入。
一级AVM —— AVM被视为与EVM/SVM相同。从不条件性，总是无条件注册。
algosdk编码边界 —— msgpack_decode()期望base64字符串。msgpack_encode()返回base64字符串。SDK协议在方法之间传递原始msgpack字节。在边界处转换。
从SDK导入常量 —— 使用ALGORAND_TESTNET_CAIP2从导入，而不是SDK代码中的硬编码字符串。
原始字节合同 —— x402 SDK在签名者方法之间传递原始msgpack字节。这符合@txnlab/use-wallet生态系统标准。

常见错误/故障排除

错误	原因	解决方案
`ImportError: x402.mechanisms.avm`	缺少`[avm]`额外	使用`pip install "x402-avm[avm]"`安装
`msgpack_decode expects string`	传递原始字节	包装：`base64.b64encode(raw).decode()`
`Invalid address`	错误的地址格式	必须是58字符的Algorand地址
`to_atomic_amount overflow`	值太大	检查小数位（USDC/ALGO为6）
`Network not supported`	未注册的网络	首先使用`register_exact_avm_*`注册

参考资料/进一步阅读

REFERENCE.md —— 所有导出的详细API参考
EXAMPLES.md —— 完整的代码示例
x402-avm AVM文档
示例存储库