diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index 5681424d..86153c6a 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -37,9 +39,13 @@ Static mode stores your private key as plaintext in an environment variable — TRON transactions cannot be constructed directly by the client from scratch. The flow must start with a call to TronGrid's `createtransaction` endpoint, which returns an unsigned transaction object containing `txID` and `raw_data` generated by the network node. That object is then passed to Agent-wallet for local signing — the signing process is fully offline and the private key never leaves the machine. Finally, the signed transaction is submitted to TronGrid's `broadcasttransaction` endpoint to be published on-chain. -``` -TronGrid (build) → Agent-wallet (sign) → TronGrid (broadcast) -``` + Agent-wallet only participates in the middle signing step. It requires no RPC connection and has no awareness of the transaction's business meaning. @@ -258,9 +264,13 @@ The example uses Base58 addresses, consistent with `visible: true`. EVM transactions require the caller to construct the transaction object themselves. Unlike TRON, the fields of an EVM transaction (`nonce`, `gas`, `chainId`, etc.) must be queried from the current chain state via RPC and filled in manually — there is no centralized API that generates them for you. Once the unsigned transaction is built, it is passed to Agent-wallet for local signing, which returns a hex-encoded signed transaction. That signed transaction is then broadcast to the network via `sendRawTransaction`. -``` -RPC query nonce/gas (build) → Agent-wallet (sign) → RPC sendRawTransaction (broadcast) -``` + The example uses BSC Testnet, but switching to Ethereum, Polygon, Base, or any other EVM chain only requires changing `RPC_URL` and `CHAIN_ID` — the Agent-wallet calling code stays exactly the same. @@ -445,9 +455,13 @@ asyncio.run( x402 payments do not work by sending a direct transfer. Instead, they use a "sign first, verify to proceed" model. The agent signs a `TransferWithAuthorization` structure (EIP-712 format), and the resulting signature is sent alongside the request as a payment credential. The server verifies the signature and returns the content only if it is valid. The agent never has to wait for on-chain confirmation — latency is minimal. -``` -Server returns 402 → Agent builds PaymentPermit → Agent-wallet signs → Resend request with signature → Server verifies and responds -``` + The PaymentPermit data is automatically constructed by the x402 SDK based on the payment parameters returned by the server. Agent-wallet is only responsible for the final signing step. The example below shows the underlying signing logic, useful for scenarios that require custom integration or bypassing the x402 SDK. diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md index 68e77a43..237eccc0 100644 --- a/docs/Agent-Wallet/Developer/SDK-Guide.md +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -519,7 +519,7 @@ Error type hierarchy: WalletError ├── WalletNotFoundError # Specified wallet not found ├── DecryptionError # Wrong password or corrupted key file -├── SigningError # Signing operation failed +├── SigningError # Signing operation failed ├── NetworkError # Network identifier mismatch ├── InsufficientBalanceError # Insufficient balance ├── UnsupportedOperationError # Operation not supported by this wallet type diff --git a/docs/BANK-OF-AI/Intro.md b/docs/BANK-OF-AI/Intro.md index d9c42165..5afcdc89 100644 --- a/docs/BANK-OF-AI/Intro.md +++ b/docs/BANK-OF-AI/Intro.md @@ -4,6 +4,8 @@ description: >- BANK OF AI is the infrastructure connecting AI and Web3. Install it, and your AI can pay, prove its identity, and execute on-chain — you describe the goal, the AI gets it done. --- +import ThemedImage from '@theme/ThemedImage'; + # Introduction Today's AI can write code, analyze data, build presentations — it can even deliver an entire software project on its own. @@ -119,21 +121,13 @@ Once installed, you say: The whole path, at a glance: -```text -User - ↓ -AI interprets the request - ↓ -Selects a Skill or calls an MCP Server - ↓ -Agent Wallet signs - ↓ -Transaction broadcast - ↓ -Blockchain - ↓ -Result -``` + If anything goes wrong along the way — insufficient balance, a malformed address — the AI stops immediately and tells you why. And anything that spends money always needs your confirmation first. @@ -143,13 +137,13 @@ If anything goes wrong along the way — insufficient balance, a malformed addre Abstract that path into a diagram, and you have all of BANK OF AI: -```text - AI - │ -BANK OF AI - │ - Web3 -``` + Internally it's four layers, each with a single job: diff --git a/docs/BANK-OF-AI/image/bankofai-architecture.svg b/docs/BANK-OF-AI/image/bankofai-architecture.svg deleted file mode 100644 index 931d8592..00000000 --- a/docs/BANK-OF-AI/image/bankofai-architecture.svg +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - How BANK OF AI Layers Work Together - Example: TRC20 Transfer · Transfer 100 TRX - - - - Result → AI Agent - - - - - - 👤 You · Natural-Language Command - "Transfer 100 TRX to address T....XXXXX" - - - - ↑ AI reply - ↓ Your command - - - - 🧠 AI Agent - Powered by LLM Service · GPT / Claude / Gemini / DeepSeek / Kimi ... - Parses the intent, picks the matching Skill - - - - - - - 🌟 Skills · trc20-token-toolkit - Business Orchestration Layer - SOP: check balance → validate address → build tx → wait for confirmation - - - - - - - ⚙️ TRON MCP Server - Capability Provider Layer · On-chain atomic capability tools - This example: build the TRC20 transfer transaction - - - - - - - 🔐 Agent-Wallet · Local Encrypted Wallet - Private key never leaves your machine · Signed locally, then submitted on-chain - This example: local signing of the TRC20 transfer transaction - - - - - - - ⛓️ TRON Blockchain - - - Legend: - - Skills orchestration - - Sign / submit - - Result feedback - diff --git a/docs/McpServer-Skills/SKILLS/image/conversational-install.png b/docs/McpServer-Skills/SKILLS/image/conversational-install.png deleted file mode 100644 index 2d574a7c..00000000 Binary files a/docs/McpServer-Skills/SKILLS/image/conversational-install.png and /dev/null differ diff --git a/docs/McpServer-Skills/SKILLS/image/skill_call.jpg b/docs/McpServer-Skills/SKILLS/image/skill_call.jpg deleted file mode 100644 index 7eb969e5..00000000 Binary files a/docs/McpServer-Skills/SKILLS/image/skill_call.jpg and /dev/null differ diff --git a/docs/x402/api-catalog/index.md b/docs/x402/api-catalog/index.md index 7f8b48aa..34a9aa51 100644 --- a/docs/x402/api-catalog/index.md +++ b/docs/x402/api-catalog/index.md @@ -4,6 +4,8 @@ sidebar_label: Introduction description: BANK OF AI's wallet-native service catalog — where AI Agents discover, call, and pay for any API, settled on-chain via x402. --- +import ThemedImage from '@theme/ThemedImage'; + # API Catalog Traditional API onboarding is designed for humans: create an account, request an API key, link a credit card, subscribe monthly. When an AI Agent wants to call an API on its own, it fails at the very first step — it has no email, no credit card, and it shouldn't be holding a pile of secret keys for you anyway. @@ -21,17 +23,13 @@ The catalog itself is just a public list of services: it keeps no database and a To get listed, a provider submits two **public** files to the catalog repository (you can start with the application form and we'll help you through); the call addresses inside the files point to the gateway of your choice — BANK OF AI hosted or self-hosted. The platform validates, scans for sensitive data, then publishes: -```text -Provider Catalog repo (CI) Distribution -──────── ───────────────── ──────────── -catalog.json ──open PR──► field & sensitive-data scan ──► /api/catalog.json -pay.md build static snapshot dist/ /api/providers/.json - /api/pay/.json · .md - │ - ┌───────────────────────┼───────────────────────┐ - ▼ ▼ ▼ - Catalog website x402-cli MCP (Agent access) -``` + Three consumers share the same data: diff --git a/docs/x402/core-concepts/client-server.md b/docs/x402/core-concepts/client-server.md index 78947356..979f7553 100644 --- a/docs/x402/core-concepts/client-server.md +++ b/docs/x402/core-concepts/client-server.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + # Client and Server Understanding these roles in depth is essential when designing, building, or integrating x402-based programmable payment services on-chain. @@ -63,6 +65,14 @@ In the x402 protocol, a typical interaction between client and server proceeds a 5. **Server Executes Settlement**: Submits the transaction to the blockchain via the Facilitator. 6. **Server Delivers Resource**: Returns the requested resource and includes settlement confirmation (with transaction hash) in the `PAYMENT-RESPONSE` header. + + --- ## Summary diff --git a/docs/x402/core-concepts/gateway.md b/docs/x402/core-concepts/gateway.md index f3e6eb3f..4399f02b 100644 --- a/docs/x402/core-concepts/gateway.md +++ b/docs/x402/core-concepts/gateway.md @@ -4,6 +4,8 @@ sidebar_label: Gateway description: The Gateway turns any API into a pay-per-call service for AI Agents — Agents discover, call, and pay on their own, with every call settled on-chain to your wallet. --- +import ThemedImage from '@theme/ThemedImage'; + # Gateway Turn any API into a pay-per-call service for AI Agents. @@ -24,11 +26,13 @@ Think of the gateway as a **cashier + relay** standing in front of your API (tec - **Upstream keys stay isolated.** If your upstream API needs auth, that API key lives only on the side running the gateway — in your local YAML / env for a self-hosted gateway, or held by us for the official gateway. Either way the caller never sees it, and it never enters the public catalog. - **You decide pricing per endpoint.** Price an endpoint in the config and it takes the paid flow; leave it unpriced (price 0) and it's forwarded directly — free endpoints stay free. -```text -Agent ──► Gateway ──► your upstream API - │ quote / verify / settle (paid endpoints only) - └ forwards the request -``` + ## Anatomy of a call diff --git a/docs/x402/core-concepts/network-and-token-support.md b/docs/x402/core-concepts/network-and-token-support.md index 8f3c236b..7cf489aa 100644 --- a/docs/x402/core-concepts/network-and-token-support.md +++ b/docs/x402/core-concepts/network-and-token-support.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + # Network & Token Support import Tabs from '@theme/Tabs'; @@ -176,6 +178,14 @@ npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --toke 3. **Settle** The Facilitator submits the on-chain transaction — `transferWithAuthorization`, Permit2 `permitTransferFrom`, a batch claim, or a GasFree relay — based on the scheme. + + --- ## Deploying a Private Facilitator diff --git a/docs/x402/index.md b/docs/x402/index.md index 3bc0dd8f..d2b0c21b 100644 --- a/docs/x402/index.md +++ b/docs/x402/index.md @@ -5,6 +5,8 @@ description: >- This guide introduces the x402 open payment standard on blockchain and helps you start building or integrating x402-powered services. --- +import ThemedImage from '@theme/ThemedImage'; + # Welcome to x402 x402 is an open blockchain payment standard built on the HTTP `402 Payment Required` status code. It enables web services to charge for APIs or content through a “pay-before-response” mechanism — without relying on traditional account systems or session management. @@ -58,8 +60,17 @@ At a high level, the workflow is straightforward: 1. **Request Initiated:** The buyer requests a protected resource from the server. 2. **Payment Required:** If payment is required, the server returns a `402 Payment Required` response along with payment instructions. 3. **Payment Submitted:** The buyer generates and submits a signed payment payload. -4. **Verification & Settlement:** The server calls the x402 Facilitator’s `/verify` and `/settle` endpoints to validate and settle the payment. -5. **Resource Delivered:** Once verification succeeds, the server delivers the requested resource. +4. **Payment Verified:** The server calls the Facilitator’s `/verify` endpoint to validate the signed payload. +5. **Settlement Executed:** The server calls the Facilitator’s `/settle` endpoint to submit the transaction on-chain. +6. **Resource Delivered:** Once settlement succeeds, the server delivers the requested resource. + + To explore further: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index 91e83f6e..8d947dba 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -37,9 +39,13 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页 TRON 交易不能由客户端直接从零构建。流程必须从调用 TronGrid 的 `createtransaction` 接口开始——该接口返回一个包含 `txID` 和 `raw_data` 的未签名交易对象，由网络节点生成。然后把这个对象传给 Agent-wallet 进行本地签名——签名过程完全离线，私钥不会离开本机。最后，把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口，发布到链上。 -``` -TronGrid（构建）→ Agent-wallet（签名）→ TronGrid（广播） -``` + Agent-wallet 只参与中间的签名步骤，不需要 RPC 连接，也不感知交易的业务含义。 @@ -258,9 +264,13 @@ asyncio.run( EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，没有集中式 API 帮你生成。未签名交易构建完成后，传给 Agent-wallet 进行本地签名，返回十六进制编码的已签名交易，最后通过 `sendRawTransaction` 广播。 -``` -RPC 查询 nonce/gas（构建）→ Agent-wallet（签名）→ RPC sendRawTransaction（广播） -``` + 示例使用 BSC 测试网，切换到 Ethereum、Polygon、Base 或其他 EVM 链只需改 `RPC_URL` 和 `CHAIN_ID`——Agent-wallet 的调用代码一行不变。 @@ -445,9 +455,13 @@ asyncio.run( x402 支付不是直接发一笔转账，而是"先签名、验证后放行"的模型。代理对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，把得到的签名随请求一起发给服务器作为支付凭证。服务器验证签名有效后才返回内容。代理不需要等待链上确认——延迟极低。 -``` -服务器返回 402 → 代理构建 PaymentPermit → Agent-wallet 签名 → 携带签名重发请求 → 服务器验证通过并响应 -``` + PaymentPermit 数据由 x402 SDK 根据服务器返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面的示例展示了底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md index caf51c92..d6aff748 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md @@ -519,7 +519,7 @@ except SigningError as e: WalletError ├── WalletNotFoundError # 指定钱包不存在 ├── DecryptionError # 密码错误或密钥文件损坏 -├── SigningError # 签名操作失败 +├── SigningError # 签名操作失败 ├── NetworkError # 网络标识符不匹配 ├── InsufficientBalanceError # 余额不足 ├── UnsupportedOperationError # 该钱包类型不支持此操作 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/Intro.md index 8a69e582..37c8a45a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/Intro.md @@ -4,6 +4,8 @@ description: >- BANK OF AI 是连接 AI 与 Web3 的基础设施。装上它，你的 AI 就能付款、验证身份、执行链上操作——你负责说想做什么，AI 负责做成。 --- +import ThemedImage from '@theme/ThemedImage'; + # 简介 今天的 AI 已经会写代码、分析数据、制作演示文稿，甚至能独立完成一个完整的软件项目。 @@ -119,21 +121,13 @@ AI 拥有可验证的链上身份，Agent 之间可以互信协作。 整条链路一目了然： -```text -用户 - ↓ -AI 理解需求 - ↓ -选择 Skill 或调用 MCP Server - ↓ -Agent Wallet 签名 - ↓ -广播交易 - ↓ -区块链 - ↓ -返回结果 -``` + 执行过程中，任何一步出现问题（余额不足、地址有误），AI 都会立即停下并说明原因；任何涉及资金支出的动作，都必须先经过你的确认。 @@ -143,13 +137,13 @@ Agent Wallet 签名 把上面那条链路抽象成一张图，就是 BANK OF AI 的全部： -```text - AI - │ -BANK OF AI - │ - Web3 -``` + 内部分为四层，每层只负责一件事： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/image/bankofai-architecture.svg b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/image/bankofai-architecture.svg deleted file mode 100644 index 25bf4688..00000000 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/image/bankofai-architecture.svg +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BANK OF AI 的协作流程 - 示例：TRC20 转账 · Transfer 100 TRX - - - - 执行结果 → AI 智能体 - - - - - - 👤 你 · 自然语言指令 - "向地址 T....XXXXX 转 100 TRX" - - - - ↑ AI 回复 - ↓ 你的指令 - - - - 🧠 AI 智能体 - 由 LLM Service 驱动 · GPT / Claude / Gemini / DeepSeek / Kimi ... - 理解意图，调用对应的 Skill - - - - - - - 🌟 Skills · trc20-token-toolkit - 业务编排层 · Business Orchestration Layer - SOP：查余额 → 校验地址 → 构造交易 → 等你确认 - - - - - - - ⚙️ TRON MCP Server - 能力提供层 · 提供链上原子能力工具 - 本例调用：构造 TRC20 转账交易 - - - - - - - 🔐 Agent-Wallet · 本地加密钱包 - 私钥永不出本机 · 交易在本地签名后提交上链 - 本例：对 TRC20 转账交易执行本地签名 - - - - - - - ⛓️ TRON Blockchain - - - 图例 / Legend： - - Skills 编排 - - 签名 / 上链 - - 执行结果反馈 - diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/conversational-install.png b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/conversational-install.png deleted file mode 100644 index 11732377..00000000 Binary files a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/conversational-install.png and /dev/null differ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/skill_call.jpg b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/skill_call.jpg deleted file mode 100644 index 7eb969e5..00000000 Binary files a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/image/skill_call.jpg and /dev/null differ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md index b0948923..5af661ae 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md @@ -4,6 +4,8 @@ sidebar_label: 介绍 description: BANK OF AI 的钱包原生服务目录 —— AI Agent 在这里发现、调用并为任意 API 按次付费，通过 x402 在链上结算。 --- +import ThemedImage from '@theme/ThemedImage'; + # API 目录 传统 API 的门槛是为人设计的：注册账号、申请 API Key、绑定信用卡、按月订阅。可一个 AI Agent 想自主调用一个接口时，光是「开户」这一步就走不通——它没有邮箱、没有信用卡，也不该替你保管一长串密钥。 @@ -21,17 +23,13 @@ description: BANK OF AI 的钱包原生服务目录 —— AI Agent 在这里发 服务方向目录仓库提交两份**公开**文件即可上架（可先填表申请，由我们联系协助）；文件里的调用地址指向所选网关——BANK OF AI 官方托管或自建均可。平台自动校验、扫描敏感信息后对外发布： -```text -服务方 目录仓库 (CI) 分发 -───────── ───────────── ──────── -catalog.json ──提交 PR──► 字段校验 + 敏感信息扫描 ──► /api/catalog.json -pay.md 构建静态快照 dist/ /api/providers/.json - /api/pay/.json · .md - │ - ┌───────────────────────┼───────────────────────┐ - ▼ ▼ ▼ - 前端目录站 x402-cli MCP（Agent 接入） -``` + 三个消费入口共用同一份数据： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md index 72cc3ddf..c3af2f46 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + # 客户端与服务器 深入理解这些角色，对于在区块链上设计、构建或集成基于 x402 的程序化支付服务至关重要。 @@ -57,6 +59,14 @@ 5. **服务端执行结算**：通过 Facilitator 将交易提交至区块链完成结算。 6. **服务端交付资源**：返回请求的资源，并在 `PAYMENT-RESPONSE` 标头中包含结算确认信息（内含交易哈希）。 + + ## 总结 在 x402 协议体系中： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md index e2646083..f0cf2f70 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md @@ -4,6 +4,8 @@ sidebar_label: 网关 description: 网关把任意 API 变成面向 AI Agent 的按次计费服务 —— Agent 自主发现、调用、付费，每一笔在链上结算到你的钱包。 --- +import ThemedImage from '@theme/ThemedImage'; + # 网关 将任意 API 转化为面向 AI Agent 的按次计费服务。 @@ -24,11 +26,13 @@ description: 网关把任意 API 变成面向 AI Agent 的按次计费服务 — - **上游密钥不外泄**。如果你的上游接口需要鉴权，那个 API Key 只待在运行网关的那一侧——自建网关时留在你本地的 yaml 或环境变量，用官方网关时由我们托管。无论哪种，调用方全程接触不到，密钥也不会进入公开目录。 - **收不收费由你按端点决定**。在配置中为端点定价即走付费流程；不定价（价格为 0）的端点直接转发，免费接口依然免费。 -```text -Agent ──► 网关 ──► 你的上游 API - │ 报价 / 验款 / 结算（仅付费端点） - └ 转发请求 -``` + ## 一次调用的完整流程 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md index 0baa52ab..d17ced2e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md @@ -1,3 +1,5 @@ +import ThemedImage from '@theme/ThemedImage'; + # 网络与代币支持 import Tabs from '@theme/Tabs'; @@ -153,6 +155,14 @@ npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --toke 2. **执行服务 (Execute)**：服务端执行请求任务，并（对于按量计费方案）计算**实际成本**。 3. **最终结算 (Settle)**：Facilitator 根据方案发起链上交易——`transferWithAuthorization`、Permit2 `permitTransferFrom`、批量 claim 或 GasFree relay。 + + ### 部署私有 Facilitator 您可以选择部署私有的 Facilitator，以完全掌控区块链网络上的支付验证与结算流程。自托管示例（`examples/typescript/facilitator/basic`）是一个暴露 `/verify`、`/settle`、`/supported` 的 Express 服务——无需数据库。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md index 4f47123f..fa209cfa 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md @@ -5,6 +5,8 @@ description: >- 本指南将帮助您了解 x402 区块链上的开放支付标准，并帮助您开始构建或集成 x402 服务。 --- +import ThemedImage from '@theme/ThemedImage'; + # 欢迎使用 x402 x402 是一种基于 HTTP `402 Payment Required` 状态码的区块链开放支付标准。它允许 Web 服务通过“先付费后响应”的机制直接对 API 或内容进行收费，无需依赖传统的账户或会话体系。目前，x402 已支持 **TRON**、**BNB Smart Chain（BSC）** 和 **Base**，并计划在未来扩展至更广泛的多链生态。 @@ -46,8 +48,17 @@ x402 支持广泛的应用场景，包括： 1. **发起请求**：买家向服务端请求受保护的资源。 2. **支付要求**：若该资源需要付费，服务端返回 `402 Payment Required` 状态码及支付指引。 3. **提交支付**：买家生成并提交签名的支付载荷。 -4. **验证结算**：服务端调用 x402 Facilitator 的 `/verify` 和 `/settle` 接口，完成支付的验证与结算。 -5. **交付资源**：支付验证通过后，服务端交付请求的资源。 +4. **校验支付**：服务端调用 Facilitator 的 `/verify` 接口，校验签名载荷的有效性。 +5. **执行结算**：服务端调用 Facilitator 的 `/settle` 接口，将交易提交上链。 +6. **交付资源**：结算成功后，服务端交付请求的资源。 + + 如需深入了解，请参考： diff --git a/package.json b/package.json index 18c22084..291dc033 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.3.18", + "version": "1.3.19", "description": "x402-tron documentation", "license": "MIT", "resolutions": { diff --git a/scripts/gen-diagrams.py b/scripts/gen-diagrams.py new file mode 100644 index 00000000..f78cd6c0 --- /dev/null +++ b/scripts/gen-diagrams.py @@ -0,0 +1,727 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +Generate dark-themed diagram SVGs for the BANK OF AI docs site. + +Design system follows the process-flow-diagram / architecture-diagram skills: + background #020617 (slate-950) + 40px grid + manual emerald #34d399 / rgba(6,78,59,.4) + automated violet #a78bfa / rgba(76,29,149,.4) + integration amber #fbbf24 / rgba(120,53,15,.3) + security rose #fb7185 / rgba(136,19,55,.4) + terminal cyan #22d3ee / rgba(8,51,68,.4) + generic slate #94a3b8 / rgba(30,41,59,.5) + +Vertical layout is used for process flows so the diagrams stay legible inside +a ~750px Docusaurus content column. +""" + +import html +import os +import sys + +FONT = ("'JetBrains Mono','SFMono-Regular',Menlo,Consolas," + "'PingFang SC','Hiragino Sans GB','Microsoft YaHei'," + "'Noto Sans CJK SC','Noto Sans SC','Source Han Sans SC',monospace") + +THEMES = { + "dark": { + "bg": "#020617", "grid": "#1e293b", "border": "#1e293b", + "mask": "#0f172a", "badge_bg": "#1e293b", + "ink": "#f8fafc", "ink2": "#e2e8f0", "ink3": "#94a3b8", + "dot": "#a78bfa", "arrow": "#64748b", + "note_fill": "rgba(30, 41, 59, 0.35)", "note_stroke": "#475569", + "boundary_fill": "rgba(167, 139, 250, 0.05)", "boundary": "#a78bfa", + "kind": { + "manual": ("rgba(6, 78, 59, 0.4)", "#34d399", "emerald"), + "auto": ("rgba(76, 29, 149, 0.4)", "#a78bfa", "violet"), + "integration": ("rgba(120, 53, 15, 0.3)", "#fbbf24", "amber"), + "security": ("rgba(136, 19, 55, 0.4)", "#fb7185", "rose"), + "terminal": ("rgba(8, 51, 68, 0.4)", "#22d3ee", "cyan"), + "generic": ("rgba(30, 41, 59, 0.5)", "#94a3b8", "slate"), + }, + "marker": {"slate": "#64748b", "cyan": "#22d3ee", "emerald": "#34d399", + "violet": "#a78bfa", "amber": "#fbbf24", "rose": "#fb7185"}, + }, + "light": { + "bg": "#ffffff", "grid": "#eef2f7", "border": "#e2e8f0", + "mask": "#ffffff", "badge_bg": "#ffffff", + "ink": "#0f172a", "ink2": "#1e293b", "ink3": "#64748b", + "dot": "#7c3aed", "arrow": "#94a3b8", + "note_fill": "#f8fafc", "note_stroke": "#cbd5e1", + "boundary_fill": "rgba(124, 58, 237, 0.04)", "boundary": "#7c3aed", + "kind": { + "manual": ("#ecfdf5", "#059669", "emerald"), + "auto": ("#f5f3ff", "#7c3aed", "violet"), + "integration": ("#fffbeb", "#d97706", "amber"), + "security": ("#fff1f2", "#e11d48", "rose"), + "terminal": ("#ecfeff", "#0891b2", "cyan"), + "generic": ("#f8fafc", "#64748b", "slate"), + }, + "marker": {"slate": "#94a3b8", "cyan": "#0891b2", "emerald": "#059669", + "violet": "#7c3aed", "amber": "#d97706", "rose": "#e11d48"}, + }, +} + +TH = THEMES["dark"] + + +def set_theme(name): + global TH, KIND + TH = THEMES[name] + KIND = TH["kind"] + + +KIND = TH["kind"] + +LEGEND_LABEL = { + "en": { + "manual": "User / manual step", + "auto": "AI / automated step", + "integration": "Network / external API", + "security": "Local signing (private key)", + "terminal": "Start / end", + "generic": "Component", + }, + "zh": { + "manual": "用户 / 手动步骤", + "auto": "AI / 自动步骤", + "integration": "网络 / 外部接口", + "security": "本地签名（私钥）", + "terminal": "起点 / 终点", + "generic": "组件", + }, +} + +E = html.escape + + +def head(w, h): + return ( + f'\n' + ' \n' + ' \n' + f' \n' + ' \n' + + "".join( + f' \n' + f' \n' + ' \n' + for name, col in TH["marker"].items() + ) + + ' \n' + f' \n' + f' \n' + f' \n' + ) + + +def title_block(w, title, subtitle): + s = ( + f' \n' + f' {E(title)}\n' + ) + if subtitle: + s += f' {E(subtitle)}\n' + return s + + +def box(x, y, w, h, kind, title, desc=None, badge=None, actor=None, title_size=13): + fill, stroke, _ = KIND[kind] + cx = x + w / 2 + s = ( + f' \n' + f' \n' + f' {E(title)}\n' + ) + for i, line in enumerate(desc or []): + s += (f' {E(line)}\n') + if badge is not None: + bx = x - 20 + s += (f' \n' + f' {E(str(badge))}\n') + if actor: + s += (f' {E(actor)}\n') + return s + + +def text_w(s, size): + """Approximate rendered width: CJK glyphs are full-width, latin mono ~0.6em.""" + units = sum(2 if ord(c) > 0x2E80 else 1 for c in s) + return units * size * 0.6 + + +def pill(x, y, w, h, label, stroke=None, fill=None): + stroke = stroke or KIND["terminal"][1] + fill = fill or KIND["terminal"][0] + return ( + f' \n' + f' \n' + f' {E(label)}\n' + ) + + +def varrow(cx, y1, y2, color="slate", label=None, label_x=None, dashed=False): + col = TH["marker"][color] + dash = ' stroke-dasharray="5,4"' if dashed else "" + s = (f' \n') + if label: + lx = label_x if label_x is not None else cx + 12 + s += (f' ' + f'{E(label)}\n') + return s + + +def harrow(y, x1, x2, color="slate", label=None, dashed=False): + col = TH["marker"][color] + dash = ' stroke-dasharray="5,4"' if dashed else "" + s = (f' \n') + if label: + s += (f' {E(label)}\n') + return s + + +def legend(x, y, kinds, lang, per_row=3, col_w=250): + s = "" + for i, k in enumerate(kinds): + fill, stroke, _ = KIND[k] + cxx = x + (i % per_row) * col_w + cyy = y + (i // per_row) * 20 + s += (f' \n' + f' ' + f'{E(LEGEND_LABEL[lang][k])}\n') + return s + + +# -------------------------------------------------------------------------- +# Vertical process flow +# -------------------------------------------------------------------------- + +W = 880 +BOX_X = 170 +BOX_W = 540 +CX = BOX_X + BOX_W / 2 +GAP = 40 + + +def vflow(spec, lang): + steps = spec["steps"] + parts = [] + y = 88 if spec.get("subtitle") else 72 + + if spec.get("start"): + pw = max(150, round(text_w(spec["start"], 12) + 48)) + parts.append(pill(CX - pw / 2, y, pw, 38, spec["start"])) + prev_bottom, prev_color = y + 38, "cyan" + y += 38 + GAP + else: + prev_bottom, prev_color = None, None + + for i, st in enumerate(steps): + h = 40 + 15 * len(st.get("desc", [])) if st.get("desc") else 40 + h = max(h, 44) + if prev_bottom is not None: + parts.append(varrow(CX, prev_bottom, y - 4, prev_color, + label=st.get("via"), label_x=BOX_X + BOX_W - 150)) + parts.append(box(BOX_X, y, BOX_W, h, st["kind"], st["title"], + st.get("desc"), badge=st.get("n", i + 1), + actor=st.get("actor"))) + prev_bottom, prev_color = y + h, KIND[st["kind"]][2].replace("cyan", "cyan") + prev_color = {"emerald": "emerald", "violet": "violet", "amber": "amber", + "rose": "rose", "cyan": "cyan", "slate": "slate"}[KIND[st["kind"]][2]] + y += h + GAP + + if spec.get("end"): + pw = max(150, round(text_w(spec["end"], 12) + 48)) + parts.append(varrow(CX, prev_bottom, y - 4, prev_color, label=spec.get("end_via"), + label_x=BOX_X + BOX_W - 150)) + parts.append(pill(CX - pw / 2, y, pw, 38, spec["end"])) + y += 38 + + y += 34 + used = {s["kind"] for s in steps} + if spec.get("start") or spec.get("end"): + used.add("terminal") + kinds = spec.get("legend") or sorted(used, key=lambda k: list(KIND).index(k)) + rows = (len(kinds) + 2) // 3 + parts.append(legend(48, y, kinds, lang)) + h_total = int(y + rows * 20 + 18) + + return (head(W, h_total) + + title_block(W, spec["title"], spec.get("subtitle")) + + "".join(parts) + "\n") + + +# -------------------------------------------------------------------------- +# Diagram specs +# -------------------------------------------------------------------------- + +T = { + # ---------------- BANK OF AI execution flow ---------------- + "bank-of-ai-execution-flow": { + "en": { + "title": "BANK OF AI — one execution, end to end", + "subtitle": 'Example: "Swap 100 USDT for TRX, keep slippage under 1%."', + "start": "You state the goal", + "steps": [ + {"kind": "auto", "title": "AI interprets the request", + "desc": ["Parses intent, amount, network and slippage limit"], + "actor": "LLM"}, + {"kind": "auto", "title": "Selects a Skill or calls an MCP Server", + "desc": ["Skill = business SOP · MCP Server = on-chain capability"], + "actor": "ORCHESTRATION"}, + {"kind": "security", "title": "Agent Wallet signs", + "desc": ["Signed locally — the private key never leaves your machine"], + "actor": "WALLET"}, + {"kind": "integration", "title": "Transaction broadcast", + "desc": ["Signed transaction submitted to a network node"], + "actor": "RPC"}, + {"kind": "integration", "title": "Blockchain", + "desc": ["Executed and confirmed on chain"], + "actor": "CHAIN"}, + ], + "end": "Result returned to you", + "note": "Any step that fails — insufficient balance, malformed address — stops the flow immediately. Anything that spends money asks for your confirmation first.", + }, + "zh": { + "title": "BANK OF AI — 一次完整执行", + "subtitle": "示例：把 100 USDT 换成 TRX，滑点不超过 1%。", + "start": "你说出目标", + "steps": [ + {"kind": "auto", "title": "AI 理解需求", + "desc": ["解析意图、金额、网络与滑点上限"], "actor": "大模型"}, + {"kind": "auto", "title": "选择 Skill 或调用 MCP Server", + "desc": ["Skill = 业务流程 · MCP Server = 链上能力"], "actor": "编排层"}, + {"kind": "security", "title": "Agent Wallet 签名", + "desc": ["本地签名，私钥不出本机"], "actor": "钱包"}, + {"kind": "integration", "title": "广播交易", + "desc": ["已签名交易提交给网络节点"], "actor": "节点"}, + {"kind": "integration", "title": "区块链", + "desc": ["链上执行并确认"], "actor": "链"}, + ], + "end": "结果返回给你", + }, + }, + + # ---------------- x402 payment flow ---------------- + "x402-payment-flow": { + "en": { + "title": "x402 payment flow", + "subtitle": "How a client, a server and the Facilitator settle one paid HTTP request", + "start": "Client wants a paid resource", + "steps": [ + {"kind": "manual", "title": "Client initiates request", + "desc": ["Plain HTTP request, no payment attached yet"], + "actor": "CLIENT"}, + {"kind": "auto", "title": "Server requires payment", + "desc": ["402 Payment Required · details in PAYMENT-REQUIRED (Base64)"], + "actor": "SERVER", "via": "402"}, + {"kind": "security", "title": "Client submits payment", + "desc": ["Signs the payload, resends it in PAYMENT-SIGNATURE"], + "actor": "CLIENT", "via": "sign"}, + {"kind": "integration", "title": "Server validates payment", + "desc": ["Facilitator /verify — signature and payload integrity"], + "actor": "FACILITATOR", "via": "/verify"}, + {"kind": "integration", "title": "Server executes settlement", + "desc": ["Facilitator /settle — transaction submitted on chain"], + "actor": "FACILITATOR", "via": "/settle"}, + {"kind": "auto", "title": "Server delivers the resource", + "desc": ["Response carries the tx hash in PAYMENT-RESPONSE"], + "actor": "SERVER"}, + ], + "end": "Resource delivered", + }, + "zh": { + "title": "x402 支付流程", + "subtitle": "客户端、服务端与 Facilitator 如何结算一次付费 HTTP 请求", + "start": "客户端请求付费资源", + "steps": [ + {"kind": "manual", "title": "客户端发起请求", + "desc": ["普通 HTTP 请求，尚未携带支付凭证"], "actor": "客户端"}, + {"kind": "auto", "title": "服务端要求付款", + "desc": ["返回 402 · 支付详情放在 PAYMENT-REQUIRED（Base64）"], + "actor": "服务端", "via": "402"}, + {"kind": "security", "title": "客户端提交支付", + "desc": ["生成签名，通过 PAYMENT-SIGNATURE 重发请求"], + "actor": "客户端", "via": "签名"}, + {"kind": "integration", "title": "服务端校验支付", + "desc": ["调用 Facilitator /verify 校验签名与载荷完整性"], + "actor": "FACILITATOR", "via": "/verify"}, + {"kind": "integration", "title": "服务端执行结算", + "desc": ["调用 Facilitator /settle，交易提交上链"], + "actor": "FACILITATOR", "via": "/settle"}, + {"kind": "auto", "title": "服务端交付资源", + "desc": ["响应在 PAYMENT-RESPONSE 中带回交易哈希"], "actor": "服务端"}, + ], + "end": "资源交付完成", + }, + }, + + # ---------------- Agent Wallet: TRON ---------------- + "agent-wallet-tron-flow": { + "en": { + "title": "TRON transfer — where Agent-wallet fits", + "subtitle": "Agent-wallet only signs. It needs no RPC connection and knows nothing about the business meaning.", + "steps": [ + {"kind": "integration", "title": "TronGrid — build", + "desc": ["createtransaction returns an unsigned tx (txID + raw_data)"], + "actor": "NETWORK"}, + {"kind": "security", "title": "Agent-wallet — sign", + "desc": ["Fully offline; the private key never leaves the machine"], + "actor": "LOCAL", "via": "unsigned tx"}, + {"kind": "integration", "title": "TronGrid — broadcast", + "desc": ["broadcasttransaction publishes it on chain"], + "actor": "NETWORK", "via": "signed tx"}, + ], + }, + "zh": { + "title": "TRON 转账 —— Agent-wallet 在哪一步", + "subtitle": "Agent-wallet 只负责签名，不需要 RPC 连接，也不感知交易的业务含义。", + "steps": [ + {"kind": "integration", "title": "TronGrid — 构造", + "desc": ["createtransaction 返回未签名交易（txID + raw_data）"], + "actor": "网络"}, + {"kind": "security", "title": "Agent-wallet — 签名", + "desc": ["完全离线，私钥不出本机"], "actor": "本地", "via": "未签名交易"}, + {"kind": "integration", "title": "TronGrid — 广播", + "desc": ["broadcasttransaction 发布上链"], "actor": "网络", "via": "已签名交易"}, + ], + }, + }, + + # ---------------- Agent Wallet: EVM ---------------- + "agent-wallet-evm-flow": { + "en": { + "title": "EVM transfer — where Agent-wallet fits", + "subtitle": "BSC / Ethereum / Polygon / Base — only RPC_URL and CHAIN_ID change.", + "steps": [ + {"kind": "integration", "title": "RPC — build", + "desc": ["Query nonce / gas / chainId and assemble the tx yourself"], + "actor": "NETWORK"}, + {"kind": "security", "title": "Agent-wallet — sign", + "desc": ["Returns a hex-encoded signed transaction"], + "actor": "LOCAL", "via": "unsigned tx"}, + {"kind": "integration", "title": "RPC — sendRawTransaction", + "desc": ["Broadcast the signed transaction to the network"], + "actor": "NETWORK", "via": "signed tx"}, + ], + }, + "zh": { + "title": "EVM 转账 —— Agent-wallet 在哪一步", + "subtitle": "BSC / Ethereum / Polygon / Base —— 只需替换 RPC_URL 与 CHAIN_ID。", + "steps": [ + {"kind": "integration", "title": "RPC — 构造", + "desc": ["查询 nonce / gas / chainId，自行组装交易对象"], "actor": "网络"}, + {"kind": "security", "title": "Agent-wallet — 签名", + "desc": ["返回 hex 编码的已签名交易"], "actor": "本地", "via": "未签名交易"}, + {"kind": "integration", "title": "RPC — sendRawTransaction", + "desc": ["将已签名交易广播到网络"], "actor": "网络", "via": "已签名交易"}, + ], + }, + }, + + # ---------------- Agent Wallet: x402 PaymentPermit ---------------- + "agent-wallet-x402-permit-flow": { + "en": { + "title": "x402 PaymentPermit signing", + "subtitle": "Sign first, verify to proceed — the agent never waits for on-chain confirmation.", + "steps": [ + {"kind": "auto", "title": "Server returns 402", + "desc": ["Payment parameters come back with the 402 response"], + "actor": "SERVER"}, + {"kind": "auto", "title": "Agent builds PaymentPermit", + "desc": ["TransferWithAuthorization struct, EIP-712 format"], + "actor": "x402 SDK"}, + {"kind": "security", "title": "Agent-wallet signs", + "desc": ["The only step Agent-wallet is responsible for"], + "actor": "LOCAL"}, + {"kind": "manual", "title": "Resend request with signature", + "desc": ["The signature travels as the payment credential"], + "actor": "AGENT"}, + {"kind": "auto", "title": "Server verifies and responds", + "desc": ["Content returned only if the signature checks out"], + "actor": "SERVER"}, + ], + }, + "zh": { + "title": "x402 PaymentPermit 签名", + "subtitle": "先签名、验证通过再放行 —— Agent 无需等待链上确认。", + "steps": [ + {"kind": "auto", "title": "服务端返回 402", + "desc": ["402 响应中带回支付参数"], "actor": "服务端"}, + {"kind": "auto", "title": "Agent 构造 PaymentPermit", + "desc": ["TransferWithAuthorization 结构，EIP-712 格式"], "actor": "x402 SDK"}, + {"kind": "security", "title": "Agent-wallet 签名", + "desc": ["Agent-wallet 只负责这一步"], "actor": "本地"}, + {"kind": "manual", "title": "携带签名重发请求", + "desc": ["签名作为支付凭证随请求发送"], "actor": "AGENT"}, + {"kind": "auto", "title": "服务端验证并响应", + "desc": ["签名有效才返回内容"], "actor": "服务端"}, + ], + }, + }, + + # ---------------- Payment schemes ---------------- + "x402-payment-scheme-flow": { + "en": { + "title": "How payment schemes work", + "subtitle": "exact · upto · batch-settlement · GasFree — same three beats, different settlement call", + "steps": [ + {"kind": "security", "title": "Authorize", + "desc": ["Client signs typed data: an exact amount, or a maximum for upto / batch"], + "actor": "CLIENT"}, + {"kind": "auto", "title": "Execute", + "desc": ["Server performs the task and, for usage-based schemes, computes actual cost"], + "actor": "SERVER"}, + {"kind": "integration", "title": "Settle", + "desc": ["transferWithAuthorization · Permit2 permitTransferFrom · batch claim · GasFree relay"], + "actor": "FACILITATOR"}, + ], + }, + "zh": { + "title": "支付方案如何运作", + "subtitle": "exact · upto · batch-settlement · GasFree —— 同样三拍，结算调用不同", + "steps": [ + {"kind": "security", "title": "授权 Authorize", + "desc": ["客户端签名 typed data：固定金额，或 upto / batch 的上限"], "actor": "客户端"}, + {"kind": "auto", "title": "执行 Execute", + "desc": ["服务端执行任务；按量计费方案还会计算实际费用"], "actor": "服务端"}, + {"kind": "integration", "title": "结算 Settle", + "desc": ["transferWithAuthorization · Permit2 · 批量领取 · GasFree 中继"], + "actor": "FACILITATOR"}, + ], + }, + }, +} + + +# -------------------------------------------------------------------------- +# Architecture diagrams (explicit layouts) +# -------------------------------------------------------------------------- + +A = { + "bank-of-ai-architecture": { + "en": { + "title": "BANK OF AI — the whole picture", + "subtitle": "One platform sitting between your AI and the on-chain world.", + "nodes": [ + ("terminal", "AI", 240, 58), + ("auto", "BANK OF AI", 340, 72), + ("terminal", "Web3", 240, 58), + ], + }, + "zh": { + "title": "BANK OF AI —— 整体架构", + "subtitle": "夹在 AI 与链上世界之间的一套平台。", + "nodes": [ + ("terminal", "AI", 240, 58), + ("auto", "BANK OF AI", 340, 72), + ("terminal", "Web3", 240, 58), + ], + }, + }, +} + + +def stack_svg(spec): + w = 880 + cx = w / 2 + y = 96 + parts = [] + prev = None + for kind, label, bw, bh in spec["nodes"]: + if prev is not None: + parts.append(f' \n') + fill, stroke, _ = KIND[kind] + size = 18 if bh > 60 else 15 + parts.append( + f' \n' + f' \n' + f' {E(label)}\n') + prev = y + bh + y = prev + 38 + h = int(prev + 34) + return head(w, h) + title_block(w, spec["title"], spec["subtitle"]) + "".join(parts) + "\n" + + +CATALOG = { + "en": { + "title": "API Catalog — from a pull request to three consumers", + "subtitle": "The catalog keeps no database and holds no upstream secrets. It makes services discoverable; it never touches calls or funds.", + "cols": ["Provider", "Catalog repo (CI)", "Distribution"], + "col_kinds": ["manual", "auto", "integration"], + "col_body": [ + ["catalog.json", "pay.md", "(two public files)"], + ["field & sensitive-data scan", "build static snapshot dist/"], + ["/api/catalog.json", "/api/providers/.json", "/api/pay/.json · .md"], + ], + "arrows": ["open PR", "publish"], + "fan_label": "same data, three ways in", + "consumers": [ + ("Catalog website", "humans browse & compare"), + ("x402-cli", "search, inspect, paid calls"), + ("MCP", "Agents call services by name"), + ], + }, + "zh": { + "title": "API Catalog —— 从一个 PR 到三个消费端", + "subtitle": "目录本身不存数据库、不接收上游密钥：只负责让服务可被发现，不碰调用也不碰资金。", + "cols": ["服务提供方", "目录仓库（CI）", "分发"], + "col_kinds": ["manual", "auto", "integration"], + "col_body": [ + ["catalog.json", "pay.md", "（两个公开文件）"], + ["字段与敏感信息扫描", "构建静态快照 dist/"], + ["/api/catalog.json", "/api/providers/.json", "/api/pay/.json · .md"], + ], + "arrows": ["提交 PR", "校验发布"], + "fan_label": "同一份数据，三种接入方式", + "consumers": [ + ("目录网站", "供人浏览与比较"), + ("x402-cli", "搜索、查看、付费调用"), + ("MCP", "Agent 按名字直接调用"), + ], + }, +} + + +def catalog_svg(spec): + w = 880 + bw, gap, x0 = 225, 62, 40 + y = 100 + parts = [] + for i, (label, kind, body) in enumerate(zip(spec["cols"], spec["col_kinds"], spec["col_body"])): + x = x0 + i * (bw + gap) + fill, stroke, _ = KIND[kind] + h = 46 + 16 * len(body) + parts.append(f' {E(label.upper() if label.isascii() else label)}\n') + parts.append(f' \n' + f' \n') + for j, line in enumerate(body): + parts.append(f' {E(line)}\n') + if i < 2: + parts.append(harrow(y + h / 2, x + bw + 6, x + bw + gap - 6, + color=KIND[kind][2], label=spec["arrows"][i])) + top_h = 46 + 16 * max(len(b) for b in spec["col_body"]) + dist_cx = x0 + 2 * (bw + gap) + bw / 2 + fan_y = y + top_h + 46 + parts.append(varrow(dist_cx, y + top_h + 4, fan_y - 4, "amber")) + parts.append(f' {E(spec["fan_label"])}\n') + + cw, cgap = bw, gap + cy = fan_y + 44 + parts.append(f' \n') + for i, (name, desc) in enumerate(spec["consumers"]): + x = x0 + i * (cw + cgap) + parts.append(varrow(x + cw / 2, fan_y, cy - 4)) + parts.append(box(x, cy, cw, 58, "generic", name, [desc], badge=None)) + h_total = int(cy + 58 + 30) + return head(w, h_total) + title_block(w, spec["title"], spec["subtitle"]) + "".join(parts) + "\n" + + +GATEWAY = { + "en": { + "title": "Gateway — a cashier and relay in front of your API", + "subtitle": "Technically a reverse proxy. Agents only ever hit the gateway address; your upstream API stays exactly as it is.", + "nodes": [ + ("manual", "Agent", ["pays on-chain from", "its own wallet"]), + ("auto", "Gateway", ["quote / verify / settle", "(paid endpoints only)"]), + ("integration", "Your upstream API", ["unchanged — not one", "line of code"]), + ], + "arrows": ["request", "forwards"], + "notes": [ + ("Never a private key", "Settlement uses a wallet address only. Neither side of the gateway ever touches a private key."), + ("Upstream keys stay isolated", "Your API key lives only gateway-side — local YAML/env if self-hosted, held by us if official. Callers never see it."), + ("You price each endpoint", "Priced endpoints take the 402 flow; unpriced (price 0) endpoints are forwarded straight through."), + ], + }, + "zh": { + "title": "Gateway —— 挡在你 API 前面的收银台兼中继", + "subtitle": "本质是一层反向代理。Agent 只访问网关地址，你的上游 API 保持原样。", + "nodes": [ + ("manual", "Agent", ["用自己的钱包", "在链上付款"]), + ("auto", "Gateway", ["报价 / 校验 / 结算", "（仅付费端点）"]), + ("integration", "你的上游 API", ["完全不改", "一行代码"]), + ], + "arrows": ["请求", "转发"], + "notes": [ + ("永远不碰私钥", "结算只用钱包地址，网关两侧都不接触私钥。"), + ("上游密钥隔离", "API Key 只存在网关一侧 —— 自建则在本地 YAML/env，官方网关则由我们保管，调用方永远看不到。"), + ("价格按端点自定", "标价的端点走 402 流程；未标价（价格为 0）的端点直接转发。"), + ], + }, +} + + +def gateway_svg(spec): + w = 880 + bw, gap, x0 = 206, 80, 50 + y = 106 + parts = [] + for i, (kind, name, desc) in enumerate(spec["nodes"]): + x = x0 + i * (bw + gap) + parts.append(box(x, y, bw, 74, kind, name, desc, badge=None)) + if i < 2: + parts.append(harrow(y + 37, x + bw + 8, x + bw + gap - 8, + color=KIND[kind][2], label=spec["arrows"][i])) + ny = y + 74 + 40 + for i, (head_txt, body) in enumerate(spec["notes"]): + yy = ny + i * 52 + parts.append(f' \n') + parts.append(f' {E(head_txt)}\n') + parts.append(f' ' + f'{E(body)}\n') + h_total = int(ny + len(spec["notes"]) * 52 + 14) + return head(w, h_total) + title_block(w, spec["title"], spec["subtitle"]) + "".join(parts) + "\n" + + +def main(): + outdir = sys.argv[1] + os.makedirs(outdir, exist_ok=True) + written = [] + + def emit(name, lang, theme, svg): + fn = name + ("" if lang == "en" else ".zh") + ("" if theme == "dark" else ".light") + ".svg" + with open(os.path.join(outdir, fn), "w", encoding="utf-8") as f: + f.write(svg) + written.append(fn) + + for theme in ("dark", "light"): + set_theme(theme) + for name, langs in T.items(): + for lang, spec in langs.items(): + emit(name, lang, theme, vflow(spec, lang)) + for lang, spec in A["bank-of-ai-architecture"].items(): + emit("bank-of-ai-architecture", lang, theme, stack_svg(spec)) + for lang, spec in CATALOG.items(): + emit("x402-api-catalog-pipeline", lang, theme, catalog_svg(spec)) + for lang, spec in GATEWAY.items(): + emit("x402-gateway-topology", lang, theme, gateway_svg(spec)) + + print(len(written), "files") + + +if __name__ == "__main__": + main() diff --git a/static/img/diagrams/agent-wallet-evm-flow.light.svg b/static/img/diagrams/agent-wallet-evm-flow.light.svg new file mode 100644 index 00000000..56340e6d --- /dev/null +++ b/static/img/diagrams/agent-wallet-evm-flow.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EVM transfer — where Agent-wallet fits + BSC / Ethereum / Polygon / Base — only RPC_URL and CHAIN_ID change. + + + RPC — build + Query nonce / gas / chainId and assemble the tx yourself + + 1 + NETWORK + + unsigned tx + + + Agent-wallet — sign + Returns a hex-encoded signed transaction + + 2 + LOCAL + + signed tx + + + RPC — sendRawTransaction + Broadcast the signed transaction to the network + + 3 + NETWORK + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-evm-flow.svg b/static/img/diagrams/agent-wallet-evm-flow.svg new file mode 100644 index 00000000..402460c1 --- /dev/null +++ b/static/img/diagrams/agent-wallet-evm-flow.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EVM transfer — where Agent-wallet fits + BSC / Ethereum / Polygon / Base — only RPC_URL and CHAIN_ID change. + + + RPC — build + Query nonce / gas / chainId and assemble the tx yourself + + 1 + NETWORK + + unsigned tx + + + Agent-wallet — sign + Returns a hex-encoded signed transaction + + 2 + LOCAL + + signed tx + + + RPC — sendRawTransaction + Broadcast the signed transaction to the network + + 3 + NETWORK + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-evm-flow.zh.light.svg b/static/img/diagrams/agent-wallet-evm-flow.zh.light.svg new file mode 100644 index 00000000..0f2ad116 --- /dev/null +++ b/static/img/diagrams/agent-wallet-evm-flow.zh.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EVM 转账 —— Agent-wallet 在哪一步 + BSC / Ethereum / Polygon / Base —— 只需替换 RPC_URL 与 CHAIN_ID。 + + + RPC — 构造 + 查询 nonce / gas / chainId，自行组装交易对象 + + 1 + 网络 + + 未签名交易 + + + Agent-wallet — 签名 + 返回 hex 编码的已签名交易 + + 2 + 本地 + + 已签名交易 + + + RPC — sendRawTransaction + 将已签名交易广播到网络 + + 3 + 网络 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/diagrams/agent-wallet-evm-flow.zh.svg b/static/img/diagrams/agent-wallet-evm-flow.zh.svg new file mode 100644 index 00000000..44e83514 --- /dev/null +++ b/static/img/diagrams/agent-wallet-evm-flow.zh.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EVM 转账 —— Agent-wallet 在哪一步 + BSC / Ethereum / Polygon / Base —— 只需替换 RPC_URL 与 CHAIN_ID。 + + + RPC — 构造 + 查询 nonce / gas / chainId，自行组装交易对象 + + 1 + 网络 + + 未签名交易 + + + Agent-wallet — 签名 + 返回 hex 编码的已签名交易 + + 2 + 本地 + + 已签名交易 + + + RPC — sendRawTransaction + 将已签名交易广播到网络 + + 3 + 网络 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/diagrams/agent-wallet-tron-flow.light.svg b/static/img/diagrams/agent-wallet-tron-flow.light.svg new file mode 100644 index 00000000..abf44830 --- /dev/null +++ b/static/img/diagrams/agent-wallet-tron-flow.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TRON transfer — where Agent-wallet fits + Agent-wallet only signs. It needs no RPC connection and knows nothing about the business meaning. + + + TronGrid — build + createtransaction returns an unsigned tx (txID + raw_data) + + 1 + NETWORK + + unsigned tx + + + Agent-wallet — sign + Fully offline; the private key never leaves the machine + + 2 + LOCAL + + signed tx + + + TronGrid — broadcast + broadcasttransaction publishes it on chain + + 3 + NETWORK + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-tron-flow.svg b/static/img/diagrams/agent-wallet-tron-flow.svg new file mode 100644 index 00000000..a1259ad2 --- /dev/null +++ b/static/img/diagrams/agent-wallet-tron-flow.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TRON transfer — where Agent-wallet fits + Agent-wallet only signs. It needs no RPC connection and knows nothing about the business meaning. + + + TronGrid — build + createtransaction returns an unsigned tx (txID + raw_data) + + 1 + NETWORK + + unsigned tx + + + Agent-wallet — sign + Fully offline; the private key never leaves the machine + + 2 + LOCAL + + signed tx + + + TronGrid — broadcast + broadcasttransaction publishes it on chain + + 3 + NETWORK + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-tron-flow.zh.light.svg b/static/img/diagrams/agent-wallet-tron-flow.zh.light.svg new file mode 100644 index 00000000..6129f3d3 --- /dev/null +++ b/static/img/diagrams/agent-wallet-tron-flow.zh.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TRON 转账 —— Agent-wallet 在哪一步 + Agent-wallet 只负责签名，不需要 RPC 连接，也不感知交易的业务含义。 + + + TronGrid — 构造 + createtransaction 返回未签名交易（txID + raw_data） + + 1 + 网络 + + 未签名交易 + + + Agent-wallet — 签名 + 完全离线，私钥不出本机 + + 2 + 本地 + + 已签名交易 + + + TronGrid — 广播 + broadcasttransaction 发布上链 + + 3 + 网络 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/diagrams/agent-wallet-tron-flow.zh.svg b/static/img/diagrams/agent-wallet-tron-flow.zh.svg new file mode 100644 index 00000000..490fc680 --- /dev/null +++ b/static/img/diagrams/agent-wallet-tron-flow.zh.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TRON 转账 —— Agent-wallet 在哪一步 + Agent-wallet 只负责签名，不需要 RPC 连接，也不感知交易的业务含义。 + + + TronGrid — 构造 + createtransaction 返回未签名交易（txID + raw_data） + + 1 + 网络 + + 未签名交易 + + + Agent-wallet — 签名 + 完全离线，私钥不出本机 + + 2 + 本地 + + 已签名交易 + + + TronGrid — 广播 + broadcasttransaction 发布上链 + + 3 + 网络 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg new file mode 100644 index 00000000..6c8b41de --- /dev/null +++ b/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 PaymentPermit signing + Sign first, verify to proceed — the agent never waits for on-chain confirmation. + + + Server returns 402 + Payment parameters come back with the 402 response + + 1 + SERVER + + + + Agent builds PaymentPermit + TransferWithAuthorization struct, EIP-712 format + + 2 + x402 SDK + + + + Agent-wallet signs + The only step Agent-wallet is responsible for + + 3 + LOCAL + + + + Resend request with signature + The signature travels as the payment credential + + 4 + AGENT + + + + Server verifies and responds + Content returned only if the signature checks out + + 5 + SERVER + + User / manual step + + AI / automated step + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.svg new file mode 100644 index 00000000..956ed10c --- /dev/null +++ b/static/img/diagrams/agent-wallet-x402-permit-flow.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 PaymentPermit signing + Sign first, verify to proceed — the agent never waits for on-chain confirmation. + + + Server returns 402 + Payment parameters come back with the 402 response + + 1 + SERVER + + + + Agent builds PaymentPermit + TransferWithAuthorization struct, EIP-712 format + + 2 + x402 SDK + + + + Agent-wallet signs + The only step Agent-wallet is responsible for + + 3 + LOCAL + + + + Resend request with signature + The signature travels as the payment credential + + 4 + AGENT + + + + Server verifies and responds + Content returned only if the signature checks out + + 5 + SERVER + + User / manual step + + AI / automated step + + Local signing (private key) + diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg new file mode 100644 index 00000000..583ae1d0 --- /dev/null +++ b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 PaymentPermit 签名 + 先签名、验证通过再放行 —— Agent 无需等待链上确认。 + + + 服务端返回 402 + 402 响应中带回支付参数 + + 1 + 服务端 + + + + Agent 构造 PaymentPermit + TransferWithAuthorization 结构，EIP-712 格式 + + 2 + x402 SDK + + + + Agent-wallet 签名 + Agent-wallet 只负责这一步 + + 3 + 本地 + + + + 携带签名重发请求 + 签名作为支付凭证随请求发送 + + 4 + AGENT + + + + 服务端验证并响应 + 签名有效才返回内容 + + 5 + 服务端 + + 用户 / 手动步骤 + + AI / 自动步骤 + + 本地签名（私钥） + diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg new file mode 100644 index 00000000..8963c1f8 --- /dev/null +++ b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 PaymentPermit 签名 + 先签名、验证通过再放行 —— Agent 无需等待链上确认。 + + + 服务端返回 402 + 402 响应中带回支付参数 + + 1 + 服务端 + + + + Agent 构造 PaymentPermit + TransferWithAuthorization 结构，EIP-712 格式 + + 2 + x402 SDK + + + + Agent-wallet 签名 + Agent-wallet 只负责这一步 + + 3 + 本地 + + + + 携带签名重发请求 + 签名作为支付凭证随请求发送 + + 4 + AGENT + + + + 服务端验证并响应 + 签名有效才返回内容 + + 5 + 服务端 + + 用户 / 手动步骤 + + AI / 自动步骤 + + 本地签名（私钥） + diff --git a/static/img/diagrams/bank-of-ai-architecture.light.svg b/static/img/diagrams/bank-of-ai-architecture.light.svg new file mode 100644 index 00000000..e6b4c286 --- /dev/null +++ b/static/img/diagrams/bank-of-ai-architecture.light.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — the whole picture + One platform sitting between your AI and the on-chain world. + + + AI + + + + BANK OF AI + + + + Web3 + diff --git a/static/img/diagrams/bank-of-ai-architecture.svg b/static/img/diagrams/bank-of-ai-architecture.svg new file mode 100644 index 00000000..8b6e054c --- /dev/null +++ b/static/img/diagrams/bank-of-ai-architecture.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — the whole picture + One platform sitting between your AI and the on-chain world. + + + AI + + + + BANK OF AI + + + + Web3 + diff --git a/static/img/diagrams/bank-of-ai-architecture.zh.light.svg b/static/img/diagrams/bank-of-ai-architecture.zh.light.svg new file mode 100644 index 00000000..3cb9733c --- /dev/null +++ b/static/img/diagrams/bank-of-ai-architecture.zh.light.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI —— 整体架构 + 夹在 AI 与链上世界之间的一套平台。 + + + AI + + + + BANK OF AI + + + + Web3 + diff --git a/static/img/diagrams/bank-of-ai-architecture.zh.svg b/static/img/diagrams/bank-of-ai-architecture.zh.svg new file mode 100644 index 00000000..2ac0dcb8 --- /dev/null +++ b/static/img/diagrams/bank-of-ai-architecture.zh.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI —— 整体架构 + 夹在 AI 与链上世界之间的一套平台。 + + + AI + + + + BANK OF AI + + + + Web3 + diff --git a/static/img/diagrams/bank-of-ai-execution-flow.light.svg b/static/img/diagrams/bank-of-ai-execution-flow.light.svg new file mode 100644 index 00000000..feb47fd6 --- /dev/null +++ b/static/img/diagrams/bank-of-ai-execution-flow.light.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — one execution, end to end + Example: "Swap 100 USDT for TRX, keep slippage under 1%." + + + You state the goal + + + + AI interprets the request + Parses intent, amount, network and slippage limit + + 1 + LLM + + + + Selects a Skill or calls an MCP Server + Skill = business SOP · MCP Server = on-chain capability + + 2 + ORCHESTRATION + + + + Agent Wallet signs + Signed locally — the private key never leaves your machine + + 3 + WALLET + + + + Transaction broadcast + Signed transaction submitted to a network node + + 4 + RPC + + + + Blockchain + Executed and confirmed on chain + + 5 + CHAIN + + + + Result returned to you + + AI / automated step + + Network / external API + + Local signing (private key) + + Start / end + diff --git a/static/img/diagrams/bank-of-ai-execution-flow.svg b/static/img/diagrams/bank-of-ai-execution-flow.svg new file mode 100644 index 00000000..bac864db --- /dev/null +++ b/static/img/diagrams/bank-of-ai-execution-flow.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — one execution, end to end + Example: "Swap 100 USDT for TRX, keep slippage under 1%." + + + You state the goal + + + + AI interprets the request + Parses intent, amount, network and slippage limit + + 1 + LLM + + + + Selects a Skill or calls an MCP Server + Skill = business SOP · MCP Server = on-chain capability + + 2 + ORCHESTRATION + + + + Agent Wallet signs + Signed locally — the private key never leaves your machine + + 3 + WALLET + + + + Transaction broadcast + Signed transaction submitted to a network node + + 4 + RPC + + + + Blockchain + Executed and confirmed on chain + + 5 + CHAIN + + + + Result returned to you + + AI / automated step + + Network / external API + + Local signing (private key) + + Start / end + diff --git a/static/img/diagrams/bank-of-ai-execution-flow.zh.light.svg b/static/img/diagrams/bank-of-ai-execution-flow.zh.light.svg new file mode 100644 index 00000000..36d30c80 --- /dev/null +++ b/static/img/diagrams/bank-of-ai-execution-flow.zh.light.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — 一次完整执行 + 示例：把 100 USDT 换成 TRX，滑点不超过 1%。 + + + 你说出目标 + + + + AI 理解需求 + 解析意图、金额、网络与滑点上限 + + 1 + 大模型 + + + + 选择 Skill 或调用 MCP Server + Skill = 业务流程 · MCP Server = 链上能力 + + 2 + 编排层 + + + + Agent Wallet 签名 + 本地签名，私钥不出本机 + + 3 + 钱包 + + + + 广播交易 + 已签名交易提交给网络节点 + + 4 + 节点 + + + + 区块链 + 链上执行并确认 + + 5 + 链 + + + + 结果返回给你 + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + + 起点 / 终点 + diff --git a/static/img/diagrams/bank-of-ai-execution-flow.zh.svg b/static/img/diagrams/bank-of-ai-execution-flow.zh.svg new file mode 100644 index 00000000..0bdbbc48 --- /dev/null +++ b/static/img/diagrams/bank-of-ai-execution-flow.zh.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BANK OF AI — 一次完整执行 + 示例：把 100 USDT 换成 TRX，滑点不超过 1%。 + + + 你说出目标 + + + + AI 理解需求 + 解析意图、金额、网络与滑点上限 + + 1 + 大模型 + + + + 选择 Skill 或调用 MCP Server + Skill = 业务流程 · MCP Server = 链上能力 + + 2 + 编排层 + + + + Agent Wallet 签名 + 本地签名，私钥不出本机 + + 3 + 钱包 + + + + 广播交易 + 已签名交易提交给网络节点 + + 4 + 节点 + + + + 区块链 + 链上执行并确认 + + 5 + 链 + + + + 结果返回给你 + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + + 起点 / 终点 + diff --git a/static/img/diagrams/x402-api-catalog-pipeline.light.svg b/static/img/diagrams/x402-api-catalog-pipeline.light.svg new file mode 100644 index 00000000..2504efa6 --- /dev/null +++ b/static/img/diagrams/x402-api-catalog-pipeline.light.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + API Catalog — from a pull request to three consumers + The catalog keeps no database and holds no upstream secrets. It makes services discoverable; it never touches calls or funds. + PROVIDER + + + catalog.json + pay.md + (two public files) + + open PR + CATALOG REPO (CI) + + + field & sensitive-data scan + build static snapshot dist/ + + publish + DISTRIBUTION + + + /api/catalog.json + /api/providers/<fqn>.json + /api/pay/<fqn>.json · .md + + same data, three ways in + + + + + Catalog website + humans browse & compare + + + + x402-cli + search, inspect, paid calls + + + + MCP + Agents call services by name + diff --git a/static/img/diagrams/x402-api-catalog-pipeline.svg b/static/img/diagrams/x402-api-catalog-pipeline.svg new file mode 100644 index 00000000..ec765829 --- /dev/null +++ b/static/img/diagrams/x402-api-catalog-pipeline.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + API Catalog — from a pull request to three consumers + The catalog keeps no database and holds no upstream secrets. It makes services discoverable; it never touches calls or funds. + PROVIDER + + + catalog.json + pay.md + (two public files) + + open PR + CATALOG REPO (CI) + + + field & sensitive-data scan + build static snapshot dist/ + + publish + DISTRIBUTION + + + /api/catalog.json + /api/providers/<fqn>.json + /api/pay/<fqn>.json · .md + + same data, three ways in + + + + + Catalog website + humans browse & compare + + + + x402-cli + search, inspect, paid calls + + + + MCP + Agents call services by name + diff --git a/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg b/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg new file mode 100644 index 00000000..0d0941c9 --- /dev/null +++ b/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + API Catalog —— 从一个 PR 到三个消费端 + 目录本身不存数据库、不接收上游密钥：只负责让服务可被发现，不碰调用也不碰资金。 + 服务提供方 + + + catalog.json + pay.md + （两个公开文件） + + 提交 PR + 目录仓库（CI） + + + 字段与敏感信息扫描 + 构建静态快照 dist/ + + 校验发布 + 分发 + + + /api/catalog.json + /api/providers/<fqn>.json + /api/pay/<fqn>.json · .md + + 同一份数据，三种接入方式 + + + + + 目录网站 + 供人浏览与比较 + + + + x402-cli + 搜索、查看、付费调用 + + + + MCP + Agent 按名字直接调用 + diff --git a/static/img/diagrams/x402-api-catalog-pipeline.zh.svg b/static/img/diagrams/x402-api-catalog-pipeline.zh.svg new file mode 100644 index 00000000..258ba913 --- /dev/null +++ b/static/img/diagrams/x402-api-catalog-pipeline.zh.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + API Catalog —— 从一个 PR 到三个消费端 + 目录本身不存数据库、不接收上游密钥：只负责让服务可被发现，不碰调用也不碰资金。 + 服务提供方 + + + catalog.json + pay.md + （两个公开文件） + + 提交 PR + 目录仓库（CI） + + + 字段与敏感信息扫描 + 构建静态快照 dist/ + + 校验发布 + 分发 + + + /api/catalog.json + /api/providers/<fqn>.json + /api/pay/<fqn>.json · .md + + 同一份数据，三种接入方式 + + + + + 目录网站 + 供人浏览与比较 + + + + x402-cli + 搜索、查看、付费调用 + + + + MCP + Agent 按名字直接调用 + diff --git a/static/img/diagrams/x402-gateway-topology.light.svg b/static/img/diagrams/x402-gateway-topology.light.svg new file mode 100644 index 00000000..503da74a --- /dev/null +++ b/static/img/diagrams/x402-gateway-topology.light.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway — a cashier and relay in front of your API + Technically a reverse proxy. Agents only ever hit the gateway address; your upstream API stays exactly as it is. + + + Agent + pays on-chain from + its own wallet + + request + + + Gateway + quote / verify / settle + (paid endpoints only) + + forwards + + + Your upstream API + unchanged — not one + line of code + + Never a private key + Settlement uses a wallet address only. Neither side of the gateway ever touches a private key. + + Upstream keys stay isolated + Your API key lives only gateway-side — local YAML/env if self-hosted, held by us if official. Callers never see it. + + You price each endpoint + Priced endpoints take the 402 flow; unpriced (price 0) endpoints are forwarded straight through. + diff --git a/static/img/diagrams/x402-gateway-topology.svg b/static/img/diagrams/x402-gateway-topology.svg new file mode 100644 index 00000000..7e75c81f --- /dev/null +++ b/static/img/diagrams/x402-gateway-topology.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway — a cashier and relay in front of your API + Technically a reverse proxy. Agents only ever hit the gateway address; your upstream API stays exactly as it is. + + + Agent + pays on-chain from + its own wallet + + request + + + Gateway + quote / verify / settle + (paid endpoints only) + + forwards + + + Your upstream API + unchanged — not one + line of code + + Never a private key + Settlement uses a wallet address only. Neither side of the gateway ever touches a private key. + + Upstream keys stay isolated + Your API key lives only gateway-side — local YAML/env if self-hosted, held by us if official. Callers never see it. + + You price each endpoint + Priced endpoints take the 402 flow; unpriced (price 0) endpoints are forwarded straight through. + diff --git a/static/img/diagrams/x402-gateway-topology.zh.light.svg b/static/img/diagrams/x402-gateway-topology.zh.light.svg new file mode 100644 index 00000000..978f965a --- /dev/null +++ b/static/img/diagrams/x402-gateway-topology.zh.light.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway —— 挡在你 API 前面的收银台兼中继 + 本质是一层反向代理。Agent 只访问网关地址，你的上游 API 保持原样。 + + + Agent + 用自己的钱包 + 在链上付款 + + 请求 + + + Gateway + 报价 / 校验 / 结算 + （仅付费端点） + + 转发 + + + 你的上游 API + 完全不改 + 一行代码 + + 永远不碰私钥 + 结算只用钱包地址，网关两侧都不接触私钥。 + + 上游密钥隔离 + API Key 只存在网关一侧 —— 自建则在本地 YAML/env，官方网关则由我们保管，调用方永远看不到。 + + 价格按端点自定 + 标价的端点走 402 流程；未标价（价格为 0）的端点直接转发。 + diff --git a/static/img/diagrams/x402-gateway-topology.zh.svg b/static/img/diagrams/x402-gateway-topology.zh.svg new file mode 100644 index 00000000..e50fd36a --- /dev/null +++ b/static/img/diagrams/x402-gateway-topology.zh.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gateway —— 挡在你 API 前面的收银台兼中继 + 本质是一层反向代理。Agent 只访问网关地址，你的上游 API 保持原样。 + + + Agent + 用自己的钱包 + 在链上付款 + + 请求 + + + Gateway + 报价 / 校验 / 结算 + （仅付费端点） + + 转发 + + + 你的上游 API + 完全不改 + 一行代码 + + 永远不碰私钥 + 结算只用钱包地址，网关两侧都不接触私钥。 + + 上游密钥隔离 + API Key 只存在网关一侧 —— 自建则在本地 YAML/env，官方网关则由我们保管，调用方永远看不到。 + + 价格按端点自定 + 标价的端点走 402 流程；未标价（价格为 0）的端点直接转发。 + diff --git a/static/img/diagrams/x402-payment-flow.light.svg b/static/img/diagrams/x402-payment-flow.light.svg new file mode 100644 index 00000000..4181aa9f --- /dev/null +++ b/static/img/diagrams/x402-payment-flow.light.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 payment flow + How a client, a server and the Facilitator settle one paid HTTP request + + + Client wants a paid resource + + + + Client initiates request + Plain HTTP request, no payment attached yet + + 1 + CLIENT + + 402 + + + Server requires payment + 402 Payment Required · details in PAYMENT-REQUIRED (Base64) + + 2 + SERVER + + sign + + + Client submits payment + Signs the payload, resends it in PAYMENT-SIGNATURE + + 3 + CLIENT + + /verify + + + Server validates payment + Facilitator /verify — signature and payload integrity + + 4 + FACILITATOR + + /settle + + + Server executes settlement + Facilitator /settle — transaction submitted on chain + + 5 + FACILITATOR + + + + Server delivers the resource + Response carries the tx hash in PAYMENT-RESPONSE + + 6 + SERVER + + + + Resource delivered + + User / manual step + + AI / automated step + + Network / external API + + Local signing (private key) + + Start / end + diff --git a/static/img/diagrams/x402-payment-flow.svg b/static/img/diagrams/x402-payment-flow.svg new file mode 100644 index 00000000..300fb392 --- /dev/null +++ b/static/img/diagrams/x402-payment-flow.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 payment flow + How a client, a server and the Facilitator settle one paid HTTP request + + + Client wants a paid resource + + + + Client initiates request + Plain HTTP request, no payment attached yet + + 1 + CLIENT + + 402 + + + Server requires payment + 402 Payment Required · details in PAYMENT-REQUIRED (Base64) + + 2 + SERVER + + sign + + + Client submits payment + Signs the payload, resends it in PAYMENT-SIGNATURE + + 3 + CLIENT + + /verify + + + Server validates payment + Facilitator /verify — signature and payload integrity + + 4 + FACILITATOR + + /settle + + + Server executes settlement + Facilitator /settle — transaction submitted on chain + + 5 + FACILITATOR + + + + Server delivers the resource + Response carries the tx hash in PAYMENT-RESPONSE + + 6 + SERVER + + + + Resource delivered + + User / manual step + + AI / automated step + + Network / external API + + Local signing (private key) + + Start / end + diff --git a/static/img/diagrams/x402-payment-flow.zh.light.svg b/static/img/diagrams/x402-payment-flow.zh.light.svg new file mode 100644 index 00000000..b46bee7d --- /dev/null +++ b/static/img/diagrams/x402-payment-flow.zh.light.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 支付流程 + 客户端、服务端与 Facilitator 如何结算一次付费 HTTP 请求 + + + 客户端请求付费资源 + + + + 客户端发起请求 + 普通 HTTP 请求，尚未携带支付凭证 + + 1 + 客户端 + + 402 + + + 服务端要求付款 + 返回 402 · 支付详情放在 PAYMENT-REQUIRED（Base64） + + 2 + 服务端 + + 签名 + + + 客户端提交支付 + 生成签名，通过 PAYMENT-SIGNATURE 重发请求 + + 3 + 客户端 + + /verify + + + 服务端校验支付 + 调用 Facilitator /verify 校验签名与载荷完整性 + + 4 + FACILITATOR + + /settle + + + 服务端执行结算 + 调用 Facilitator /settle，交易提交上链 + + 5 + FACILITATOR + + + + 服务端交付资源 + 响应在 PAYMENT-RESPONSE 中带回交易哈希 + + 6 + 服务端 + + + + 资源交付完成 + + 用户 / 手动步骤 + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + + 起点 / 终点 + diff --git a/static/img/diagrams/x402-payment-flow.zh.svg b/static/img/diagrams/x402-payment-flow.zh.svg new file mode 100644 index 00000000..5fc82117 --- /dev/null +++ b/static/img/diagrams/x402-payment-flow.zh.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + x402 支付流程 + 客户端、服务端与 Facilitator 如何结算一次付费 HTTP 请求 + + + 客户端请求付费资源 + + + + 客户端发起请求 + 普通 HTTP 请求，尚未携带支付凭证 + + 1 + 客户端 + + 402 + + + 服务端要求付款 + 返回 402 · 支付详情放在 PAYMENT-REQUIRED（Base64） + + 2 + 服务端 + + 签名 + + + 客户端提交支付 + 生成签名，通过 PAYMENT-SIGNATURE 重发请求 + + 3 + 客户端 + + /verify + + + 服务端校验支付 + 调用 Facilitator /verify 校验签名与载荷完整性 + + 4 + FACILITATOR + + /settle + + + 服务端执行结算 + 调用 Facilitator /settle，交易提交上链 + + 5 + FACILITATOR + + + + 服务端交付资源 + 响应在 PAYMENT-RESPONSE 中带回交易哈希 + + 6 + 服务端 + + + + 资源交付完成 + + 用户 / 手动步骤 + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + + 起点 / 终点 + diff --git a/static/img/diagrams/x402-payment-scheme-flow.light.svg b/static/img/diagrams/x402-payment-scheme-flow.light.svg new file mode 100644 index 00000000..fedf7dea --- /dev/null +++ b/static/img/diagrams/x402-payment-scheme-flow.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How payment schemes work + exact · upto · batch-settlement · GasFree — same three beats, different settlement call + + + Authorize + Client signs typed data: an exact amount, or a maximum for upto / batch + + 1 + CLIENT + + + + Execute + Server performs the task and, for usage-based schemes, computes actual cost + + 2 + SERVER + + + + Settle + transferWithAuthorization · Permit2 permitTransferFrom · batch claim · GasFree relay + + 3 + FACILITATOR + + AI / automated step + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/x402-payment-scheme-flow.svg b/static/img/diagrams/x402-payment-scheme-flow.svg new file mode 100644 index 00000000..9b83d450 --- /dev/null +++ b/static/img/diagrams/x402-payment-scheme-flow.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How payment schemes work + exact · upto · batch-settlement · GasFree — same three beats, different settlement call + + + Authorize + Client signs typed data: an exact amount, or a maximum for upto / batch + + 1 + CLIENT + + + + Execute + Server performs the task and, for usage-based schemes, computes actual cost + + 2 + SERVER + + + + Settle + transferWithAuthorization · Permit2 permitTransferFrom · batch claim · GasFree relay + + 3 + FACILITATOR + + AI / automated step + + Network / external API + + Local signing (private key) + diff --git a/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg b/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg new file mode 100644 index 00000000..fe509bcc --- /dev/null +++ b/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 支付方案如何运作 + exact · upto · batch-settlement · GasFree —— 同样三拍，结算调用不同 + + + 授权 Authorize + 客户端签名 typed data：固定金额，或 upto / batch 的上限 + + 1 + 客户端 + + + + 执行 Execute + 服务端执行任务；按量计费方案还会计算实际费用 + + 2 + 服务端 + + + + 结算 Settle + transferWithAuthorization · Permit2 · 批量领取 · GasFree 中继 + + 3 + FACILITATOR + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/diagrams/x402-payment-scheme-flow.zh.svg b/static/img/diagrams/x402-payment-scheme-flow.zh.svg new file mode 100644 index 00000000..ef7d242c --- /dev/null +++ b/static/img/diagrams/x402-payment-scheme-flow.zh.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 支付方案如何运作 + exact · upto · batch-settlement · GasFree —— 同样三拍，结算调用不同 + + + 授权 Authorize + 客户端签名 typed data：固定金额，或 upto / batch 的上限 + + 1 + 客户端 + + + + 执行 Execute + 服务端执行任务；按量计费方案还会计算实际费用 + + 2 + 服务端 + + + + 结算 Settle + transferWithAuthorization · Permit2 · 批量领取 · GasFree 中继 + + 3 + FACILITATOR + + AI / 自动步骤 + + 网络 / 外部接口 + + 本地签名（私钥） + diff --git a/static/img/favicon.svg b/static/img/favicon.svg deleted file mode 100644 index c5c90f3f..00000000 --- a/static/img/favicon.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - 402 - diff --git a/static/img/twitter_card_bg.jpg b/static/img/twitter_card_bg.jpg deleted file mode 100644 index e69de29b..00000000