x402-avm Python 包用于 Algorand

x402-avm Python 包提供了 Algorand (AVM) 支付协议支持，通过模块化的额外系统、基于协议的签名者接口和每个组件的异步/同步变体。

先决条件

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

Python 3.10+ 已安装
pip 可用于包安装
理解 x402 协议 – 客户端发送请求，得到 402，创建支付，用支付头重试

核心概念：基于额外的安装

x402-avm 包使用 pip 额外功能来安装您需要的内容。PyPI 上的包名为 x402-avm，但所有导入都使用 from x402...（而不是 from x402_avm...）。

# 最小的 AVM 支持
pip install "x402-avm[avm]"

# 服务器框架
pip install "x402-avm[fastapi,avm]"
pip install "x402-avm[flask,avm]"

# HTTP 客户端
pip install "x402-avm[httpx,avm]"
pip install "x402-avm[requests,avm]"

# 一切
pip install "x402-avm[all]"

核心工作流程：签名者协议模式

关键洞见是 x402 定义了 协议类（结构化类型）用于签名者。您的实现不需要继承 – 它只需要匹配方法。

私钥（环境变量）
        |
        v
签名者实现（满足协议）
        |
        v
register_exact_avm_client(x402_client, signer)
        |
        v
HTTP 客户端（httpx 或 requests）自动处理 402

如何进行

第 1 步：选择您的额外组件

使用案例	安装命令
客户端使用 httpx（异步）	`pip install "x402-avm[httpx,avm]"`
客户端使用 requests（同步）	`pip install "x402-avm[requests,avm]"`
服务器使用 FastAPI（异步）	`pip install "x402-avm[fastapi,avm]"`
服务器使用 Flask（同步）	`pip install "x402-avm[flask,avm]"`
Facilitator 服务	`pip install "x402-avm[fastapi,avm]"` 或 `"x402-avm[flask,avm]"`
全部安装	`pip install "x402-avm[all]"`

第 2 步：理解异步与同步变体

每个核心类都有异步和同步变体。使用错误的变体会在运行时出错。

组件	异步（FastAPI/httpx）	同步（Flask/requests）
x402 客户端	`x402Client`	`x402ClientSync`
资源服务器	`x402ResourceServer`	`x402ResourceServerSync`
Facilitator 客户端	`HTTPFacilitatorClient`	`HTTPFacilitatorClientSync`
HTTP 资源服务器	`x402HTTPResourceServer`	`x402HTTPResourceServerSync`

第 3 步：实现签名者

对于客户端，实现 ClientAvmSigner：

from x402.mechanisms.avm.signer import ClientAvmSigner

# 协议 -- 只需匹配此形状：
class ClientAvmSigner(Protocol):
    @property
    def address(self) -> str: ...
    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: ...

第 4 步：处理 algosdk 编码边界

这是最常见的错误来源。x402 SDK 在方法之间传递 原始 msgpack 字节，但 Python algosdk（v2.11.1）使用 base64 字符串：

操作	Python algosdk 期望/返回
`msgpack_decode(s)`	期望 base64 字符串
`msgpack_encode(obj)`	返回 base64 字符串
`Transaction.sign(key)`	期望 base64 字符串密钥

边界转换：

import base64
from algosdk import encoding

# 原始字节 -> algosdk 对象（DECODE）
b64_string = base64.b64encode(raw_bytes).decode("utf-8")
txn_obj = encoding.msgpack_decode(b64_string)

# algosdk 对象 -> 原始字节（ENCODE）
b64_string = encoding.msgpack_encode(txn_obj)
raw_bytes = base64.b64decode(b64_string)

第 5 步：注册并使用

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

signer = MyClientSigner(os.environ["AVM_PRIVATE_KEY"])
client = x402Client()
register_exact_avm_client(client, signer)
# 现在使用 httpx 或 requests 客户端包装器

重要规则 / 指南

始终使用 base64 边界 – msgpack_decode 期望 base64 字符串，而不是原始字节
匹配异步/同步变体 – FastAPI 使用 x402Client，Flask 使用 x402ClientSync
私钥格式 – AVM_PRIVATE_KEY 是 Base64 编码的 64 字节（32 字节种子 + 32 字节公钥）
地址派生 – encode_address(secret_key[32:]) 从公钥部分提取地址
导入为 x402 – 安装为 x402-avm 但导入为 from x402...
协议类型 – 不需要继承，只需匹配方法签名

常见错误 / 故障排除

错误	原因	解决方案
`TypeError: a bytes-like object is required`	向 `msgpack_decode` 传递了原始字节	首先转换为 base64 字符串：`base64.b64encode(raw).decode()`
`TypeError: expected str, got bytes`	`msgpack_encode` 返回 base64 字符串，而不是字节	使用 `base64.b64decode(result)` 获取原始字节
`Invalid key length: expected 64`	错误的密钥格式	确保 `AVM_PRIVATE_KEY` 是 Base64 编码的 64 字节密钥
`TypeError: x402HTTPAdapter requires sync client`	使用 requests 时使用了 `x402Client`	使用 requests（同步）时使用 `x402ClientSync`
`ImportError: AVM mechanism requires...`	缺少 `py-algorand-sdk`	`pip install "x402-avm[avm]"`
`ModuleNotFoundError: x402_avm`	错误的导入名称	导入为 `from x402...` 而不是 `from x402_avm...`
`Simulation failed: ...`	交易组无效	检查组 ID 分配，费用计算，资产选择

参考资料 / 进一步阅读

REFERENCE.md - 所有 Python 组件的详细 API 参考
EXAMPLES.md - 完整代码示例
x402-avm on PyPI
x402-avm Examples Repository
x402 Algorand Documentation