创建x402 HTTP客户端

在Python中创建使用httpx（异步）或requests（同步）的x402 HTTP客户端，这些客户端可以自动处理Algorand上的402支付。当构建支付API访问费用的Python HTTP客户端、设置自动402支付处理、实现ClientAvmSigner进行支付签名，或在httpx和requests之间选择x402时使用。强烈的触发词包括“创建Python x402客户端”、“带有x402支付的httpx”、“带有Algorand的requests”、“在Python中自动处理402支付”、“wrapHttpxWithPayment”、“wrapRequestsWithPayment”、“x402HttpxClient设置”、“x402_requests设置”、“我如何在Python中使用Algorand支付API访问费？”、“ClientAvmSigner实现”。

先决条件

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

安装了Python 3.10+
一个Algorand私钥 – Base64编码的64字节密钥（设置为AVM_PRIVATE_KEY环境变量）
USDC选择加入 – 支付地址必须在目标网络上选择加入USDC ASA
一个受保护的支付端点 – 一个运行x402中间件的服务器以供测试

核心工作流程：自动402处理

x402 HTTP客户端包装了你的HTTP库的传输层。当收到402响应时，它会自动创建支付并重试。

client.get("https://api.example.com/paid")
      |
      v
HTTP传输发送请求
      |
      v
服务器返回402 + PaymentRequirements
      |
      v
x402传输拦截402
      |
      v
ExactAvmScheme创建原子事务组
      |
      v
ClientAvmSigner签名支付事务
      |
      v
传输用X-PAYMENT头重试
      |
      v
服务器验证，结算，返回200 + 数据

如何进行

第1步：选择异步或同步

库	变体	x402客户端	安装
httpx（异步）	`x402HttpxClient`	`x402Client`	`pip install "x402-avm[httpx,avm]"`
requests（同步）	`x402_requests`	`x402ClientSync`	`pip install "x402-avm[requests,avm]"`

第2步：实现ClientAvmSigner

异步和同步客户端都需要相同的签名实现：

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

第3步：从环境创建签名者

import os
import base64
from algosdk import encoding

avm_private_key = os.environ["AVM_PRIVATE_KEY"]
secret_key = base64.b64decode(avm_private_key)
if len(secret_key) != 64:
    raise ValueError("AVM_PRIVATE_KEY必须是Base64编码的64字节密钥")

avm_address = encoding.encode_address(secret_key[32:])
signer = AlgorandSigner(secret_key, avm_address)

第4步：注册并发出请求

使用httpx（异步）：

import asyncio
from x402 import x402Client
from x402.http.clients.httpx import x402HttpxClient
from x402.mechanisms.avm.exact.register import register_exact_avm_client

async def main():
    x402 = x402Client()
    register_exact_avm_client(x402, signer)

    async with x402HttpxClient(x402) as client:
        response = await client.get("https://api.example.com/paid-resource")
        print(response.status_code)
        print(response.text)

asyncio.run(main())

使用requests（同步）：

from x402 import x402ClientSync
from x402.http.clients.requests import x402_requests
from x402.mechanisms.avm.exact.register import register_exact_avm_client

x402 = x402ClientSync()
register_exact_avm_client(x402, signer)

with x402_requests(x402) as session:
    response = session.get("https://api.example.com/paid-resource")
    print(response.status_code)
    print(response.text)

重要规则/指南

httpx使用x402Client（异步），requests使用x402ClientSync（同步） – 混用会导致TypeError
私钥格式 – AVM_PRIVATE_KEY必须是Base64编码的64字节（32字节种子+32字节公钥）
algosdk编码边界 – msgpack_decode期望base64字符串，msgpack_encode返回base64字符串，sign()期望base64密钥
没有无限重试 – 传输最多重试一次；如果重试仍然返回402，则传递
创建HTTP客户端前注册 – 在包装httpx/requests之前调用register_exact_avm_client
USDC选择加入必需 – 支付地址必须在目标网络上选择加入USDC

替代客户端创建方法

`wrapHttpxWithPayment`（返回标准httpx.AsyncClient）

from x402.http.clients.httpx import wrapHttpxWithPayment

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

`wrapRequestsWithPayment`（包装现有会话）

from x402.http.clients.requests import wrapRequestsWithPayment

session = requests.Session()
session.headers.update({"Authorization": "Bearer token"})
wrapRequestsWithPayment(session, x402)
response = session.get(url)

基于配置的设置

from x402 import x402ClientConfig, SchemeRegistration
from x402.mechanisms.avm.exact import ExactAvmClientScheme

config = x402ClientConfig(
    schemes=[
        SchemeRegistration(
            network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
            client=ExactAvmClientScheme(signer=my_signer),
        ),
    ],
)

常见错误/故障排除

错误	原因	解决方案
`TypeError: x402HTTPAdapter requires sync client`	使用`x402Client`与requests	对requests使用`x402ClientSync`
`PaymentError: Failed to handle payment`	支付创建或编码失败	检查签名设置，私钥，网络注册
`ValueError: AVM_PRIVATE_KEY必须是...`	密钥长度错误	确保密钥是Base64编码的64字节密钥
`ImportError: AVM机制需要...`	未安装`py-algorand-sdk`	`pip install "x402-avm[avm]"`
`ImportError: requests客户端需要...`	未安装`requests`	`pip install "x402-avm[requests]"`
`ImportError: httpx客户端需要...`	未安装`httpx`	`pip install "x402-avm[httpx]"`
重试后返回402	支付无效或协助者拒绝	检查USDC余额，选择加入状态，正确的网络

参考资料/进一步阅读

REFERENCE.md - httpx和requests的详细API参考
EXAMPLES.md - 完整的代码示例
x402-avm示例存储库
x402 Algorand文档