x402 Python EVM 支付机制详解Exact 方案、EIP-3009 授权与智能钱包结算【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文基于仓库中的 EVM 机制说明文档 及其对应的 实现源码系统讲解 x402 支付协议在 Python SDK 中面向 EVM 链的 Exact 支付方案如何用ExactEvmClientScheme生成 EIP-3009 签名授权、ExactEvmServerScheme如何解析美元定价并构建付款要求、ExactEvmFacilitatorScheme如何在链上校验签名并完成转账结算以及 ERC-4337/ERC-6492 智能钱包的自动处理机制。读完后你将能够在 Client / Server / Facilitator 三个角色中完整接入 EVM 链稳定币USDC 等的 HTTP 402 支付。一、机制定位Exact 方案与三方角色x402 的 Python EVM 机制x402.mechanisms.evm实现的是Exact支付方案买方签署一份精确金额的转账授权付款金额必须与卖方的PaymentRequirements完全一致exact 即分毫不差。其底层依赖EIP-3009 TransferWithAuthorization标准——支付方用一次签名授权任意方代其在链上执行transferWithAuthorization从而避免买方每次支付都要发送交易、支付 gas。机制由三个对称命名的组件构成源码位于 exact/ 目录角色类源码文件职责Client买方ExactEvmClientSchemeclient.py构建并签署 EIP-3009 付款授权Server卖方ExactEvmServerSchemeserver.py构建付款要求、解析价格Facilitator结算方ExactEvmFacilitatorSchemefacilitator.py校验签名、执行链上转账三者共用同一个scheme exact标识定义于 constants.py 中的SCHEME_EXACT。在 exact/__init__.py 中ExactEvmScheme默认导出为 Client 方案最常用场景而 Server 与 Facilitator 则通过别名ExactEvmServerScheme、ExactEvmFacilitatorScheme单独导出避免混淆。二、安装EVM 机制依赖eth_account与web3作为可选安装项提供uv add x402[evm]从源码看signers.py 在模块导入时即尝试from eth_account import Account ... from web3 import Web3若缺失会抛出带明确提示的ImportError提示安装x402[evm]因此在没有该扩展的安装中导入签名器会直接失败。三、Quick Start三角色接入3.1 客户端签署付款授权from x402 import x402Client from x402.mechanisms.evm.exact import ExactEvmScheme from x402.mechanisms.evm import EthAccountSigner from eth_account import Account account Account.from_key(0x...) signer EthAccountSigner(account) client x402Client() client.register(eip155:*, ExactEvmScheme(signersigner)) payload await client.create_payment_payload(payment_required)要点结合 client.py 源码构造函数签名是ExactEvmScheme(signer)若直接传入eth_account的LocalAccount_wrap_if_local_account()会自动包装成EthAccountSigner所以跳过手工包装也可以。create_payment_payload()内部按requirements.extra[assetTransferMethod]分流值为permit2时走 Permit2 载荷create_permit2_payload否则走标准的 EIP-3009 流程。EIP-3009 流程会随机生成 32 字节 noncecreate_nonce→ 依据requirements.max_timeout_seconds缺省 3600 秒对应 constants.py 的DEFAULT_VALIDITY_PERIOD计算有效时间窗create_validity_window另含 600 秒时钟偏差缓冲DEFAULT_VALIDITY_BUFFER→ 组装ExactEIP3009Authorization→ 通过build_typed_data_for_signing()构造 EIP-712 类型化数据并调用signer.sign_typed_data()完成签名。签名 EIP-712 需要域参数name/version如 USDC 的USD Coin/2。客户端优先从requirements.extra读取若缺失则尝试通过get_asset_info()从本地注册资产中补全再缺失才抛出ValueError(EIP-712 domain parameters (name, version) required in extra)。3.2 服务端构建付款要求from x402 import x402ResourceServer from x402.mechanisms.evm.exact import ExactEvmServerScheme server x402ResourceServer(facilitator_client) server.register(eip155:*, ExactEvmServerScheme())server.py 中的ExactEvmServerScheme提供两个关键能力parse_price(price, network)— 价格解析。price可以是三种形式已是AssetAmount字典含amount键或AssetAmount对象原样返回要求必须带asset地址美元金额字符串/数字如$0.01或1.5先经parse_money_to_decimal()归一化再依次尝试用户注册的自定义解析器链register_money_parser()支持链式注册、按注册顺序尝试返回None则继续下一个最后回落到默认 USDC 转换amount * 10**decimalsBase 上 USDC 为 6 位小数即$0.01→10000原子单位。enhance_payment_requirements()— 付款要求增强。自动完成四件事按NETWORK_CONFIGS填充默认资产地址把带小数点的金额按代币decimals转换为最小单位向extra注入 EIP-712 域参数name/version若资产配置了assetTransferMethod如permit2则一并写入extra供客户端分流。若某网络未配置默认稳定币且用户未显式指定资产会抛出明确错误提示使用register_money_parser或显式AssetAmount。3.3 Facilitator校验与结算from x402 import x402Facilitator from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme from x402.mechanisms.evm import FacilitatorWeb3Signer facilitator x402Facilitator() facilitator.register([eip155:8453, eip155:84532], ExactEvmFacilitatorScheme(signersigner))注意以当前源码为准FacilitatorWeb3Signer的构造参数是private_keyrpc_url见 signers.py L261-L284即signer FacilitatorWeb3Signer( private_key0x..., rpc_urlhttps://sepolia.base.org, )它在初始化时会为 Base、Polygon 等 PoA 链注入ExtraDataToPOAMiddleware并缓存chain_id。Facilitator 方案支持一个可选配置类ExactEvmSchemeConfigfacilitator.py L46-L54配置项默认值作用deploy_erc4337_with_eip6492False允许在 settle 时通过 ERC-6492 工厂自动部署未部署的 ERC-4337 智能钱包simulate_in_settleFalse在 settle 阶段重跑一次转账模拟verify 阶段默认已模拟3.4 注册辅助函数register.py 提供三个一站式注册函数均同时注册 V2eip155:*或指定网络与 V1 遗留网络from x402.mechanisms.evm.exact import ( register_exact_evm_client, register_exact_evm_server, register_exact_evm_facilitator, ) # 客户端自动包装 LocalAccount注册 eip155:* 全部 V1 网络 register_exact_evm_client(client, signer) # 服务端仅 V2 register_exact_evm_server(server) # Facilitator可开启智能钱包部署与 settle 模拟 register_exact_evm_facilitator( facilitator, signer, networkseip155:84532, deploy_erc4337_with_eip6492False, simulate_in_settleFalse, )四、Signer 协议与内置实现x402 通过两个 Protocol 把钱包能力与支付逻辑解耦signer.pyClientEvmSigner只需address属性 sign_typed_data(domain, types, primary_type, message)两个成员即可接入任意钱包 SDK。FacilitatorEvmSigner需要get_addresses()、read_contract()、verify_typed_data()、write_contract()、send_transaction()、wait_for_transaction_receipt()、get_balance()、get_chain_id()、get_code()等能力覆盖读合约、验签、发交易、等回执全流程。signers.py 提供了三个开箱即用的实现类定位说明EthAccountSigner客户端封装eth_account.LocalAccount用account.sign_typed_data()签 EIP-712 数据EthAccountSignerWithRPC客户端增强额外提供read_contract/sign_transaction/get_transaction_count/estimate_fees_per_gas满足 EIP-2612 与 ERC-20 approval 免 gas 扩展的能力要求ClientEvmSignerWithReadContract/ClientEvmSignerWithSignTransaction协议FacilitatorWeb3SignerFacilitator封装web3.pyverify_typed_data()先做 EOA 签名恢复比对失败后若地址存在合约代码则回落到 EIP-1271isValidSignature校验比对0x1626ba7e魔法值五、EIP-3009 授权结构与 EIP-712 签名Exact 方案的核心载荷types.py 的ExactEIP3009Authorization/ExactEIP3009Payload序列化为如下 JSON{ from: 0x..., # 支付方地址 to: 0x..., # 收款地址payTo value: 10000000, # 金额最小单位USDC 即 $1.00 validAfter: 1700000000, # 生效时间Unix 秒 validBefore: 1700003600, # 过期时间Unix 秒 nonce: 0x..., # 32 字节随机 nonce防重放 }ExactEIP3009Payload在此基础上附加signature字段0x前缀的 65 字节 ECDSA或更长的 ERC-6492 封装签名。签名时通过 eip712.py 的build_typed_data_for_signing()构造域{name, version, chainId, verifyingContract: 代币合约}与TransferWithAuthorization主类型——域参数直接决定签名哈希因此服务端注入的name/version必须与链上name()/version()一致否则验签必然失败。链上执行时Facilitator 按代币 ABI 调用transferWithAuthorizationVRS 与 bytes 两种重载均内置于 constants.py 的TRANSFER_WITH_AUTHORIZATION_VRS_ABI/TRANSFER_WITH_AUTHORIZATION_BYTES_ABI并可用authorizationState查询 nonce 是否已被使用。六、Facilitator 校验与结算流程ExactEvmFacilitatorScheme.verify()的完整校验清单facilitator.py L116-L270Scheme 匹配payload.accepted.scheme必须为exact否则返回unsupported_scheme网络匹配payload.accepted.network requirements.network否则network_mismatch链 ID 解析CAIP-2eip155:id→ chain id解析失败返回invalid_exact_evm_failed_to_get_network_configEIP-712 域参数extra必须含name与version否则missing_eip712_domain收款方一致authorization.to requirements.pay_to否则invalid_exact_evm_payload_recipient_mismatch金额一致authorization.value requirements.amountExact 方案的精确约束否则invalid_exact_evm_payload_authorization_value_mismatch时间窗validBefore必须晚于当前时间 6 秒缓冲防过期竞态validAfter不得晚于当前时间签名分类与校验classify_eip3009_signature()判定签名属于 EOA / 已部署智能钱包EIP-1271/ 未部署智能钱包ERC-6492三类之一未部署钱包若无部署信息则报invalid_exact_evm_payload_undeployed_smart_wallet交易模拟simulate_eip3009_transfer()用eth_call预演转账失败时经diagnose_eip3009_simulation_failure()给出细化原因如余额不足invalid_exact_evm_insufficient_balance、nonce 已用invalid_exact_evm_nonce_already_used。settle()流程先复用_verify()是否再模拟取决于simulate_in_settle→ 若签名携带 ERC-6492 部署信息且钱包尚未部署则按配置自动调用工厂部署deploy_erc4337_with_eip6492→ 执行transferWithAuthorization→wait_for_transaction_receipt()等待确认超时 120 秒→ 回执status 1返回SettleResponse(successTrue, transactiontx_hash, ...)。Permit2 载荷会分流到verify_permit2()/settle_permit2()permit2_utils.py由 Uniswap Permit2 合约配合仓库中的 x402ExactPermit2Proxy 完成结算代理地址0x402085c248EeA27D92E8b30b2C58ed07f9E20001与 Permit2 一样经 CREATE2 在各 EVM 链固定部署。七、支持的链与默认资产x402.mechanisms.evm导出NETWORK_CONFIGSCAIP-2 映射与V1_NETWORKS遗留网络名。当前 constants.py 中内置的 V2 链及默认资产如下链CAIP-2chain_id默认资产精度转账方式Base Mainneteip155:84538453USD Coin (USDC)0x8335...29136EIP-3009Base Sepoliaeip155:8453284532USDC0x036C...CF7e6EIP-3009MegaETHeip155:43264326MegaUSD18Permit2支持 EIP-2612Monadeip155:143143USD Coin6EIP-3009Mezo Testneteip155:3161131611Mezo USD18Permit2支持 EIP-2612Stable Mainneteip155:988988USDT06EIP-3009Stable Testneteip155:22012201USDT06EIP-3009Polygoneip155:137137USD Coin6EIP-3009Arbitrum Oneeip155:4216142161USD Coin6EIP-3009Arbitrum Sepoliaeip155:421614421614USD Coin6EIP-3009eip155:*通配符可注册到所有 EVM 链V1 遗留网络名base、base-sepolia、polygon、polygon-amoy、avalanche、avalanche-fuji等由V1_NETWORKS列出注册辅助函数会自动完成 V1 侧注册。关于链与代币支持的完整背景CAIP-2 标识规范、EIP-3009 与 Permit2 的选择逻辑参见 Networks Token Support为美元字符串定价补充新链默认资产的方式亦见该文档 新增默认资产 一节。八、资产支持EIP-3009 优先Permit2 兜底机制支持两类代币转账路径可对照 network-and-token-support.mdx 的EVM: Asset Transfer Methods一节EIP-3009适用于实现了transferWithAuthorization()的代币USDC 等一次签名即可、无授权步骤是首选路径Permit2适用于任意 ERC-20需一次性 Permit2 授权。仓库提供了两条免 gas 扩展来免除这一步EIP-2612 permit 扩展x402.extensions.eip2612_gas_sponsoring与 ERC-20 approval 扩展x402.extensions.erc20_approval_gas_sponsoring。从客户端源码可见当服务端在PaymentRequired.extensions中声明相应能力、且签名器实现了对应 ProtocolClientEvmSignerWithReadContract/ClientEvmSignerWithSignTransaction时create_payment_payload()会先链上读取现有 allowance不足时自动补签扩展数据并放入载荷的__extensions字段。自定义代币接入需要三要素代币地址、EIP-712name、EIP-712version即链上name()/version()返回值服务端可通过显式AssetAmount含extra.eip712或在AssetInfo注册中提供。九、智能钱包支持ERC-4337 / ERC-6492Exact 方案自动处理三种签名来源EOA标准 ECDSA直接Account.recover_message恢复比对已部署智能钱包EIP-1271isValidSignature校验成功返回0x1626ba7eEIP1271_MAGIC_VALUE未部署智能钱包ERC-6492 反事实签名。签名中内嵌工厂地址与部署 calldataparse_erc6492_signature()解析见 erc6492.pyverify 阶段按未来地址校验签名settle 阶段在deploy_erc4337_with_eip6492True时由 Facilitator 代为执行部署交易。未开启该配置时遇到未部署钱包会返回invalid_exact_evm_payload_undeployed_smart_wallet错误码。十、错误码速查所有失败路径都返回语义化的invalid_reason定义于 constants.py L318-L362常见者如错误码含义invalid_exact_evm_payload_signature签名无效非 EOA/1271 有效签名invalid_exact_evm_payload_undeployed_smart_wallet智能钱包未部署且无可解析的部署信息invalid_exact_evm_payload_authorization_value_mismatch授权金额与要求金额不一致invalid_exact_evm_nonce_already_usednonce 已被使用重放invalid_exact_evm_insufficient_balance支付方代币余额不足missing_eip712_domainrequirements.extra 缺少 name/versionsmart_wallet_deployment_failedERC-6492 钱包部署交易失败transaction_failed结算交易上链失败十一、关键文件索引路径内容README.md本机制的官方使用说明exact/client.py客户端签名授权生成含 Permit2 分流与免 gas 扩展exact/server.py服务端价格解析与要求增强exact/facilitator.pyFacilitator 校验/结算/智能钱包部署exact/register.py三个注册辅助函数signers.pyEthAccountSigner/EthAccountSignerWithRPC/FacilitatorWeb3Signersigner.py客户端/Facilitator 签名器 Protocol 定义constants.py网络配置、ABI、错误码、Permit2 代理地址types.pyExactEIP3009Payload、Permit2 载荷等数据类型eip712.py / erc6492.pyEIP-712 哈希构造 / ERC-6492 签名解析contracts/evm/src/x402ExactPermit2Proxy、x402UptoPermit2Proxy合约源码小结Python 的 x402 EVM 机制把 EIP-3009 一次签名、代付 gas 的支付模型封装为三角色对称的 Scheme 类——客户端只管签名、服务端只管定价与要求、Facilitator 只管校验与上链且通过 Signer Protocol 允许你接入任意钱包实现通过 ERC-6492 自动兼容尚未部署的 ERC-4337 智能账户。若你只需美元计价 USDC 结算按第二、三节的注册方式配合NETWORK_CONFIGS中任一内置链即可跑通若使用自定义代币或链则需要补充资产信息或注册自定义 money parser。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考