x402 Python SDK 实战指南基于 httpx 的异步 402 支付请求与 EVM/SVM 双链支持【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文基于 x402 仓库中的官方示例 examples/python/clients/httpx/README.md讲解如何使用 x402 v2 Python SDK 的 httpx 异步客户端访问受 402Payment Required保护的 API 端点。读完后你将能够配置并运行一个支持以太坊EVM与 SolanaSVM两种链上支付的客户端、理解 SDK 在底层 Transport 层自动拦截 402、签名并携带支付头重发的完整机制以及如何从响应头中解析出结算确认Settlement信息。1. 示例定位与目录结构该示例位于examples/python/clients/httpx/是 x402 Python SDK 系列客户端示例之一同目录下还有 requests 同步客户端示例 等。它演示的核心场景是httpx 是异步 HTTP 客户端SDK 为其提供了带支付能力的x402HttpxClient让调用方对 402 协议完全无感。examples/python/clients/httpx/ ├── .env-local # 环境变量模板私钥、服务器地址、端点路径 ├── main.py # 示例主程序 ├── pyproject.toml # uv 项目配置 ├── uv.lock # 依赖锁定文件 └── README.md # 本文对应的原始文档依赖声明见 pyproject.toml要求Python 3.10依赖python-dotenv与x402[httpx,evm,svm]。其中x402通过 uv 的本地路径源以可编辑editable模式指向仓库内的 SDK 源码python/x402因此该示例天然跟随仓库内 SDK 的最新状态[project] name x402-httpx-example requires-python 3.10 dependencies [ python-dotenv1.0.0, x402[httpx,evm,svm], ] [tool.uv.sources] x402 { path ../../../../python/x402, editable true }[httpx,evm,svm]是三个可选依赖组extrahttpx提供异步传输封装evm/svm分别提供两条链的支付机制scheme与签名器。2. 环境准备2.1 配置环境变量仓库提供了模板文件 .env-local复制为.env并填入私钥cp .env-local .env.env-local的默认内容为EVM_PRIVATE_KEY SVM_PRIVATE_KEY RESOURCE_SERVER_URLhttp://localhost:4021 ENDPOINT_PATH/weather变量说明EVM_PRIVATE_KEYEVM 链私钥带或不带0x前缀均可SVM_PRIVATE_KEYSolana 私钥base58 编码RESOURCE_SERVER_URL受 x402 保护的服务器基地址默认模板为http://localhost:4021ENDPOINT_PATH受保护端点的路径默认模板为/weather注意EVM_PRIVATE_KEY与SVM_PRIVATE_KEY至少提供其一。这一点在 main.py 的validate_environment()中得到了代码级印证L22-L49函数依次读取四个环境变量若两个私钥均为空、或服务器地址/端点路径缺失则打印缺失项并以sys.exit(1)终止。2.2 安装依赖并运行# 安装依赖uv 会自动读取 pyproject.toml 中的本地路径源 uv sync # 运行示例 uv run python main.py运行效果客户端向{RESOURCE_SERVER_URL}{ENDPOINT_PATH}发起 GET 请求若服务器返回 402SDK 自动完成支付并返回成功响应同时打印响应状态码、响应体以及从响应头解码出的SettleResponseJSON。3. 完整支付流程main.py 逐段解析main.py 是官方文档“Code Overview”一节的完整可运行版本整体流程分四步。3.1 第一步创建 x402 支付客户端from x402 import x402Client client x402Client()x402Client是 v2 SDK 的异步客户端核心本身不感知 HTTP只负责按网络注册支付机制scheme、在收到 402 时选择合适的机制创建并签名支付载荷payment payload。3.2 第二步注册 EVM 与 SVM 支付机制from eth_account import Account from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client from x402.mechanisms.svm import KeypairSigner from x402.mechanisms.svm.exact.register import register_exact_svm_client # 注册 EVM以太坊系支付 if evm_private_key: account Account.from_key(evm_private_key) register_exact_evm_client(client, EthAccountSigner(account)) print(fInitialized EVM account: {account.address}) # 注册 SVMSolana 系支付 if svm_private_key: svm_signer KeypairSigner.from_base58(svm_private_key) register_exact_svm_client(client, svm_signer) print(fInitialized SVM account: {svm_signer.address})签名器分别来自 python/x402/mechanisms/evm/signers.py 的EthAccountSigner包装eth_account.Account与 python/x402/mechanisms/svm/signers.py 的KeypairSigner从 base58 私钥构造。两个register_*_client帮助函数值得展开。以 EVM 版 register_exact_evm_client 为例其源码显示它一次做了三件事将传入的 signer 经_wrap_if_local_account归一化后构造ExactEvmClientScheme若未指定networks参数则按eip155:*通配符注册 V2 机制——即该客户端可响应任意 EVM 网络如eip155:8453Base、eip155:1主网等的 exact 支付要求若指定了具体网络则逐个注册同时为所有 V1 遗留网络注册ExactEvmSchemeV1保证对旧版 x402 v1 服务器的向后兼容。SVM 版 register_exact_svm_client 结构相同只是 V2 通配符为solana:*且多一个可选参数rpc_url用于指定自定义 RPC 端点。两个函数都支持policies参数注册支付策略并在末尾返回 client 以支持链式调用。3.3 第三步发起请求402 由 SDK 自动处理from x402.http import x402HTTPClient from x402.http.clients import x402HttpxClient http_client x402HTTPClient(client) # 用于事后解析支付响应头 url f{base_url}{endpoint_path} async with x402HttpxClient(client) as http: response await http.get(url) await response.aread() print(fResponse status: {response.status_code}) print(fResponse body: {response.text})对业务代码而言x402HttpxClient就是一个普通的httpx.AsyncClientget/post/...用法不变但返回的永远不是“原始的” 402——拦截、付费、重试全部发生在传输层。其底层实现见第 4 节。3.4 第四步提取支付结算确认try: settle_response http_client.get_payment_settle_response( lambda name: response.headers.get(name) ) print(f\nPayment response: {settle_response.model_dump_json(indent2)}) except ValueError: print(\nNo payment response header found)get_payment_settle_response接收一个“按名称取响应头”的回调内部依次检查PAYMENT-RESPONSEV2与X-PAYMENT-RESPONSEV1两个头将 base64 解码为SettleResponse对象含交易哈希/签名等结算凭据见 python/x402/http/x402_http_client_base.py。若两个头都不存在则抛出ValueError示例中据此优雅降级为“无支付响应头”提示——这对应了请求根本没有经过付费路径的情况例如端点未受保护。4. 底层原理Transport 层的 402 拦截与重发为什么 SDK 选择 Transport 而非 httpx 的事件钩子event hooks这是理解整个异步封装的关键设计决策。httpx 的 request/response 事件钩子无法替换最终返回给调用方的 Response 对象因此 SDK 实现了一个自定义异步传输 x402AsyncTransport它继承httpx.AsyncBaseTransport内部再包装一个默认AsyncHTTPTransport在handle_async_request中拦截并改写响应。源码注释明确写道“Unlike event hooks, transports can control the response returned.”。完整的处理链为透传非 402 响应response.status_code ! 402时原样返回防止无限重试检查请求扩展字段中的RETRY_KEY值为_x402_is_retry。若当前请求已是重试请求仍收到 402例如余额不足、签名被拒直接把 402 交还给调用方不再二次付费解析支付要求调用get_payment_required_response(get_header, body)——优先读PAYMENT-REQUIRED头V2 格式头不存在时回退解析 JSON 响应体中x402Version 1的 V1 格式两者皆无则报ValueError见 x402_http_client_base.py创建并签名支付载荷await self._client.create_payment_payload(payment_required)按网络匹配已注册的 scheme 完成签名编码支付头encode_payment_signature_header根据载荷版本选择头名——V2 用PAYMENT-SIGNATUREV1 用X-PAYMENT值为 base64 编码见 x402_http_client_base.py 与 python/x402/http/utils.py克隆请求并重发拷贝原请求的 method/url/content更新头含Access-Control-Expose-Headers: PAYMENT-RESPONSE,X-PAYMENT-RESPONSE便于跨域场景下前端脚本读取结算头在 extensions 中打上RETRY_KEY标记然后经同一底层 transport 重发返回重试后的响应错误归一化任何处理过程中的异常都被包装为PaymentError抛出调用方可捕获统一处理。对应的测试位于 python/x402/tests/unit/http/clients/test_httpx.py覆盖了 402 拦截、重试标记、异常分支等行为。5. SDK 提供的四种 httpx 接入方式x402HttpxClient本示例采用只是四种官方接入方式之一全部定义在 python/x402/http/clients/httpx.py总览文档见 python/x402/http/clients/README.md接入方式适用场景用法x402HttpxClient最常用继承httpx.AsyncClientasync with x402HttpxClient(client) as http: ...x402_httpx_transport()已有httpx.AsyncClient构造逻辑只替换 transporthttpx.AsyncClient(transportx402_httpx_transport(client))wrapHttpxWithPayment()一行创建带支付的客户端可透传额外 httpx 参数async with wrapHttpxWithPayment(client) as http: ...wrapHttpxWithPaymentFromConfig()不想手动 register用x402ClientConfig声明式配置async with wrapHttpxWithPaymentFromConfig(config) as http: ...其中FromConfig变体基于x402ClientConfigSchemeRegistration声明方案与网络例如注册ExactEvmScheme(signer...)到eip155:8453适合配置驱动的部署形态。两点需要注意同步/异步必须匹配httpx异步必须搭配异步的x402Clientrequests同步则搭配x402ClientSync。混用会抛出TypeError见 clients README 的 “Sync/Async Matching” 一节。x402_httpx_hooks已废弃SDK 保留了该函数仅用于 API 兼容调用时会触发DeprecationWarning并返回空钩子httpx.py原因是 httpx 事件钩子无法改写响应。新代码应使用 transport 方式。6. 运行验证与小结在填好.env至少一个私钥后执行uv run python main.py预期输出依次为初始化信息Initialized EVM account: 0x...或Initialized SVM account: ...、请求 URL、响应状态码与响应体如/weather端点返回的天气文本以及Payment response:后跟SettleResponse的 JSON含链上结算凭据。若服务器端点不受保护或响应中无支付头则输出No payment response header found。总结本示例的技术要点零侵入业务代码只写await http.get(url)402 拦截、方案匹配、载荷签名、头编码、重试全部在 x402AsyncTransport 内闭环完成双链支持通过 register_exact_evm_client / register_exact_svm_client 注册eip155:*/solana:*通配方案并同时兼容 V1 遗留网络可验证的结算用x402HTTPClient.get_payment_settle_response从PAYMENT-RESPONSE头还原结算确认作为交易凭据存档或展示。想进一步深入 SDK 全貌服务器端中间件、facilitator、MCP 集成等可继续阅读 python/x402/README.md 与同目录下的 requests 同步客户端示例。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 x402 Python SDK 实战指南：基于 httpx 的异步 402 支付请求与 EVM/SVM 双链支持
x402 Python SDK 实战指南基于 httpx 的异步 402 支付请求与 EVM/SVM 双链支持【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文基于 x402 仓库中的官方示例 examples/python/clients/httpx/README.md讲解如何使用 x402 v2 Python SDK 的 httpx 异步客户端访问受 402Payment Required保护的 API 端点。读完后你将能够配置并运行一个支持以太坊EVM与 SolanaSVM两种链上支付的客户端、理解 SDK 在底层 Transport 层自动拦截 402、签名并携带支付头重发的完整机制以及如何从响应头中解析出结算确认Settlement信息。1. 示例定位与目录结构该示例位于examples/python/clients/httpx/是 x402 Python SDK 系列客户端示例之一同目录下还有 requests 同步客户端示例 等。它演示的核心场景是httpx 是异步 HTTP 客户端SDK 为其提供了带支付能力的x402HttpxClient让调用方对 402 协议完全无感。examples/python/clients/httpx/ ├── .env-local # 环境变量模板私钥、服务器地址、端点路径 ├── main.py # 示例主程序 ├── pyproject.toml # uv 项目配置 ├── uv.lock # 依赖锁定文件 └── README.md # 本文对应的原始文档依赖声明见 pyproject.toml要求Python 3.10依赖python-dotenv与x402[httpx,evm,svm]。其中x402通过 uv 的本地路径源以可编辑editable模式指向仓库内的 SDK 源码python/x402因此该示例天然跟随仓库内 SDK 的最新状态[project] name x402-httpx-example requires-python 3.10 dependencies [ python-dotenv1.0.0, x402[httpx,evm,svm], ] [tool.uv.sources] x402 { path ../../../../python/x402, editable true }[httpx,evm,svm]是三个可选依赖组extrahttpx提供异步传输封装evm/svm分别提供两条链的支付机制scheme与签名器。2. 环境准备2.1 配置环境变量仓库提供了模板文件 .env-local复制为.env并填入私钥cp .env-local .env.env-local的默认内容为EVM_PRIVATE_KEY SVM_PRIVATE_KEY RESOURCE_SERVER_URLhttp://localhost:4021 ENDPOINT_PATH/weather变量说明EVM_PRIVATE_KEYEVM 链私钥带或不带0x前缀均可SVM_PRIVATE_KEYSolana 私钥base58 编码RESOURCE_SERVER_URL受 x402 保护的服务器基地址默认模板为http://localhost:4021ENDPOINT_PATH受保护端点的路径默认模板为/weather注意EVM_PRIVATE_KEY与SVM_PRIVATE_KEY至少提供其一。这一点在 main.py 的validate_environment()中得到了代码级印证L22-L49函数依次读取四个环境变量若两个私钥均为空、或服务器地址/端点路径缺失则打印缺失项并以sys.exit(1)终止。2.2 安装依赖并运行# 安装依赖uv 会自动读取 pyproject.toml 中的本地路径源 uv sync # 运行示例 uv run python main.py运行效果客户端向{RESOURCE_SERVER_URL}{ENDPOINT_PATH}发起 GET 请求若服务器返回 402SDK 自动完成支付并返回成功响应同时打印响应状态码、响应体以及从响应头解码出的SettleResponseJSON。3. 完整支付流程main.py 逐段解析main.py 是官方文档“Code Overview”一节的完整可运行版本整体流程分四步。3.1 第一步创建 x402 支付客户端from x402 import x402Client client x402Client()x402Client是 v2 SDK 的异步客户端核心本身不感知 HTTP只负责按网络注册支付机制scheme、在收到 402 时选择合适的机制创建并签名支付载荷payment payload。3.2 第二步注册 EVM 与 SVM 支付机制from eth_account import Account from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client from x402.mechanisms.svm import KeypairSigner from x402.mechanisms.svm.exact.register import register_exact_svm_client # 注册 EVM以太坊系支付 if evm_private_key: account Account.from_key(evm_private_key) register_exact_evm_client(client, EthAccountSigner(account)) print(fInitialized EVM account: {account.address}) # 注册 SVMSolana 系支付 if svm_private_key: svm_signer KeypairSigner.from_base58(svm_private_key) register_exact_svm_client(client, svm_signer) print(fInitialized SVM account: {svm_signer.address})签名器分别来自 python/x402/mechanisms/evm/signers.py 的EthAccountSigner包装eth_account.Account与 python/x402/mechanisms/svm/signers.py 的KeypairSigner从 base58 私钥构造。两个register_*_client帮助函数值得展开。以 EVM 版 register_exact_evm_client 为例其源码显示它一次做了三件事将传入的 signer 经_wrap_if_local_account归一化后构造ExactEvmClientScheme若未指定networks参数则按eip155:*通配符注册 V2 机制——即该客户端可响应任意 EVM 网络如eip155:8453Base、eip155:1主网等的 exact 支付要求若指定了具体网络则逐个注册同时为所有 V1 遗留网络注册ExactEvmSchemeV1保证对旧版 x402 v1 服务器的向后兼容。SVM 版 register_exact_svm_client 结构相同只是 V2 通配符为solana:*且多一个可选参数rpc_url用于指定自定义 RPC 端点。两个函数都支持policies参数注册支付策略并在末尾返回 client 以支持链式调用。3.3 第三步发起请求402 由 SDK 自动处理from x402.http import x402HTTPClient from x402.http.clients import x402HttpxClient http_client x402HTTPClient(client) # 用于事后解析支付响应头 url f{base_url}{endpoint_path} async with x402HttpxClient(client) as http: response await http.get(url) await response.aread() print(fResponse status: {response.status_code}) print(fResponse body: {response.text})对业务代码而言x402HttpxClient就是一个普通的httpx.AsyncClientget/post/...用法不变但返回的永远不是“原始的” 402——拦截、付费、重试全部发生在传输层。其底层实现见第 4 节。3.4 第四步提取支付结算确认try: settle_response http_client.get_payment_settle_response( lambda name: response.headers.get(name) ) print(f\nPayment response: {settle_response.model_dump_json(indent2)}) except ValueError: print(\nNo payment response header found)get_payment_settle_response接收一个“按名称取响应头”的回调内部依次检查PAYMENT-RESPONSEV2与X-PAYMENT-RESPONSEV1两个头将 base64 解码为SettleResponse对象含交易哈希/签名等结算凭据见 python/x402/http/x402_http_client_base.py。若两个头都不存在则抛出ValueError示例中据此优雅降级为“无支付响应头”提示——这对应了请求根本没有经过付费路径的情况例如端点未受保护。4. 底层原理Transport 层的 402 拦截与重发为什么 SDK 选择 Transport 而非 httpx 的事件钩子event hooks这是理解整个异步封装的关键设计决策。httpx 的 request/response 事件钩子无法替换最终返回给调用方的 Response 对象因此 SDK 实现了一个自定义异步传输 x402AsyncTransport它继承httpx.AsyncBaseTransport内部再包装一个默认AsyncHTTPTransport在handle_async_request中拦截并改写响应。源码注释明确写道“Unlike event hooks, transports can control the response returned.”。完整的处理链为透传非 402 响应response.status_code ! 402时原样返回防止无限重试检查请求扩展字段中的RETRY_KEY值为_x402_is_retry。若当前请求已是重试请求仍收到 402例如余额不足、签名被拒直接把 402 交还给调用方不再二次付费解析支付要求调用get_payment_required_response(get_header, body)——优先读PAYMENT-REQUIRED头V2 格式头不存在时回退解析 JSON 响应体中x402Version 1的 V1 格式两者皆无则报ValueError见 x402_http_client_base.py创建并签名支付载荷await self._client.create_payment_payload(payment_required)按网络匹配已注册的 scheme 完成签名编码支付头encode_payment_signature_header根据载荷版本选择头名——V2 用PAYMENT-SIGNATUREV1 用X-PAYMENT值为 base64 编码见 x402_http_client_base.py 与 python/x402/http/utils.py克隆请求并重发拷贝原请求的 method/url/content更新头含Access-Control-Expose-Headers: PAYMENT-RESPONSE,X-PAYMENT-RESPONSE便于跨域场景下前端脚本读取结算头在 extensions 中打上RETRY_KEY标记然后经同一底层 transport 重发返回重试后的响应错误归一化任何处理过程中的异常都被包装为PaymentError抛出调用方可捕获统一处理。对应的测试位于 python/x402/tests/unit/http/clients/test_httpx.py覆盖了 402 拦截、重试标记、异常分支等行为。5. SDK 提供的四种 httpx 接入方式x402HttpxClient本示例采用只是四种官方接入方式之一全部定义在 python/x402/http/clients/httpx.py总览文档见 python/x402/http/clients/README.md接入方式适用场景用法x402HttpxClient最常用继承httpx.AsyncClientasync with x402HttpxClient(client) as http: ...x402_httpx_transport()已有httpx.AsyncClient构造逻辑只替换 transporthttpx.AsyncClient(transportx402_httpx_transport(client))wrapHttpxWithPayment()一行创建带支付的客户端可透传额外 httpx 参数async with wrapHttpxWithPayment(client) as http: ...wrapHttpxWithPaymentFromConfig()不想手动 register用x402ClientConfig声明式配置async with wrapHttpxWithPaymentFromConfig(config) as http: ...其中FromConfig变体基于x402ClientConfigSchemeRegistration声明方案与网络例如注册ExactEvmScheme(signer...)到eip155:8453适合配置驱动的部署形态。两点需要注意同步/异步必须匹配httpx异步必须搭配异步的x402Clientrequests同步则搭配x402ClientSync。混用会抛出TypeError见 clients README 的 “Sync/Async Matching” 一节。x402_httpx_hooks已废弃SDK 保留了该函数仅用于 API 兼容调用时会触发DeprecationWarning并返回空钩子httpx.py原因是 httpx 事件钩子无法改写响应。新代码应使用 transport 方式。6. 运行验证与小结在填好.env至少一个私钥后执行uv run python main.py预期输出依次为初始化信息Initialized EVM account: 0x...或Initialized SVM account: ...、请求 URL、响应状态码与响应体如/weather端点返回的天气文本以及Payment response:后跟SettleResponse的 JSON含链上结算凭据。若服务器端点不受保护或响应中无支付头则输出No payment response header found。总结本示例的技术要点零侵入业务代码只写await http.get(url)402 拦截、方案匹配、载荷签名、头编码、重试全部在 x402AsyncTransport 内闭环完成双链支持通过 register_exact_evm_client / register_exact_svm_client 注册eip155:*/solana:*通配方案并同时兼容 V1 遗留网络可验证的结算用x402HTTPClient.get_payment_settle_response从PAYMENT-RESPONSE头还原结算确认作为交易凭据存档或展示。想进一步深入 SDK 全貌服务器端中间件、facilitator、MCP 集成等可继续阅读 python/x402/README.md 与同目录下的 requests 同步客户端示例。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考