【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载本文以仓库中最小的 x402 付费 Agent 示例 examples/premium-advisor 为骨架完整讲解如何在 Bindu 上把一个普通的 Agno OpenRouter Agent 改造成「先付费、后回答」的可变现 Agent调用方不带支付头访问时收到 402 报价签名 USDC 转账并通过X-PAYMENT头重发后Agent 才开始真正干活。读完本文你将掌握execution_cost配置、402 报价解读、X-PAYMENT头签名流程、底层 x402 中间件的工作机制以及上线前必须注意的安全与生产要点。一、这个示例解决什么问题Premium Advisor 是 Bindu 提供的一个最小可运行示例验证了 x402 支付墙的完整闭环每个问题收费 0.01 USDCBase Sepolia 测试网只有付款到账后才返回市场洞察回答。技术栈是 Agno 框架 OpenRouter 模型全部逻辑放在一个文件里。示例演示的核心链路如下调用方curl 脚本、另一个 Agent 或浏览器向 Agent 发请求未携带支付凭证AgentBindu作为守门人返回 HTTP 402附上价格报价网络、资产、金额、收款地址调用方用钱包签署一次性授权EIP-3009把签名后的 payload 放进X-PAYMENT头重发Bindu 中间件向 facilitator验证/结算服务确认支付有效然后才执行 Agent 的 handler。这与 Bindu 项目「AI Agent 的身份、通信与支付层」的定位直接对应——支付层即 x402 扩展实现在 bindu/server/middleware/x402/。二、前置准备与安装按示例 README 的要求先准备两个东西export OPENROUTER_API_KEYget one at https://openrouter.ai/keys uv sync --extra agentsOPENROUTER_API_KEY是 OpenRouter 的 API 密钥用于调用openai/gpt-oss-120b模型uv sync --extra agents安装包含 Agno 等 Agent 框架依赖的 extras。关键提醒来自 README 原话要让 Agent 真正收钱你需要一个持有Base Sepolia USDC的钱包。示例中premium_advisor.py里配置的pay_to_address是一个演示用的假地址dummy在接入真实资金之前必须修改——否则真金白银会打到无效地址上。三、最小付费 Agent 的源码拆解premium_advisor.py整个示例只有一个文件 examples/premium-advisor/premium_advisor.py可以分成三块理解。3.1 Agent 本体Agno OpenRouterfrom agno.agent import Agent from agno.models.openrouter import OpenRouter agent Agent( instructionsYou are the Oracle of Value, a premium market insight advisor. Provide high-value, actionable market insights and investment recommendations. ..., modelOpenRouter( idopenai/gpt-oss-120b, api_keyos.getenv(OPENROUTER_API_KEY) ), )agent是一个标准 Agno Agent系统提示词强调输出「高价值、可执行」的市场洞察与投资建议。这里的关键点付费墙与模型能力完全解耦——支付逻辑由 Bindu 的 x402 扩展负责Agent 本身不需要感知支付细节。3.2 handler被支付墙保护的入口def handler(messages: list[dict[str, str]]): if messages: latest_message messages[-1].get(content, ) if isinstance(messages[-1], dict) else str(messages[-1]) result agent.run(inputlatest_message) if hasattr(result, content): return result.content elif hasattr(result, response): return result.response else: return str(result) return Welcome to Oracle of Value! ...handler 签名是(messages: list[dict[str, str]]) - Any这是 Bindubindufy()对 handler 的约定。从 bindu/penguin/bindufy.py 的 docstring 可见handler 会被validate_agent_function()校验后包装进 Agent manifest。只有通过支付校验的请求才会走到这里。3.3 config支付墙的开关就在execution_costconfig { author: premium.advisorexample.com, name: Oracle_of_Value, description: I provide high-value market insights and investment recommendations. Payment required upfront., deployment: { url: http://localhost:3773, expose: True, cors_origins: [http://localhost:5173] }, execution_cost: { amount: 0.01, # 单次交互价格 token: USDC, # 计价币种 network: base-sepolia, # 网络Base 测试网 pay_to_address: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e, # 演示用假地址 }, skills: [skills/premium-market-insight-skill], storage: {type: memory}, scheduler: {type: memory}, debug_mode: True, } # Bindu-fy the agent - converts it to a discoverable, interoperable Bindu agent bindufy(config, handler)最后一行bindufy(config, handler)是全部魔法的入口它会校验配置、生成确定性 agent_id、初始化 DID 扩展、加载 skills、创建 Agent manifest并启动 uvicorn HTTP 服务器默认监听 bindu/utils/server_runner.py 解析出的 host:port。四、execution_cost是如何变成支付墙的源码视角示例 README 只给了配置但想知道它为什么生效需要看 bindu/penguin/bindufy.py 的处理链_normalize_execution_costs()把execution_cost归一化为列表单 dict 或 list 均可逐个校验amount必填token与network有默认值USDC/base-sepolia见文件顶部的DEFAULT_TOKEN、DEFAULT_NETWORK_setup_x402_extension()用第一个计费项构造X402AgentExtension同时把完整列表作为payment_options传入X402AgentExtensionbindu/extensions/x402/x402_agent_extension.py封装 amount/token/network/pay_to_address并校验开启支付时pay_to_address不能为空否则抛ValueError。这就是为什么示例里即使放一个假地址也必须有值只有当execution_cost被配置时x402 扩展才会挂到 Agent 的 capabilities 上add_extension_to_capabilitiesagent card 中随之出现 x402 extension URI。值得注意amount在 wire 上会换算成原子单位atomic units。README 中配置的是0.01而 402 报价里出现的是10000——因为 USDC 是 6 位小数0.01 × 10^6 10000。文档 docs/PAYMENT.md 特别强调amount 用字符串而不是浮点数避免精度问题。五、启动并体验「未付费 → 402 报价」运行方式README 原文uv run examples/premium-advisor/premium_advisor.py # http://localhost:3773启动后用 README 中的 curl 发一条不带支付头的 JSON-RPC 请求curl -i http://localhost:3773/ \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:message/send,id:00000000-0000-0000-0000-000000000004,params:{message:{role:user,parts:[{kind:text,text:Is now a good time to buy ETH?}],kind:message,messageId:00000000-0000-0000-0000-000000000001,contextId:00000000-0000-0000-0000-000000000002,taskId:00000000-0000-0000-0000-000000000003},configuration:{acceptedOutputModes:[application/json]}}}你会收到HTTP/1.1 402 Payment Required {x402Version:2,error:X-PAYMENT header required, accepts:[{amount:10000,asset:0x036CbD53842c5426634e7929541eC2318f3dCF7e, ...}]}示例 README 点明了一个常被误解的事实这个 402 就是工作状态working state——说明支付墙在正常履职。响应里的accepts数组就是报价单amount: 100000.01 USDC 的原子单位、asset是 Base Sepolia 上 USDC 合约地址、payTo是收款地址、maxTimeoutSeconds是授权有效窗口。从 bindu/server/middleware/x402/x402_middleware.py 看这个 402 由X402Middleware的_create_402_response()构造基于 x402 SDK 的PaymentRequired类型并额外附加 Bindu 的 Agent 发现元数据name、description、agentCard: /.well-known/agent.json以及配置了 DID 时的did字段——方便客户端从 402 响应里直接发现 Agent card。中间件的完整判定管线源码 docstring 与实现对应解析 JSON-RPC body解析失败直接 402此前版本的 bug 是解析异常会让请求「fail-open」绕过支付检查现在已收紧为只捕获JSONDecodeError/UnicodeDecodeError方法白名单检查只有app_settings.x402.protected_methods里的方法如message/send才要求支付检查X-PAYMENT头是否存在base64 解码并解析 payloadSDK 的parse_payment_payload同时支持 v1/v2 形态但 verify 侧只接受 v2匹配到 Agent 发布的某个PaymentRequirements先占坑防重放以(network, asset, nonce)为键在 nonce store 中 claimTTL 为max_timeout_seconds 60s缓冲交给x402ResourceServer.verify_payment走 facilitator 做 EIP-3009 签名恢复与链上余额校验is_valid为 False 时拒绝而非放行fail closed。六、付款后如何调用X-PAYMENT 头与浏览器支付流README 给出的解法是签署一笔 USDC 转账用X-PAYMENT: signed-payload重发请求。签名格式遵循 x402 规范EIP-3009 一次性授权每个请求需要新的签名nonce 不可复用。支付成功且校验通过后中间件会把payment_payload、payment_requirements、payer等信息挂到request.state上交给后续 worker。从 bindu/server/workers/manifest_worker.py 的调用链_settle_payment→_handle_settlement_failure可以确认Bindu 在运行你的 Agent 之前先结算settle-first结算失败的任务直接置为 failed不产生 LLM 开销也不会留下孤儿支付。除了纯 API 方式Bindu 还提供浏览器支付流实现在 bindu/server/endpoints/payment_sessions.pyPOST /api/start-payment-session创建支付会话返回browser_urlGET /payment-capture?session_id...渲染 x402 paywall 页面钱包确认后捕获支付 token捕获但不消费GET /api/payment-status/{session_id}轮询状态完成后返回可直接作为X-PAYMENT头使用的payment_tokenbase64 编码的 JSON。说明上图为 Bindu x402 paywall 的浏览器流程截图支付墙页与支付成功页与示例中 API 级 402 流程是同一条支付通道的两种交互形态。七、Skill 声明让付费能力可被发现示例还配套了一个 skill 清单 examples/premium-advisor/skills/premium-market-insight-skill/skill.yaml。它声明了id/name/version/author等元数据description明确写出「Payment Required: 0.01 USDC per interaction」tagsfinance、market-analysis、investment 等与input_modes/output_modesexamples如 Should I invest in new DeFi projects?capabilities_detail其中payment_gated: supported: true直接宣告这是一个付费技能。加载机制在 bindu/utils/skills/loader.pyload_skills()支持目录路径含skill.yaml或SKILL.md与内联 dict 两种形式。示例 config 里的skills: [skills/premium-market-insight-skill]就是相对路径运行时以调用方目录为基准解析caller_dir / skill_pathname与description是必填字段其余可选字段按需透传。这些 skill 会进入 Agent manifest最终在 agent card/.well-known/agent.json见 bindu/server/endpoints/agent_card.py中对外发布让其他 Agent 与工具可以发现「这个 Agent 提供什么、要收多少钱」。八、安全与生产要点示例 README 虽然简短但埋了两个值得展开的安全信号1.pay_to_address必须是真实收款地址。示例里是 dummy 地址README 明确警告「edit it before pointing real money at it」。生产环境应使用自己控制私钥的钱包地址并单独为 Agent 建钱包避免与个人资产混放。2. 测试网与主网切换。默认network: base-sepolia是 Base 测试网假钱、假 gas适合学习上线时改成base主网。docs/PAYMENT.md 还提到如需接受其他 EVM 链SKALE、Polygon、Ethereum 等需要在 bindu/settings.py 的extra_networks里注册该链的 CAIP-2 标识与 USDC 合约地址并指向认识该链的 facilitator默认https://x402.org/facilitator由 Coinbase 运营支持 Base、Solana、Algorand、Aptos、StellarSKALE 等需要其他 facilitator。3. 支付与鉴权是叠加关系。README 最后一行特别说明付费墙x402与认证门Hydra OAuth DID 签名消息体两者都要通过才能执行 handler。认证流程详见 docs/AUTH.md。也就是说付费只解决「给钱」认证解决「你是谁」二者互不替代。4. 重放与孤儿支付。每个支付授权都带 nonce重复使用会被中间件以Payment nonce already used (replay)拒绝且拒绝发生在 facilitator 往返之前省一次外部调用。而 settle-first 意味着如果 settle 成功后 handler 抛异常付款方已被扣款且 x402 没有原生退款原语任务会以payment-orphaned状态结束需要运营方手动发起 USDC 退款——详见 docs/PAYMENT.md 与 bugs/known-issues.md。九、故障排查速查结合 docs/PAYMENT.md 的排障章节常见现象与原因如下现象原因与处理永远 402到不了 handlerX-PAYMENT头缺失402 body 会指明缺什么error: Payment verification failedfacilitator 拒绝签名错误、链不匹配或 facilitator 不认识你请求的链查 Agent 服务端日志error: Payment nonce already used (replay)同一授权用了两次需为每个请求重新签名error: No matching payment requirements foundpayload 与execution_cost不匹配通常是 network/asset 不一致任务 failedPayment settlement failed; task not executed.verify 通过但/settle失败Agent 未执行无 LLM 开销task.metadata里有 facilitator 的失败原因任务 failedx402.payment.status payment-orphanedsettle 成功已扣款但 handler 抛异常需要手动退款十、继续深入完整支付机制文档docs/PAYMENT.md含 mock facilitator 本地演练、四种失败模式的端到端演示、生产上线清单中间件实现bindu/server/middleware/x402/x402_middleware.py 与防重放 bindu/server/middleware/x402/nonce_store.py结算与孤儿支付在 bindu/server/workers/manifest_worker.py 中搜索_settle_payment与_handle_settlement_failure支付需求构建在 bindu/server/applications.py 中搜索_create_payment_requirements中间件测试可视为最准确的规格说明tests/unit/server/middleware/x402/端到端失败模式驱动tests/e2e/x402_scenarios/uv run python tests/e2e/x402_scenarios/run_e2e.py。Premium Advisor 的全部价值在于它把「Agent 收费」压缩到了最少的代码量——一个 config 块、一个 handler、一行bindufy()。理解了这几十行你就理解了 Bindu 支付层的全部核心概念可以在此基础上扩展出多网络报价、浏览器支付流、生产收款等完整方案。赞分享【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载相关推荐x402 Fastify 支付中间件实战用 HTTP 402 协议为 Fastify API 接入按次付费墙x402 Fastify 支付中间件实战用 HTTP 402 协议为 Fastify API 接入按次付费墙 导读 本文基于 x402 仓库中的 exampl后端金融科技区块链API设计使用 x402/next 为 Next.js 应用接入 HTTP 402 付费墙paymentProxy 与 withX402 完整实战使用 x402/next 为 Next.js 应用接入 HTTP 402 付费墙paymentProxy 与 withX402 完整实战 导读 本文基于 x后端金融科技区块链API设计x402 Python MCP 集成实战用 x402.mcp 为 MCP 工具调用实现付费墙与自动支付x402 Python MCP 集成实战用 x402.mcp 为 MCP 工具调用实现付费墙与自动支付 本文基于 x402 Python SDK 中的 x40后端金融科技区块链API设计上一篇如何快速安全地导出浏览器CookieGet cookies.txt LOCALLY终极指南下一篇如何在Windows上快速部署小爱音箱语音控制系统实现智能音乐播放的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考