企业官网建设流程全解析

本文以仓库中最小的 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 USDC（Base Sepolia 测试网），只有付款到账后才返回市场洞察回答。技术栈是 Agno 框架 + OpenRouter 模型，全部逻辑放在一个文件里。

示例演示的核心链路如下：

1. 调用方（curl 脚本、另一个 Agent 或浏览器）向 Agent 发请求，未携带支付凭证；
2. Agent（Bindu）作为守门人返回 HTTP 402，附上价格报价（网络、资产、金额、收款地址）；
3. 调用方用钱包签署一次性授权（EIP-3009），把签名后的 payload 放进X-PAYMENT头重发；
4. Bindu 中间件向 facilitator（验证/结算服务）确认支付有效，然后才执行 Agent 的 handler。

这与 Bindu 项目「AI Agent 的身份、通信与支付层」的定位直接对应——支付层即 x402 扩展，实现在 bindu/server/middleware/x402/。

二、前置准备与安装

按示例 README 的要求，先准备两个东西：

export OPENROUTER_API_KEY=<get one at https://openrouter.ai/keys> uv sync --extra agents

• OPENROUTER_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 + OpenRouter

from agno.agent import Agent from agno.models.openrouter import OpenRouter agent = Agent( instructions="""You are the Oracle of Value, a premium market insight advisor. Provide high-value, actionable market insights and investment recommendations. ...""", model=OpenRouter( id="openai/gpt-oss-120b", api_key=os.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(input=latest_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_cost

config = { "author": "premium.advisor@example.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 的处理链：

1. _normalize_execution_costs()：把execution_cost归一化为列表（单 dict 或 list 均可），逐个校验amount必填，token与network有默认值USDC/base-sepolia（见文件顶部的DEFAULT_TOKEN、DEFAULT_NETWORK）；
2. _setup_x402_extension()：用第一个计费项构造X402AgentExtension，同时把完整列表作为payment_options传入；
3. X402AgentExtension（bindu/extensions/x402/x402_agent_extension.py）封装 amount/token/network/pay_to_address，并校验：开启支付时pay_to_address不能为空，否则抛ValueError。这就是为什么示例里即使放一个假地址也必须有值；
4. 只有当execution_cost被配置时，x402 扩展才会挂到 Agent 的 capabilities 上（add_extension_to_capabilities），agent 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: "10000"（0.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 与实现对应）：

1. 解析 JSON-RPC body，解析失败直接 402（此前版本的 bug 是解析异常会让请求「fail-open」绕过支付检查，现在已收紧为只捕获JSONDecodeError/UnicodeDecodeError）；
2. 方法白名单检查：只有app_settings.x402.protected_methods里的方法（如message/send）才要求支付；
3. 检查X-PAYMENT头是否存在；
4. base64 解码并解析 payload（SDK 的parse_payment_payload，同时支持 v1/v2 形态，但 verify 侧只接受 v2）；
5. 匹配到 Agent 发布的某个PaymentRequirements；
6. 先占坑防重放：以(network, asset, nonce)为键在 nonce store 中 claim，TTL 为max_timeout_seconds + 60s缓冲；
7. 交给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.py：

• POST /api/start-payment-session：创建支付会话，返回browser_url；
• GET /payment-capture?session_id=...：渲染 x402 paywall 页面，钱包确认后捕获支付 token（捕获但不消费）；
• GET /api/payment-status/{session_id}：轮询状态，完成后返回可直接作为X-PAYMENT头使用的payment_token（base64 编码的 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」；
• tags（finance、market-analysis、investment 等）与input_modes/output_modes；
• examples（如 "Should I invest in new DeFi projects?"）；
• capabilities_detail：其中payment_gated: supported: true直接宣告这是一个付费技能。

加载机制在 bindu/utils/skills/loader.py：load_skills()支持目录路径（含skill.yaml或SKILL.md）与内联 dict 两种形式。示例 config 里的"skills": ["skills/premium-market-insight-skill"]就是相对路径，运行时以调用方目录为基准解析（caller_dir / skill_path），name与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、Stellar；SKALE 等需要其他 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 的排障章节，常见现象与原因如下：

十、继续深入

• 完整支付机制文档：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 支付层的全部核心概念，可以在此基础上扩展出多网络报价、浏览器支付流、生产收款等完整方案。