diff --git a/changelog/index.md b/changelog/index.md
index b03016b..4498614 100644
--- a/changelog/index.md
+++ b/changelog/index.md
@@ -7,6 +7,33 @@ description: 'Product updates and announcements for BANK OF AI — all products,
 
 Product updates and announcements for BANK OF AI.
 
+<div className="changelog-entry">
+<div className="changelog-date">Aug 25, 2026</div>
+<div className="changelog-body">
+
+### x402 SDK v1.1.0 · Docs
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">x402</span><span className="changelog-tag">Docs</span></div>
+
+- **x402 SDK 1.1.0** — explicit payment flows (`upfront` / `escrow` on the wire as `extra.paymentFlow`, `authorization` by default), client spend controls on by default (`$1` per-payment cap, default-asset allowlist), payment-selection policies and lifecycle hooks, EVM smart-account support (ERC-7702, allowlisted ERC-6492), and a 90-second `HTTPFacilitatorClient` timeout. Upgrade all 11 packages together; Node.js 22+. [SDK Feature Matrix](../x402/sdk-features/)
+- **Docs corrections** — removed the obsolete facilitator-fee material (`base_fee`, `extra.fee`, `/fee/quote`); the anonymous `/settle` limit is 1 request/minute on the official deployment; GasFree is no longer described as auto-preferred — the CLI takes the first advertised requirement matching your filters, so pass `--scheme exact_gasfree` to force it; TRON Shasta is now documented as signed by the SDK/CLI but **not** settled by the official facilitator (use Nile or self-host); the CLI page now states its **pinned** dependencies — CLI 1.0.2 still bundles the `@bankofai/x402-*` SDK packages at 1.0.1 (`@bankofai/x402-gateway` at 1.0.2), so it does not yet carry the 1.1.0 client spend controls; and the Skills pages now install with `npx skills add … -g`. [x402 docs](../x402/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Aug 20, 2026</div>
+<div className="changelog-body">
+
+### Facilitator — BSC receipt reliability
+
+<div className="changelog-tags"><span className="changelog-tag">Fix</span><span className="changelog-tag">Facilitator</span></div>
+
+- Settlement receipt lookups on **BSC Mainnet** (`eip155:56`) fall back to a secondary RPC endpoint, so one unresponsive node no longer turns a settled payment into a failed one. [Official Facilitator](../x402/core-concepts/OfficialFacilitator/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 30, 2026</div>
 <div className="changelog-body">
@@ -22,13 +49,29 @@ Product updates and announcements for BANK OF AI.
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">Jul 29, 2026</div>
+<div className="changelog-body">
+
+### Official Facilitator — Base settlement
+
+<div className="changelog-tags"><span className="changelog-tag">Update</span><span className="changelog-tag">Facilitator</span><span className="changelog-tag">Base</span></div>
+
+- The official facilitator now settles **Base USDC** — `eip155:8453` (Mainnet) and `eip155:84532` (Sepolia) are enabled alongside TRON Mainnet/Nile and BSC Mainnet/Testnet. The bundled example facilitator still registers only `eip155:97` and `eip155:56` on the EVM side, so self-hosting Base sellers must add the Base ids themselves. [Official Facilitator](../x402/core-concepts/OfficialFacilitator/)
+- **Breaking for self-hosters** — the facilitator config now takes canonical CAIP-2 ids only; friendly aliases such as `bsc:mainnet` and `tron:nile` are no longer resolved and are rejected at startup.
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 21, 2026</div>
 <div className="changelog-body">
 
 ### Docs
 
-<div className="changelog-tags"><span className="changelog-tag">Product Updates</span><span className="changelog-tag">Docs</span><span className="changelog-tag">x402</span></div>
+<div className="changelog-tags"><span className="changelog-tag">Product Updates</span><span className="changelog-tag">Docs</span><span className="changelog-tag">x402</span><span className="changelog-tag">SKILLS</span></div>
+
+- **SKILLS — `x402-payment` now pays through `x402-cli`** (1.0.1 or newer) instead of bundled local scripts, with a `--dry-run` preview, `--max-amount` caps, a required GasFree fee cap, and canonical CAIP-2 TRON ids. [Details](./skills/)
 
 - **TRON network IDs now use CAIP-2 format** across the x402 docs — `tron:0x2b6653dc` (Mainnet), `tron:0xcd8690dc` (Nile), `tron:0x94a9059e` (Shasta). In application code, prefer the SDK constants `TRON_MAINNET` / `TRON_NILE` / `TRON_SHASTA` over hard-coded hex strings. [Network & Token Support](../x402/core-concepts/network-and-token-support/)
 - **`auth-capture` scheme removed** — x402 now documents four payment schemes: `exact`, `upto`, `batch-settlement`, and `exact_gasfree` (TRON). [SDK Features](../x402/sdk-features/)
diff --git a/changelog/skills.md b/changelog/skills.md
index a97e5f5..483e6d8 100644
--- a/changelog/skills.md
+++ b/changelog/skills.md
@@ -7,6 +7,24 @@ description: 'Release notes for SKILLS.'
 
 Release notes for SKILLS.
 
+<div className="changelog-entry">
+<div className="changelog-date">Jul 21, 2026</div>
+<div className="changelog-body">
+
+### x402-payment now runs on the x402 CLI
+
+<div className="changelog-tags"><span className="changelog-tag">Update</span><span className="changelog-tag">x402</span></div>
+
+- **Payments go through `x402-cli`** (1.0.1 or newer) instead of bundled local TypeScript scripts. The skill checks your installed version and tells you how to install the CLI when it is missing.
+- **Every payment is previewed and capped** — a `--dry-run --json` preview before the first payment to an unfamiliar endpoint, and `--max-amount` on the real request. GasFree payments must also cap the relayer fee with `--max-gasfree-fee`, which the payment cap does not cover.
+- **Canonical CAIP-2 TRON identifiers only** — `tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`. Shorthand aliases such as `tron:mainnet` are rejected. The `agent-wallet` skill uses the same identifiers.
+- The retired `--gasfree-info` / `--gasfree-activate` script flags are gone, and uninstall now handles custom skill directories.
+
+👉 [Skill Catalog](/McpServer-Skills/SKILLS/BANKOFAISkill/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 10, 2026</div>
 <div className="changelog-body">
diff --git a/changelog/x402.md b/changelog/x402.md
index 976e016..72ee9e8 100644
--- a/changelog/x402.md
+++ b/changelog/x402.md
@@ -7,6 +7,39 @@ description: 'Release notes for the x402 payment protocol, SDK, and CLI.'
 
 Release notes for the x402 protocol, SDK, and [CLI](/x402/cli/).
 
+<div className="changelog-entry">
+<div className="changelog-date">Aug 25, 2026</div>
+<div className="changelog-body">
+
+### x402 SDK v1.1.0 — payment flows & wallet compatibility
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">SDK</span></div>
+
+- **Payment flows are now explicit** — a scheme/network server declares the flows it supports per asset-transfer method. `upfront` and `escrow` travel on the wire as `extra.paymentFlow`; `authorization` stays the default and is omitted from `extra`. Legacy v1.0 servers that declare nothing keep using the authorization flow.
+- **Client spend controls are on by default** — a client pays only assets it recognizes from the default-asset registry, capped at `DEFAULT_MAX_AMOUNT_PER_PAYMENT` (`$1` worth) per payment. Raise the cap with `spendControls.maxAmountPerPayment`, allow a custom token with `spendControls.allowedAssets`, or switch the guard off with `spendControls: false`.
+- **Payment-selection policies and lifecycle hooks** — `PaymentPolicy` plus `onBeforePaymentCreation` / `onAfterPaymentCreation` / `onPaymentCreationFailure` / `onPaymentResponse`.
+- **EVM wallet compatibility** — deployed smart accounts, ERC-7702 delegation, and allowlisted ERC-6492 counterfactual wallets. ERC-6492 requires an explicit `eip6492AllowedFactories` allowlist on the facilitator.
+- **`HTTPFacilitatorClient`** gains typed timeout errors, rate-limit retries, stricter response validation, and a 90-second default timeout.
+- Upgrade all **11 `@bankofai/x402-*` packages together** — internal dependencies resolve to `~1.1.0`. The SDK requires **Node.js 22+**. Custom money parsers now receive decimal strings.
+
+👉 [SDK Feature Matrix](/x402/sdk-features/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Aug 20, 2026</div>
+<div className="changelog-body">
+
+### Facilitator — BSC receipt reliability
+
+<div className="changelog-tags"><span className="changelog-tag">Fix</span><span className="changelog-tag">Facilitator</span></div>
+
+- Settlement receipt lookups on **BSC Mainnet** (`eip155:56`) now fall back to a secondary RPC endpoint, so a single unresponsive node no longer turns a settled payment into a failed one.
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 30, 2026</div>
 <div className="changelog-body">
@@ -43,6 +76,23 @@ Release notes for the x402 protocol, SDK, and [CLI](/x402/cli/).
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">Jul 29, 2026</div>
+<div className="changelog-body">
+
+### Official Facilitator — Base settlement
+
+<div className="changelog-tags"><span className="changelog-tag">Update</span><span className="changelog-tag">Facilitator</span><span className="changelog-tag">Base</span></div>
+
+- The official facilitator now settles **Base USDC**: `eip155:8453` (Mainnet) and `eip155:84532` (Sepolia) are enabled alongside TRON Mainnet/Nile and BSC Mainnet/Testnet.
+- Every enabled network registers `exact`, `upto`, and `batch-settlement`; TRON additionally registers `exact_gasfree` where the service holds GasFree relayer credentials. Query `/supported` for the authoritative list. The bundled example facilitator (`facilitator/basic`) still registers only `eip155:97` and `eip155:56` on the EVM side (its `TRON_NETWORKS` already covers Nile/Shasta/Mainnet), so self-hosting Base sellers must add the Base ids to `EVM_NETWORKS` themselves.
+- **Breaking for self-hosters** — the facilitator config now takes canonical CAIP-2 ids only. Friendly aliases such as `bsc:mainnet` and `tron:nile` are no longer resolved and are rejected at startup. [Network & Token Support](/x402/core-concepts/network-and-token-support/)
+
+👉 [Official Facilitator](/x402/core-concepts/OfficialFacilitator/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 20, 2026</div>
 <div className="changelog-body">
diff --git a/devnotes/x402-stablecoin-payments-for-agents.md b/devnotes/x402-stablecoin-payments-for-agents.md
index 9b0a6f8..b98f6c6 100644
--- a/devnotes/x402-stablecoin-payments-for-agents.md
+++ b/devnotes/x402-stablecoin-payments-for-agents.md
@@ -81,7 +81,7 @@ Its limits are equally clear: when the real cost is only known after execution,
 
 `exact_gasfree` is a TRON-only fixed-amount scheme. The payer can pay in USDT or USDD without holding TRX in their ordinary wallet; the official GasFree Proxy/relayer path submits the transaction and pays the corresponding on-chain resource cost.
 
-This is not universally "free" payment. The scheme requires the wallet, token, GasFree service, and Facilitator to all support the flow, and the fee may surface through service rules, asset balances, or the quote structure. Production deployments should explicitly check available assets, GasFree account status, fee configuration, and the failure fallback path — you cannot decide whether payment is possible from the main wallet's TRX balance alone.
+This is not universally "free" payment. The scheme requires the wallet, token, GasFree service, and Facilitator to all support the flow, and the cost surfaces as the GasFree **relayer fee**, which the client estimates and which is deducted from the payment token on top of the payment amount — the payment requirement itself carries no fee object. Production deployments should explicitly check available assets, GasFree account status, fee configuration, and the failure fallback path — you cannot decide whether payment is possible from the main wallet's TRX balance alone.
 
 ### 4.3 Upto: paying for actual usage
 
diff --git a/docs/BANK-OF-AI/QuickStart.md b/docs/BANK-OF-AI/QuickStart.md
index 80475ec..3621371 100644
--- a/docs/BANK-OF-AI/QuickStart.md
+++ b/docs/BANK-OF-AI/QuickStart.md
@@ -19,7 +19,7 @@ Want your AI client to gain BANK OF AI's on-chain capabilities? Just **two steps
 Open whichever AI client you use (OpenClaw / Claude Code / Cursor / Codex / etc.) and paste this command in:
 
 ```
-Run npx skills add BofAI/skills to install every BANK OF AI Skill. After the install completes, run bankofai-guide to walk me through the next steps.
+Run npx skills add BofAI/skills -g to install every BANK OF AI Skill. After the install completes, run bankofai-guide to walk me through the next steps.
 Note: please install into this Agent's own skills directory.
 ```
 
diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
index e939d15..a7caa39 100644
--- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
+++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
@@ -93,7 +93,7 @@ Your AI's secure signing engine. This skill creates and manages encrypted wallet
 
 > Setting up for the first time? Try: "Create a new agent wallet" — the AI walks you through choosing a wallet type (`local_secure` for an encrypted local key, or `privy` for a hosted wallet via API credentials), generating keys, and saving your master password.
 
-> Managing multiple chains? Try: "Show me all my wallets and their addresses" — one wallet derives both EVM and TRON addresses from the same key. Use `eip155:<chainId>` for EVM networks (e.g. `eip155:1` Ethereum, `eip155:56` BSC, `eip155:137` Polygon, `eip155:42161` Arbitrum, `eip155:8453` Base) and `tron:mainnet` / `tron:nile` for TRON.
+> Managing multiple chains? Try: "Show me all my wallets and their addresses" — one wallet derives both EVM and TRON addresses from the same key. Use `eip155:<chainId>` for EVM networks (e.g. `eip155:1` Ethereum, `eip155:56` BSC, `eip155:137` Polygon, `eip155:42161` Arbitrum, `eip155:8453` Base) and canonical CAIP-2 IDs for TRON: `tron:0x2b6653dc` (Mainnet), `tron:0xcd8690dc` (Nile), `tron:0x94a9059e` (Shasta).
 
 > Need to sign something? Try: "Sign this transaction on BSC" — the AI handles the signing locally without broadcasting. Supports raw transactions, EIP-191 messages, and EIP-712 typed data (EVM only).
 
@@ -424,28 +424,36 @@ Changing Owner permissions is **irreversible** without the new keys. The skill v
 
 ## x402-payment {#x402-payment}
 
-Some APIs and AI agents require on-chain payment before use. This skill uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — the AI detects the charge, completes the on-chain payment, gets the result, and reports back. It always asks for your confirmation before paying. Supports payments on multiple chains — **TRON (TRC20: USDT, USDD)** and **BSC (ERC20: USDT, USDC)** (each payment settles on its own chain; this is multi-chain support, not a cross-chain bridge), covering both mainnet and testnet (Nile / BSC testnet).
+Some APIs and AI agents require on-chain payment before use. This skill uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — the AI detects the charge, previews it, completes the on-chain payment, gets the result, and reports back. It always asks for your confirmation before paying. Payments run through the `x402-cli` command-line tool (version **1.0.1 or newer**). The skill checks your installed version first and, if the CLI is missing, tells you how to install it (`npm install -g @bankofai/x402-cli@1.0.1` — the version the skill pins; the CLI's own latest release is 1.0.2) — no local payment scripts are involved. Payments settle on **TRON (TRC20: USDT, USDD)** or **BSC (ERC20: USDT on mainnet; USDT and USDC on testnet)** — each payment settles on its own chain; this is multi-chain support, not a cross-chain bridge.
 
 **Completely safe — looking only, no spending:**
 
-> Verify my x402 wallet status (addresses + readiness).
+> Check whether x402-cli is installed and which version I have.
 
-> Show my GasFree wallet info (address, activation status, balances).
+> Preview what this endpoint would charge before I pay anything: https://api.example.com/protected
 
-> Fetch the manifest for this x402 agent: https://api.example.com/.well-known/agent.json
+> Show me what this endpoint would charge, without paying: https://api.example.com/protected
 
 **Requires your confirmation:**
 
-> Use the x402 protocol to call this paid agent endpoint: https://api.example.com (replace with the actual paid endpoint URL you want to call)
+> Use the x402 protocol to call this paid agent endpoint, and don't spend more than 0.01 USDT: https://api.example.com (replace with the actual paid endpoint URL you want to call)
 
-> Activate my GasFree account on nile with USDT.
+> Pay this endpoint on Nile with USDT via GasFree — cap the payment at 0.01 and the relayer fee at 0.5.
+
+:::tip Always previewed, always capped
+Before the first payment to an unfamiliar endpoint, the skill runs a dry run (`x402-cli pay <url> --dry-run --json`) and shows you the network, scheme, token, and exact amount. Unless you explicitly approve the exact advertised amount, every real payment then carries a spending cap (`--max-amount`), so the payment itself can't exceed what you approved — on GasFree the relayer fee sits on top of it, capped separately (see below).
+:::
 
 :::tip GasFree support (TRON)
-When paying on TRON, the skill prefers `exact_gasfree` and automatically falls back to `exact` if GasFree payment creation fails. GasFree requires sufficient token balance in the GasFree wallet; inactive accounts can be activated on first payment when the advertised fees permit it. Use `--gasfree-info` to check wallet address, activation status, balance, and nonce; use `--gasfree-activate` to activate manually.
+GasFree (`scheme=exact_gasfree`) lets you pay on TRON without holding TRX for energy — a relayer covers the network cost and charges a small fee in the payment token instead (the relayer's service charge: a fixed transfer fee per payment, plus a one-time activation fee on first use, deducted from your GasFree account). The CLI takes the first payment option the endpoint offers that matches your constraints — it does not prefer GasFree — so say "require GasFree" whenever an endpoint also offers a normal TRON payment. Your GasFree account needs enough of the payment token to cover **both** the payment amount and the relayer fee. Because the spending cap doesn't include that fee, every GasFree payment also caps the fee (`--max-gasfree-fee`) unless you explicitly approve the estimate. GasFree is TRON-only — it can't be combined with a BSC (`eip155:*`) network.
+:::
+
+:::info Networks use canonical CAIP-2 IDs
+`tron:0x2b6653dc` (TRON Mainnet — USDT, USDD), `tron:0xcd8690dc` (Nile — USDT, USDD), `tron:0x94a9059e` (Shasta — USDT), `eip155:56` (BSC — USDT), `eip155:97` (BSC testnet — USDT, USDC). Shorthand aliases such as `tron:mainnet` are no longer accepted.
 :::
 
 :::caution Wallet credentials come from agent-wallet
-This skill loads signers via `agent-wallet` only — it does **not** read raw private keys from random config files. Set `AGENT_WALLET_PASSWORD` for encrypted local mode, or `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` for static mode. Requires Node.js 20+.
+This skill loads signers via `agent-wallet` only — it does **not** read raw private keys from random config files, and never accepts a private key typed into a chat command. Set `AGENT_WALLET_PASSWORD` for encrypted local mode, or `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` for static mode. Requires Node.js 20+.
 :::
 
 ---
@@ -502,9 +510,9 @@ Use `twitter-mcp` when you want digests driven by the local `xurl` CLI; use `twi
 
 The onboarding companion that ties the rest of the skill set together. You don't typically invoke this skill directly — it kicks in automatically in three situations:
 
-1. **Post-install setup.** Right after you run `npx skills add BofAI/skills`, the installer hands off to `bankofai-guide`. It installs the `@bankofai/agent-wallet` CLI globally, checks whether you already have a wallet, and asks whether you want to set one up now or later.
+1. **Post-install setup.** Right after you run `npx skills add BofAI/skills -g`, the installer hands off to `bankofai-guide`. It installs the `@bankofai/agent-wallet` CLI globally, checks whether you already have a wallet, and asks whether you want to set one up now or later.
 2. **First-wallet creation.** If you have no wallet yet, it offers two paths: a **quick setup** (strongly recommended — fully automated, takes ~10 seconds, generates an encrypted `local_secure` wallet and a strong random password) and a **detailed setup** (step-by-step walkthrough with custom options). Once your wallet is ready, it shows you both the EVM and TRON addresses and tells you where to deposit USDT.
-3. **Wallet guard.** Signing skills (`sunswap`, `sunperp-skill`, `trc20-toolkit-skill`, `multisig-permissions`, `x402-payment`) run `agent-wallet list` first to check wallet state before any on-chain operation. **Only when no wallet is found** do they hand off to `bankofai-guide`, which pauses the current operation, walks you through creating one in a minute or two, and then returns control to the original flow.
+3. **Wallet guard.** Signing skills (`sunswap`, `sunperp-skill`, `sunpump-agent-skill`, `trc20-toolkit-skill`, `multisig-permissions`) run `agent-wallet list` first to check wallet state before any on-chain operation. **Only when no wallet is found** do they hand off to `bankofai-guide`, which pauses the current operation, walks you through creating one in a minute or two, and then returns control to the original flow.
 
 **Sample prompts that will activate it:**
 
diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md
index cd64e03..3ddd7e1 100644
--- a/docs/McpServer-Skills/SKILLS/Faq.md
+++ b/docs/McpServer-Skills/SKILLS/Faq.md
@@ -173,10 +173,10 @@ For example, if you think 20x leverage is still too risky for perpetual trading,
 rm -rf ~/.agents/skills/sunswap-dex-trading
 ```
 
-**Update:** Re-run the install command. It will update all skills to the latest version.
+**Update:** Re-run the install command (keep `-g` so it refreshes the global copy). It will update all skills to the latest version.
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
 ---
diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md
index 1ad1dcc..e882f4b 100644
--- a/docs/McpServer-Skills/SKILLS/QuickStart.md
+++ b/docs/McpServer-Skills/SKILLS/QuickStart.md
@@ -22,7 +22,7 @@ If you're already using a Skills-compatible AI Agent (OpenClaw, a Telegram bot,
 2. Copy and paste the following prompt:
 
    ```
-   Run npx skills add BofAI/skills to install all BANK OF AI skills. After installation, use bankofai-guide to guide subsequent operations.
+   Run npx skills add BofAI/skills -g to install all BANK OF AI skills. After installation, use bankofai-guide to guide subsequent operations.
    Note: Please install to the skill directory corresponding to the current Agent.
    ```
 
@@ -42,19 +42,19 @@ You don't need to know what `npx`, `npm`, or "global install" mean. The AI handl
 If you have Node.js installed and prefer the command line, simply tell your AI Agent to execute the following command:
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
-The `-y` flag skips all interactive prompts and installs all available Skills by default. Once complete, it will show ✅ Installation complete! along with the full list of installed Skills.
+The `-y` flag skips all interactive prompts and installs all available Skills by default. The `-g` flag installs them **globally** (user-level, under `~/.agents/skills/`) so every project can use them — keep it, otherwise the installer only installs into the directory you happen to be in. Once complete, it will show ✅ Installation complete! along with the full list of installed Skills.
 
 ---
 
 ### Method 3: Interactive Install (Most Control)
 
-If you want to choose which Skills to install and the installation scope, remove the `-y` flag:
+If you want to choose which Skills to install and which AI tools to install them to, drop the `-y` flag but keep `-g`:
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -g
 ```
 
 :::tip
@@ -89,16 +89,16 @@ Unless you're sure you only need specific skills, install them all. Skills use a
 The installer auto-detects AI tools on your computer (e.g., Cursor, Claude Code, Cline, etc.). Use Space to select the ones you want:
 
 ```
-◇  71 agents
+◇  77 agents
 ◇  Which agents do you want to install to?
 │  Amp, Antigravity, Antigravity CLI, Cline, Codex, Cursor, Deep Agents,
 │  Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp, Zed,
-│  Claude Code, OpenClaw … (71 in total — tick the ones you actually use)
+│  Claude Code, OpenClaw … (77 in total — tick the ones you actually use)
 ```
 
-**3️⃣ Choose installation scope**
+**3️⃣ Installation scope**
 
-Select `Project` (current project only) or `User` (globally available across all projects):
+Because you passed `-g`, the installer skips this question and installs at user level, under `~/.agents/skills/`. Without `-g` it asks you to choose between `Project` (current project only) and `User` (globally available across all projects):
 
 ```
 ◇  Installation scope
@@ -274,6 +274,10 @@ When you see output like this, all Skills have been successfully installed to yo
 └  Done!  Review skills before use; they run with full agent permissions.
 ```
 
+:::info A "Failed to install" list at the end is normal
+A global install sometimes ends with `■  Failed to install 14` and one line per skill saying `PromptScript: PromptScript does not support global skill installation`. That is a single client — PromptScript — which has no global install location. It does not affect anything else: the `✓ Installed 14 skills` list printed just above it is the real result, and Claude Code, OpenClaw, Codex and the rest are installed.
+:::
+
 ### Verify Installation
 
 Open your AI chat and type:
diff --git a/docs/x402/api-catalog/get-started.md b/docs/x402/api-catalog/get-started.md
index 01129f4..01ce324 100644
--- a/docs/x402/api-catalog/get-started.md
+++ b/docs/x402/api-catalog/get-started.md
@@ -87,7 +87,7 @@ A service that settles on multiple chains exposes one route per network (`x402Ro
 
 ## What happens during a paid call
 
-Every call clears on-chain via x402 — the quoted price is exactly what you pay, always:
+Every call clears on-chain via x402. On `exact` routes the quoted price is exactly what you pay; on TRON `exact_gasfree` routes the relayer additionally deducts its energy fee from the payment token, so cap it with `--max-gasfree-fee`:
 
 1. **Agent calls** — requests the target endpoint.
 2. **Gateway quotes** — returns the price (HTTP `402`).
diff --git a/docs/x402/api-catalog/reference.md b/docs/x402/api-catalog/reference.md
index 8b33231..696005b 100644
--- a/docs/x402/api-catalog/reference.md
+++ b/docs/x402/api-catalog/reference.md
@@ -63,13 +63,13 @@ An endpoint may serve the same capability across several chains, each settling t
 | `network` | string | Canonical CAIP-2 chain ID this route settles on (e.g. `tron:0x2b6653dc`, `eip155:56`, `eip155:8453`). Legacy TRON aliases such as `tron:nile` are rejected by schema validation. |
 | `provider` | string | The gateway provider `fqn` that handles this network |
 | `scheme` | string | x402 payment scheme for this route: `exact` or, on TRON, `exact_gasfree` — each route declares its own |
-| `assetTransferMethod` | string | Authorization used by an `exact` route: `permit2` on TRON and BSC, `eip3009` on Base USDC. **Omit** it on `exact_gasfree` routes. |
+| `assetTransferMethod` | string | Authorization used by an `exact` route — only `permit2` (TRON and BSC) is meaningful. **Omit** it on Base USDC routes and on `exact_gasfree` routes: the gateway emits the EIP-3009 `name` / `version` pair for Base itself, and `x402-cli` rejects any other `assetTransferMethod` value with `INVALID_PAYMENT_REQUIREMENT`. |
 | `url` | string | Full gateway URL for this network's route |
 
 The build passes this through to outputs as `x402_routes`. When present, callers/agents pick the route matching their intended payment chain; the top-level `url` remains the default route.
 
 :::note GasFree routes
-On TRON you can add an `exact_gasfree` route alongside the `exact` one for the same endpoint: a relayer pays the network energy and deducts its fee from the payment token, so the payer needs no TRX. GasFree routes are TRON-only and must not carry `assetTransferMethod`. With x402 SDK 1.0.1 the relayer cost is estimated client-side, so catalog routes must **not** publish the legacy `fee` or `feeConfig` fields.
+On TRON you can add an `exact_gasfree` route alongside the `exact` one for the same endpoint: a relayer pays the network energy and deducts its fee from the payment token, so the payer needs no TRX. GasFree routes are TRON-only and must not carry `assetTransferMethod`. Since x402 SDK 1.0.1 (current release 1.1.0) the relayer cost is estimated client-side, so catalog routes must **not** publish the legacy `fee` or `feeConfig` fields.
 :::
 
 For example, an endpoint may expose one route per supported chain — TRON Mainnet, BSC Mainnet, and Base Mainnet — each with its own `provider` and `scheme`. To call one, point `x402-cli pay` at the chosen route's `url` and pass the matching `--network` / `--scheme`:
@@ -118,12 +118,13 @@ security   shopping    storage     translation
 |---|---|
 | TRON mainnet | `tron:0x2b6653dc` |
 | TRON Nile testnet | `tron:0xcd8690dc` |
-| TRON Shasta testnet | `tron:0x94a9059e` |
+| TRON Shasta testnet | `tron:0x94a9059e` — schema-level only: the gateway has no Shasta token registry and the official facilitator does not settle it, so it cannot back a live route |
 | BNB Chain (BSC) | `eip155:56` |
 | BNB Smart Chain testnet | `eip155:97` |
 | Base mainnet | `eip155:8453` |
+| Base Sepolia testnet | `eip155:84532` |
 
-The build resolves each chain ID into display metadata (`kind` / `label` / `label_zh`) so the frontend doesn't have to parse CAIP-2 itself — see [Frontend display fields](#frontend-display-fields).
+Check the published `catalog.json` for which routes are actually live on each chain. The build resolves each chain ID into display metadata (`kind` / `label` / `label_zh`) so the frontend doesn't have to parse CAIP-2 itself — see [Frontend display fields](#frontend-display-fields).
 
 ## Validation and secret scanning
 
diff --git a/docs/x402/cli/command-reference.md b/docs/x402/cli/command-reference.md
index 8417edb..b16adb2 100644
--- a/docs/x402/cli/command-reference.md
+++ b/docs/x402/cli/command-reference.md
@@ -43,9 +43,9 @@ x402-cli pay <url> [options]
 
 | Option | Description |
 | :--- | :--- |
-| `--method <method>` | HTTP method (default: `GET`) |
+| `--method <method>` | HTTP method — uppercase, one of `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT` (default: `GET`); anything else fails with `INVALID_ARGUMENT` (exit 2) |
 | `--header "Name: Value"` | Request header; repeatable |
-| `--body <body>` | Request body for non-`GET`/`HEAD` methods |
+| `--body <body>` | Request body; ignored for `GET` and `HEAD` |
 | `--network <caip2>` | Require a specific network (e.g. `tron:0xcd8690dc`, `base-mainnet`) |
 | `--token <symbol>` | Require a specific token (e.g. `USDT`, `USDC`) |
 | `--asset <address>` | Require a specific asset address |
@@ -99,9 +99,9 @@ If the endpoint does not return `402`, the CLI reports the actual status and res
 
 ### GasFree payments (TRON) {#gasfree-payments-tron}
 
-On TRON, `scheme=exact_gasfree` lets a relayer pay the network energy and deduct its fee from the payment token, so the payer doesn't need to hold TRX. The CLI normally selects this scheme automatically when the server's `402` challenge advertises it; pass `--scheme exact_gasfree` to require it explicitly.
+On TRON, `scheme=exact_gasfree` lets a relayer pay the network energy and deduct its fee from the payment token, so the payer doesn't need to hold TRX. The CLI does **not** prefer GasFree: it takes the first requirement in the server's `accepts` list that passes your `--network` / `--scheme` / `--token` filters. If the endpoint also advertises plain `exact`, pass `--scheme exact_gasfree` to guarantee the gasless route.
 
-GasFree fees are **separate** from the advertised payment amount. Set a fee limit so the CLI estimates the relayer fee and rejects the payment before signing if the estimate is too high:
+GasFree fees are **separate** from the advertised payment amount — they are the relayer's service charge (a fixed per-payment transfer fee, plus a one-time activation fee if the GasFree account is not yet activated), deducted from your GasFree account in the payment token. The CLI always estimates the relayer fee for an `exact_gasfree` requirement and reports it as `gasfreeEstimate` (`fee` and `total`) in the result; adding a fee limit makes it abort before signing when either the estimate or the final signed `maxFee` exceeds your cap:
 
 ```bash
 x402-cli pay https://api.example.com/pay \
@@ -112,9 +112,9 @@ x402-cli pay https://api.example.com/pay \
   --json
 ```
 
-`--max-gasfree-fee` and `--max-gasfree-fee-raw` are mutually exclusive, and only apply to an `exact_gasfree` requirement. Override the relayer endpoint with `--gasfree-api-url <url>` or `X402_GASFREE_API_URL`.
+`--max-gasfree-fee` and `--max-gasfree-fee-raw` are mutually exclusive, and are rejected with `INVALID_ARGUMENT` (exit 2) if the requirement the CLI selects is not `exact_gasfree`. Override the relayer endpoint with `--gasfree-api-url <url>` or `X402_GASFREE_API_URL`.
 
-A paid response distinguishes `settled` (the payment cleared on-chain) from `delivered` (the upstream HTTP business response succeeded). A settled upstream failure reports `paid=true`, `settled=true`, `delivered=false` and still includes its transaction information — inspect the transaction and provider behavior before retrying.
+A paid response distinguishes `settled` (the payment cleared on-chain) from `delivered` (the upstream HTTP business response succeeded). A settled-but-undelivered request exits with code 1 and an error envelope (`ok: false`, `error.code: HTTP_ERROR`, or `RATE_LIMITED` on 429); the `paid` / `settled` / `delivered` flags and `paymentResponse` are carried under `error.details`. Read them from there for reconciliation, and do not retry blindly.
 
 ### Paying on Base {#paying-on-base}
 
@@ -146,10 +146,13 @@ Some settings have no flag and are configured through the environment only:
 | `TRON_GRID_API_KEY` | TronGrid API key — set this to avoid public rate limits |
 | `X402_TRON_ALLOWANCE_MODE` | TRON allowance handling; defaults to `auto` |
 | `EVM_RPC_URL` | Default EVM RPC endpoint |
-| `EVM_RPC_URL_8453` / `EVM_RPC_URL_84532` | Per-network RPC for Base Mainnet / Base Sepolia |
+| `EVM_RPC_URL_<chainId>` | Per-network RPC, e.g. `EVM_RPC_URL_8453`, `EVM_RPC_URL_84532`, `EVM_RPC_URL_56`, `EVM_RPC_URL_97` |
+| `RPC_URL` | Generic EVM RPC fallback |
 | `X402_GASFREE_API_URL` | Override the TRON GasFree relayer API |
 | `EVM_PRIVATE_KEY` / `TRON_PRIVATE_KEY` / `PRIVATE_KEY` | Override Agent Wallet — development and CI only |
 
+> EVM RPC precedence: `--rpc-url` → `EVM_RPC_URL_<chainId>` → `RPC_URL` → `EVM_RPC_URL` → a built-in public endpoint. The built-in endpoints (BSC as well as Base) are for development only.
+
 ---
 
 ## `serve`
@@ -174,19 +177,18 @@ x402-cli serve --pay-to <address> [options]
 | `--port <port>` | Bind port (default: `4020`) |
 | `--resource-url <url>` | URL advertised in the payment requirement |
 | `--facilitator-url <url>` | Facilitator base URL (default: `https://facilitator.bankofai.io`) |
-| `--valid-for-seconds <n>` | How long the payment requirement stays valid (default: `300`) |
+| `--valid-for-seconds <n>` | How long the payment requirement stays valid — integer 1–86400 (default: `300`) |
 | `--timeout-ms <ms>` | Facilitator timeout in ms (default: `30000`) |
 | `-d, --daemon` | Run in the background and print the child pid |
 | `--json` | Print the JSON envelope |
 
-The server exposes four routes:
+The server exposes these routes — the paywall branches on the `PAYMENT-SIGNATURE` header, not on the HTTP method:
 
 | Route | Purpose |
 | :--- | :--- |
 | `GET /health` | Returns `{ "ok": true }` |
 | `GET /.well-known/x402` | Machine-readable payment metadata (network, scheme, asset, amount, `payTo`) |
-| `GET /pay` | Returns `402 Payment Required` with the challenge header |
-| `POST /pay` | Verifies the payment, settles it, and returns the transaction |
+| `/pay` (any method) | Returns `402 Payment Required` with the challenge header when the request carries no `PAYMENT-SIGNATURE`; with that header, verifies and settles the payment through the facilitator and returns the transaction |
 
 **Examples:**
 
@@ -235,7 +237,9 @@ x402-cli gateway <search|start|check|scaffold|catalog> [options]
 | `scaffold <name>` | Write a starter `provider.yml` |
 | `catalog <command>` | Build/check/search gateway catalog assets |
 
-`start` and `gateway catalog` require the `@bankofai/x402-gateway` runtime. Install it (`npm install -g @bankofai/x402-gateway`), run from a checkout that has `../x402-gateway/dist/cli.js`, or pass `--gateway-bin <path>`.
+`gateway start` spawns a gateway runtime, but the CLI already ships one: the published package bundles `dist/gateway/cli.js` and depends on `@bankofai/x402-gateway`, so a normal `npm install -g @bankofai/x402-cli` needs nothing extra. It resolves the runtime in order — `--gateway-bin`, the `@bankofai/x402-gateway` dependency, the bundled `dist/gateway/cli.js`, `x402-gateway` on `PATH`, then `../x402-gateway/dist/cli.js` in a checkout. `gateway check`, `gateway catalog build`, `gateway catalog pay-assets`, and `catalog build` call the gateway library in-process; `gateway scaffold` only writes a template file, and `gateway search` / `gateway catalog search` read a catalog source.
+
+Defaults: `gateway start` binds `--host 127.0.0.1 --port 4020` and reads `--providers providers`; `gateway check` also defaults to `providers`; `gateway scaffold` writes to `--output-dir providers/<name>` with `--forward-url https://api.example.com`; a bare `x402-cli gateway catalog` runs `build`.
 
 **Validate provider files:**
 
@@ -300,7 +304,9 @@ x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build> [o
 | :--- | :--- |
 | `--catalog <source>` | `catalog.json` path or URL |
 | `--provider <fqn>` | Provider FQN (for `export-gateway`) |
-| `--output-dir <dir>` | Output directory for generated files |
+| `--output-dir <dir>` | Output directory for generated files (`export-gateway`) |
+| `--output <file>` | Write the built catalog JSON to this file (`build`) |
+| `--dist-dir <dir>` | Write the built catalog to `<dir>/catalog.json` (`build`) |
 | `-n, --limit <count>` | Search result limit (default: `10`) |
 | `--include-blocked` | Include blocked providers in search results |
 | `--timeout-ms <ms>` | Network timeout in ms (default: `30000`) |
diff --git a/docs/x402/cli/faq.md b/docs/x402/cli/faq.md
index 0630ff5..c278a6e 100644
--- a/docs/x402/cli/faq.md
+++ b/docs/x402/cli/faq.md
@@ -69,7 +69,7 @@ Base settles USDC with **EIP-3009** (`transferWithAuthorization`) instead of Per
 
 ### Can I pay without holding TRX?
 
-Yes, on TRON, using GasFree. With `scheme=exact_gasfree`, a relayer pays the network energy and deducts its fee from the payment token, so the payer wallet needs only the stablecoin — no TRX. The CLI selects `exact_gasfree` automatically when the endpoint advertises it, or you can require it with `--scheme exact_gasfree`. Because the relayer fee is separate from the payment amount, cap it with `--max-gasfree-fee <amount>`. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
+Yes, on TRON, using GasFree. With `scheme=exact_gasfree`, a relayer pays the network energy and deducts its fee from the payment token, so the payer wallet needs only the stablecoin — no TRX. The CLI takes the first advertised requirement matching your filters and does not prefer GasFree, so require it with `--scheme exact_gasfree` whenever the endpoint also offers plain `exact`. Because the relayer fee is separate from the payment amount, cap it with `--max-gasfree-fee <amount>`. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
 
 ---
 
@@ -99,7 +99,13 @@ Every failure prints a stable error `code`, a message, and a `hint`. Add `--json
 | `DEADLINE_OR_CLOCK_SKEW` | Requirement expired or clock is off | Sync your local clock and retry with a fresh requirement |
 | `RATE_LIMITED` | Upstream service or RPC is rate limiting | Wait briefly and retry |
 | `NETWORK_ERROR` | Could not reach the URL/RPC | Check the URL, local server, proxy, and connectivity |
-| `SDK_API_DRIFT` | Installed SDK packages don't match the CLI | Reinstall `@bankofai/x402-cli` and its SDK dependencies |
+| `SDK_API_DRIFT` | Installed SDK packages don't match the CLI | Reinstall `@bankofai/x402-cli` (its SDK dependencies are pinned, so don't upgrade them separately) |
+| `INVALID_SETTLEMENT` | The gateway returned a `PAYMENT-RESPONSE` that is not a successful settlement | Do not treat the request as paid; contact the gateway operator |
+| `WALLET_ADDRESS_MISMATCH` | The selected wallet doesn't match the payer in the typed data | Reselect the wallet and retry with a fresh requirement |
+| `INVALID_PAYMENT_REQUIREMENT` | The `402` requirement failed structural validation (scheme, network, amount, address, timeout, resource URL) | The endpoint is misconfigured; contact the provider |
+| `TOKEN_BALANCE_CHECK_FAILED` | The balance check on the payment token failed | Verify the RPC endpoint and the token/network pair |
+| `HTTP_ERROR` | The paid retry returned a non-2xx status | Read `error.details` for `settled` / `paymentResponse` before retrying |
+| `IO_ERROR` | Fallback code for an error the CLI could not classify (local file read/write failures land here too) | Re-run with `--json` and read the raw `message`; check the provider/gateway logs |
 
 ### "402 response missing PAYMENT-REQUIRED header"
 
@@ -115,7 +121,7 @@ The endpoint offered payment options, but none matched your `--network`, `--toke
 
 ### `gateway start` says the runtime isn't found
 
-`gateway start` and `gateway catalog` need the separate `@bankofai/x402-gateway` package. Install it (`npm install -g @bankofai/x402-gateway`), run from a checkout that has `../x402-gateway/dist/cli.js`, or point at a binary with `--gateway-bin <path>`.
+This usually means a broken or partial install: the CLI normally bundles the gateway runtime (`dist/gateway/cli.js`) and depends on `@bankofai/x402-gateway`, so reinstall `@bankofai/x402-cli` first, or point at another runtime with `--gateway-bin <path>`. Only `gateway start` needs that runtime at all: `gateway check`, `gateway catalog build`, `gateway catalog pay-assets`, and `catalog build` call the gateway library in-process, `gateway scaffold` just writes a template file, and the search commands read a catalog source.
 
 ### How do I validate my provider files before deploying?
 
diff --git a/docs/x402/cli/index.md b/docs/x402/cli/index.md
index 5cd5c6e..fe3db6b 100644
--- a/docs/x402/cli/index.md
+++ b/docs/x402/cli/index.md
@@ -8,7 +8,7 @@ description: >-
 
 ## What is x402 CLI?
 
-x402 CLI (`@bankofai/x402-cli`) brings the [x402 payment protocol](../index.md) to your terminal. It is a single, dependency-light command that lets a human operator, a shell script, or an AI agent **pay an x402-protected URL, stand up a local paywall, and browse the provider catalog** — without writing any integration code.
+x402 CLI (`@bankofai/x402-cli`) brings the [x402 payment protocol](../index.md) to your terminal. It is a single command that lets a human operator, a shell script, or an AI agent **pay an x402-protected URL, stand up a local paywall, and browse the provider catalog** — without writing any integration code.
 
 Think of it this way: the [x402 SDK](../sdk-features.md) is what you embed inside an application to charge for or pay for a resource. The CLI is the same capability wrapped as a command you can run right now:
 
@@ -17,7 +17,7 @@ Think of it this way: the [x402 SDK](../sdk-features.md) is what you embed insid
 x402-cli pay https://api.example.com/paid --network tron:0xcd8690dc --token USDT
 ```
 
-It is built entirely on the published TypeScript SDK packages — `@bankofai/x402-core`, `@bankofai/x402-evm`, `@bankofai/x402-fetch`, and `@bankofai/x402-tron`. Stablecoin payments use `scheme=exact`: Permit2 authorization on TRON and BSC, EIP-3009 on Base USDC. TRON also supports `scheme=exact_gasfree`, where a relayer pays the network energy and deducts its fee from the payment token — so the payer doesn't need to hold TRX. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
+It is built entirely on the published TypeScript SDK packages, bundled at pinned versions rather than tracking the newest SDK release — CLI 1.0.2 ships `@bankofai/x402-core`, `-evm`, `-fetch`, and `-tron` at 1.0.1, plus `@bankofai/x402-gateway` 1.0.2 and `@bankofai/agent-wallet` 2.4.0. Stablecoin payments use `scheme=exact`: Permit2 authorization on TRON and BSC, EIP-3009 on Base USDC. TRON also supports `scheme=exact_gasfree`, where a relayer pays the network energy and deducts its fee from the payment token — so the payer doesn't need to hold TRX. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
 
 By default, `pay` signs with your active [Agent Wallet](../../Agent-Wallet/Intro.md) — no private key in an environment variable. See [Paying with Agent Wallet](./command-reference.md#paying-with-agent-wallet).
 
@@ -41,7 +41,7 @@ Read-only commands (`pay --dry-run`, `catalog search`, `gateway check`) need no
 
 ## Human-readable by default, JSON when you need it
 
-Output is human-friendly text by default. Add `--json` to any command for a stable, machine-readable envelope — ideal for scripts and AI agents:
+Output is human-friendly text by default. Add `--json` to any command that returns a result for a stable, machine-readable envelope — ideal for scripts and AI agents. (`gateway start` streams the gateway's own output and emits no envelope; `catalog pay-json --raw` prints the bare payload.)
 
 ```bash
 x402-cli pay 'https://x402-gateway.bankofai.io/providers/defillama-tvl-tron/protocols' \
@@ -89,7 +89,7 @@ The CLI ships a built-in token registry. Pass a network with `--network` and a t
 | :--- | :--- | :--- |
 | **TRON Mainnet** | `tron:0x2b6653dc` | USDT, USDD |
 | **TRON Nile Testnet** | `tron:0xcd8690dc` | USDT, USDD |
-| **TRON Shasta Testnet** | `tron:0x94a9059e` | USDT |
+| **TRON Shasta Testnet** | `tron:0x94a9059e` | USDT (signing only — see note) |
 | **BSC Mainnet** | `eip155:56` | USDT |
 | **BSC Testnet** | `eip155:97` | USDT, USDC |
 | **Base Mainnet** | `eip155:8453` | USDC |
@@ -104,6 +104,10 @@ Always pass TRON networks as their canonical CAIP-2 identifiers (`tron:0x…`).
 | `base-mainnet` | `eip155:8453` |
 | `base-sepolia` | `eip155:84532` |
 
+:::caution Shasta is not settled by the official facilitator
+The CLI accepts `tron:0x94a9059e`, but the official facilitator (`https://facilitator.bankofai.io`) enables only TRON Mainnet/Nile, BSC Mainnet/Testnet, and Base Mainnet/Sepolia. A Shasta payment therefore cannot be verified or settled there — use `tron:0xcd8690dc` (Nile) for TRON testing, or run your own facilitator with Shasta registered.
+:::
+
 Registered token decimals are authoritative and can't be overridden. For an unregistered, non-Base asset, pass `--asset <address>` together with `--decimals <count>`.
 
 :::note Authorization differs by chain
diff --git a/docs/x402/cli/quickstart.md b/docs/x402/cli/quickstart.md
index e478a82..9256ad9 100644
--- a/docs/x402/cli/quickstart.md
+++ b/docs/x402/cli/quickstart.md
@@ -97,7 +97,7 @@ x402-cli pay '<x402-url>' \
 `--max-amount` caps what you're willing to pay: if the endpoint's price exceeds it, the CLI aborts before signing. The same command works on EVM networks — just point `--network` at one, such as `eip155:97` (BSC Testnet) or `base-sepolia` (Base Sepolia, USDC).
 
 :::tip No TRX? Use GasFree
-On TRON, if the endpoint advertises `exact_gasfree`, the CLI can pay without any TRX in your wallet — a relayer covers the network energy and takes its fee from the payment token. The CLI selects it automatically, or you can require it with `--scheme exact_gasfree` and cap the relayer fee with `--max-gasfree-fee`. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
+On TRON, if the endpoint advertises `exact_gasfree`, the CLI can pay without any TRX in your wallet — a relayer covers the network energy and takes its fee from the payment token. The CLI picks the first advertised requirement that matches your filters — it does not prefer GasFree — so require it with `--scheme exact_gasfree` when the endpoint also offers plain `exact`, and cap the relayer fee with `--max-gasfree-fee`. See [GasFree payments](./command-reference.md#gasfree-payments-tron).
 :::
 
 ---
@@ -119,8 +119,7 @@ It exposes:
 
 - `GET /health` — liveness check
 - `GET /.well-known/x402` — machine-readable payment metadata
-- `GET /pay` — returns `402 Payment Required`
-- `POST /pay` — verifies and settles a submitted payment through the facilitator
+- `/pay` — returns `402 Payment Required` when the request has no `PAYMENT-SIGNATURE` header; with that header it verifies and settles the payment through the facilitator (any HTTP method)
 
 In another terminal, pay it:
 
diff --git a/docs/x402/core-concepts/OfficialFacilitator.md b/docs/x402/core-concepts/OfficialFacilitator.md
index bb03435..0b46cc8 100644
--- a/docs/x402/core-concepts/OfficialFacilitator.md
+++ b/docs/x402/core-concepts/OfficialFacilitator.md
@@ -56,7 +56,7 @@ Official Facilitator supports **two calling modes**.
 
 | Mode | Rate Limit | Description |
 |-----|-----|-----|
-| **Anonymous Mode** | 10 times / minute (default, configurable) | No API Key required, suitable for local development and functional testing |
+| **Anonymous Mode** | 1 time / minute on the official deployment (configurable; the code default is 10/minute when unset) | No API Key required, suitable for local development and functional testing |
 | **API Key Mode** | 1000 times / minute | API Key required, suitable for production environments and high-frequency payment requests |
 
 The calling methods for both modes are exactly the same, but they differ in **identity recognition and interface rate limiting strategies**.
@@ -70,7 +70,7 @@ If the request **does not carry an API Key**, the Facilitator will treat the req
 In anonymous mode:
 
 - The `/settle` interface is **rate-limited**
-- **Maximum 10 calls per minute** (default, configurable)
+- **1 call per minute** on the official deployment (configurable; the code default is 10/minute when unset)
 
 This mode is mainly used for:
 
@@ -252,7 +252,17 @@ After clicking **"Confirm"**, you will return to the Dashboard page, and the API
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | Query payment records by the on-chain authorization identity |
 | GET | `/payments` | Authenticated seller's settlement feed (`?limit=&offset=`) |
 
-> There is **no** `/fee/quote` endpoint — fee terms travel inside the payment requirements' `extra` field. Rate limiting only applies to the `/settle` interface; other interfaces are not affected by rate limiting.
+> There is **no** `/fee/quote` endpoint, and the schemes carry no facilitator fee. Rate limiting only applies to the `/settle` interface; other interfaces are not affected by rate limiting.
+
+### Networks and schemes the official service settles
+
+| Network | Environment |
+|---|---|
+| `tron:0x2b6653dc` (TRON Mainnet) · `tron:0xcd8690dc` (Nile) | mainnet · testnet |
+| `eip155:56` (BSC) · `eip155:97` (BSC testnet) | mainnet · testnet |
+| `eip155:8453` (Base) · `eip155:84532` (Base Sepolia) | mainnet · testnet |
+
+Each of these networks registers `exact`, `upto`, and `batch-settlement`; TRON additionally registers `exact_gasfree` where the service holds GasFree relayer credentials (TRON Mainnet and Nile). Query `/supported` for the authoritative list of the deployment you are pointing at.
 
 ### Payment Record Query
 
@@ -277,7 +287,7 @@ The `/payments/tx/{tx_hash}` and `/payments?network=&nonce=[&asset=&payer=]` int
 
 **Q: Can it run normally without configuring an API Key?**
 
-Yes, it can run, but the `/settle` interface is limited to 10 calls per IP per minute by default. This is only suitable for testing; any real traffic must be configured with an API Key.
+Yes, it can run, but on the official deployment the `/settle` interface is limited to 1 call per IP per minute (the facilitator service's built-in default is 10/minute when the deployment does not configure it). This is only suitable for testing; any real traffic must be configured with an API Key.
 
 **Q: Does the API Key expire?**
 
diff --git a/docs/x402/core-concepts/facilitator.md b/docs/x402/core-concepts/facilitator.md
index 79133be..bd1265f 100644
--- a/docs/x402/core-concepts/facilitator.md
+++ b/docs/x402/core-concepts/facilitator.md
@@ -19,7 +19,7 @@ By introducing a Facilitator, servers no longer need to maintain direct connecti
 
 - **Payment Verification**: Ensures that the signed payload strictly complies with the server's declared payment requirements.
 - **Payment Settlement**: Submits validated transactions to the blockchain and monitors their confirmation status.
-- **Fee Management**: Supports configurable service fees (optional) for facilitating payments.
+- **Settlement Records**: Persists one record per settlement, keyed on the on-chain authorization identity, and answers seller-scoped record queries.
 - **Result Feedback**: Returns verification and settlement results to the server, enabling it to decide whether to deliver the requested resource.
 
 > **Note**: The Facilitator **does not custody funds** and does not act as an escrow. It only executes verification and on-chain operations according to the client's signed authorization.
@@ -43,12 +43,12 @@ To use x402, you need access to a Facilitator service. There are currently two o
 
 | | Official Facilitator | Self-Hosted Facilitator |
 |---|---|---|
-| **Best for** | Most sellers, especially those new to x402 | Advanced users who need full control over fee policies and energy management |
+| **Best for** | Most sellers, especially those new to x402 | Advanced users who need full control over the settlement wallet, RPC endpoints, and which networks/schemes are registered |
 | **Requires server maintenance** | No | Yes |
-| **Requires wallet private key** | No | Yes (for paying transaction fees) |
+| **Requires a settlement wallet** | No | Yes — a funded wallet resolved through `@bankofai/agent-wallet` (pays network fees) |
 | **Setup difficulty** | Low (just obtain an API Key) | Medium (requires deployment and configuration) |
-| **Fee control** | Fixed policy | Fully customizable |
-| **Recommended for** | Testing, quick launch, small to medium-scale apps | Large-scale production, custom fee structures |
+| **Network & scheme control** | Fixed set | Fully customizable |
+| **Recommended for** | Testing, quick launch, small to medium-scale apps | Large-scale production, private or compliance-bound deployments |
 
 ---
 
@@ -71,13 +71,13 @@ Quick usage examples can be found in [OfficialFacilitator](./OfficialFacilitator
 
 ## Option 2: Self-Hosted Facilitator
 
-If you need full control over fee policies and energy management, or have specific privacy or compliance requirements, you can deploy your own Facilitator service.
+If you need full control over the settlement wallet, RPC endpoints, energy management, or which networks and schemes are registered — or you have specific privacy or compliance requirements — you can deploy your own Facilitator service.
 
 > ⚠️ **Self-hosting security notes:**
-> - A self-hosted Facilitator requires a **dedicated wallet** private key to pay blockchain transaction fees
+> - A self-hosted Facilitator needs a **dedicated funded wallet** to pay blockchain transaction fees. It is resolved through `@bankofai/agent-wallet` and unlocked out-of-band (for example `AGENT_WALLET_PASSWORD`) — the raw private key never enters the service process
 > - **This Facilitator wallet should be separate from your payment recipient wallet** — create a new wallet specifically for this purpose
 > - Only deposit a small amount of tokens into the Facilitator wallet (enough for fees); do not store large amounts
-> - Keep the private key only in your `.env` file — **never upload it to GitHub or share it with anyone**
+> - Never place a raw private key in `.env`, a config file, or a shell command — **and never upload wallet material to GitHub or share it with anyone**
 
 Quick usage examples can be found in [Quickstart for Sellers](../getting-started/quickstart-for-sellers.md)
 
@@ -99,7 +99,7 @@ Whether using the official service or a self-hosted instance, the Facilitator pr
 | GET | `/metrics` | Prometheus metrics (operational; exposed on the main port only when monitoring shares it) |
 | ALL | `/mainnet/*` · `/nile/*` | GasFree Open API transparent proxy (HMAC-signed) — used internally by the TRON `exact_gasfree` scheme |
 
-> There is **no** `/fee/quote` endpoint. Fee terms travel inside the payment requirements' `extra` field, and payment records are keyed on the on-chain authorization identity (`network` + `scheme` + `asset` + `payer` + `nonce`), not a client-supplied payment ID.
+> There is **no** `/fee/quote` endpoint, and the schemes carry no facilitator fee at all. Payment records are keyed on the on-chain authorization identity (`network` + `scheme` + `asset` + `payer` + `nonce`), not a client-supplied payment ID.
 
 ---
 
@@ -110,7 +110,7 @@ The `/settle` endpoint enforces dynamic rate limits based on the caller's authen
 | Mode | Rate Limit | How to Authenticate |
 |------|------------|---------------------|
 | **Authenticated** | 1000 requests / minute | Include `X-API-KEY: <your_key>` header |
-| **Anonymous** | 10 requests / minute (default, configurable) | No API Key provided |
+| **Anonymous** | 1 request / minute on the official deployment (configurable; the code default is 10/minute when unset) | No API Key provided |
 
 Other endpoints (`/verify`, `/supported`, `/payments/*`) are not individually rate-limited.
 
@@ -126,14 +126,14 @@ When the request includes a valid `X-API-KEY` header, the results are **automati
 
 ---
 
-## Fee Structure
+## Fees
 
-The Facilitator supports flexible service fee configurations:
+The current schemes carry **no facilitator fee**: there is no `base_fee` configuration, no fee object in the payment requirements, and no `/fee/quote` endpoint — all removed in SDK 1.0.1. A settlement transfers the signed amount to the seller — never less than the advertised amount, and exactly that amount when paying with the official SDK or CLI clients.
 
-- **Base Fee**: A fixed service fee per transaction, configured per network and asset (e.g., `1 USDT`).
-- **No Fee Mode**: Supports zero-fee operation (e.g. EVM `exact` takes no facilitator fee).
+The costs that do exist:
 
-Fee terms are included in the Payment Requirements' `extra` field sent from the server to the client; there is no separate `/fee/quote` endpoint.
+- **Network fees** (TRX energy/bandwidth, BNB or ETH gas) are paid by the Facilitator's settlement wallet.
+- **The GasFree relayer fee** on TRON `exact_gasfree` — the relayer's service charge for fronting the network energy (a per-payment transfer fee, plus a one-time activation fee for a new GasFree account) — is set by the relayer and deducted from the payment token on top of the payment amount. Clients should cap it explicitly.
 
 ---
 
diff --git a/docs/x402/core-concepts/http-402.md b/docs/x402/core-concepts/http-402.md
index cc5c2ea..a644370 100644
--- a/docs/x402/core-concepts/http-402.md
+++ b/docs/x402/core-concepts/http-402.md
@@ -61,12 +61,7 @@ When the server returns a `402 Payment Required` response, the decoded `PAYMENT-
       "payTo": "<SELLER_TRON_ADDRESS>",
       "maxTimeoutSeconds": 3600,
       "extra": {
-        "assetTransferMethod": "permit2",
-        "fee": {
-          "feeTo": "<FACILITATOR_FEE_RECEIVER_ADDRESS>",
-          "feeAmount": "100",
-          "caller": "<FACILITATOR_CALLER_ADDRESS>"
-        }
+        "assetTransferMethod": "permit2"
       }
     }
   ]
@@ -129,12 +124,12 @@ When the server returns a `402 Payment Required` response, the decoded `PAYMENT-
 | `resource`          | Information about the requested resource                                    |
 | `accepts`           | Array of accepted payment options                                           |
 | `scheme`            | Payment scheme (`exact`, `upto`, `batch-settlement`, or `exact_gasfree`)  |
-| `network`           | Network identifier (`tron:0xcd8690dc`, `tron:0x2b6653dc`, `eip155:56`, `eip155:97`)  |
+| `network`           | Network identifier (`tron:0xcd8690dc`, `tron:0x2b6653dc`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532`)  |
 | `amount`            | Payment amount in the smallest unit (e.g., 100 = 0.0001 USDT)              |
 | `asset`             | TRC-20/BEP-20 token contract address                                        |
 | `payTo`             | Seller's wallet address                                                     |
 | `maxTimeoutSeconds` | Maximum validity duration of the payment                                    |
-| `extra.fee`         | Facilitator fee information (includes `feeTo`, `feeAmount`, `caller`) |
+| `extra`             | Scheme-specific data — `assetTransferMethod` (`eip3009` / `permit2`), the token `name`/`version` for EIP-3009 assets, and, for a scheme that declares a non-default payment flow, `paymentFlow` (`upfront` or `escrow`) — every built-in scheme uses the default `authorization` flow, which is omitted from `extra`. It carries no fee object: the schemes take no facilitator fee. |
 | `extensions`        | Additional context for the payment scheme (e.g., gas-sponsoring, payment-identifier) |
 
 ## Payment Signature Structure
diff --git a/docs/x402/core-concepts/network-and-token-support.md b/docs/x402/core-concepts/network-and-token-support.md
index 7cf489a..a673690 100644
--- a/docs/x402/core-concepts/network-and-token-support.md
+++ b/docs/x402/core-concepts/network-and-token-support.md
@@ -29,7 +29,7 @@ In the x402 protocol (on-the-wire), BSC uses the EIP-155 chain ID format:
 | **BSC Mainnet**  | `eip155:56`   | BSC Mainnet (Production)      |
 | **BSC Testnet**  | `eip155:97`   | BSC Testnet (Chapel)          |
 
-> **Note**: When configuring a self-hosted Facilitator, the YAML config file uses a human-readable format: `bsc:mainnet` and `bsc:testnet`. The Facilitator automatically maps these to the corresponding EIP-155 chain IDs used in the protocol.
+> **Note**: A self-hosted Facilitator's YAML config takes **canonical CAIP-2 identifiers only** — `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532`, `tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`. Friendly aliases such as `bsc:mainnet` or `tron:nile` are not resolved and are rejected at startup.
 
 ---
 
@@ -57,7 +57,7 @@ The protocol uses secure signing mechanisms to ensure tamper-resistant message a
 | :------------------ | :--------- | :---- |
 | **TRON Mainnet**    | **Mainnet** | **Production network** for real-value assets |
 | **TRON Nile**       | **Testnet** | **Recommended testnet** for development and debugging |
-| **TRON Shasta**     | **Testnet** | Long-running alternative testnet |
+| **TRON Shasta**     | **Testnet** | Alternative testnet — SDK/CLI only; the official facilitator does not settle Shasta, so use Nile or self-host |
 | **BSC Mainnet**     | **Mainnet** | **Production network** for real-value assets |
 | **BSC Testnet**     | **Testnet** | **Recommended testnet** for BSC development |
 | **Base Mainnet**    | **Mainnet** | **Production network** using official USDC |
@@ -75,20 +75,22 @@ x402 supports **TRC-20, BEP-20, and ERC-20** tokens. TRON/BSC routes use their c
 | :------ | :------------- | :--------------- |
 | **USDT** | `tron:0x2b6653dc` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
 | **USDT** | `tron:0xcd8690dc`    | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` |
+| **USDT** | `tron:0x94a9059e` | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` |
 | **USDD** | `tron:0x2b6653dc` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` |
 | **USDD** | `tron:0xcd8690dc`    | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` |
 | **USDT** | `eip155:56`    | `0x55d398326f99059fF775485246999027B3197955` |
 | **USDC** | `eip155:56`    | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
-| **EPS**  | `eip155:56`    | `0xA7f552078dcC247C2684336020c03648500C6d9F` |
 | **USDT** | `eip155:97`    | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
 | **USDC** | `eip155:97`    | `0x64544969ed7EBf5f083679233325356EbE738930` |
 | **DHLU** | `eip155:97`    | `0x375cADdd2cB68cE82e3D9B075D551067a7b4B816` |
 | **USDC** | `eip155:8453`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 | **USDC** | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
+> **Default assets vs. opt-in assets (SDK 1.1.0+)**: the default-asset registry resolves **USDT** on TRON (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) and BSC Mainnet (`eip155:56`), and **USDC** on BSC Testnet (`eip155:97`) and Base (`eip155:8453`, `eip155:84532`). Everything else in the table above — TRON USDD, BSC Mainnet USDC, BSC Testnet USDT, DHLU, and any custom token — is server-advertised only: with the 1.1.0 client spend controls on by default, a client refuses to pay it unless you allowlist it via `spendControls.allowedAssets`, and `x402-cli` pays registry tokens by default — an unregistered asset requires explicit `--asset` plus `--decimals`, and is rejected outright on Base.
+
 > **Extensibility**: The protocol is highly extensible. By registering tokens in the `TokenRegistry`, you can easily support any custom TRC-20 or BEP-20 token.
 
-> **Token selection for the `exact` scheme**: EIP-3009 tokens (for example official Base USDC and BSC testnet DHLU) settle gaslessly via `transferWithAuthorization`. Plain ERC-20 tokens (for example BSC USDC/USDT and TRON USDT/USDD) settle via the Permit2 path — the client auto-broadcasts a one-time `approve(Permit2)` on first payment. The per-token method is data in the server's `accepts[].price.extra`: EIP-3009 → `{ name, version }`; plain ERC-20 → `{ assetTransferMethod: "permit2" }`.
+> **Token selection for the `exact` scheme**: EIP-3009 tokens (for example official Base USDC and BSC testnet DHLU) settle gaslessly via `transferWithAuthorization`. Plain ERC-20 tokens (for example BSC USDC/USDT and TRON USDT/USDD) settle via the Permit2 path — the client auto-broadcasts a one-time `approve(Permit2)` on first payment. You set the per-token method on the server under `accepts[].price.extra`; the SDK surfaces it on the wire as `accepts[].extra`: EIP-3009 → `{ name, version }`; plain ERC-20 → `{ assetTransferMethod: "permit2" }`.
 
 ---
 
@@ -147,26 +149,26 @@ A payment-channel scheme for high-frequency micro-payments (e.g. AI agent per-to
 
 ### `exact_gasfree` Scheme
 
-TRON-specific. Allows buyers to pay with USDT/USDD **without holding TRX for gas fees**. The payer signs a TIP-712 GasFree permit and a relayer pays the on-chain energy via the official GasFree Proxy — no TRX for the payer, no one-time `approve`. Funds come from the payer's GasFree custodial wallet (not the main wallet). Available on `tron:0x2b6653dc` and `tron:0xcd8690dc`.
+TRON-specific. Allows buyers to pay with USDT/USDD **without holding TRX for gas fees**. The payer signs a TIP-712 GasFree permit and a relayer pays the on-chain energy via the official GasFree Proxy — no TRX for the payer, no one-time `approve`. Funds come from the payer's GasFree custodial wallet (not the main wallet). The SDK registers GasFree on `tron:0x2b6653dc`, `tron:0xcd8690dc`, and `tron:0x94a9059e`, but the official facilitator only proxies the relayer for TRON Mainnet and Nile — the built-in Shasta relayer URL has no upstream behind it, so Shasta GasFree needs your own relayer.
 
-#### GasFree Account Management (via x402-payment skill)
+The relayer charges its own fee in the payment token, **on top of** the payment amount, so the GasFree account must hold enough to cover both.
 
-When using the `x402-payment` skill, you can manage GasFree accounts directly from the CLI:
+:::info What the relayer fee is
+**The relayer fee is the service charge of the GasFree relayer**: instead of burning your own TRX, the relayer fronts the on-chain energy/bandwidth, and in exchange deducts a fee from your GasFree account, denominated in the payment token (e.g. USDT). It is composed of a fixed **transfer fee** per payment, plus a one-time **activation fee** on the first payment if the GasFree account is not yet activated. The rates are quoted per token by the relayer's API; the client queries and estimates them before signing (when the relayer reports no rate for the token, the client signs a default ceiling of one whole token instead), and the signed permit carries a `maxFee` ceiling the relayer cannot exceed. It is counted **separately** from the payment amount (the money the seller receives) — `--max-amount` does not cover it, so cap it with `--max-gasfree-fee`.
+:::
 
-**Query GasFree wallet info** (address, activation status, balance, nonce):
-```bash
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --network nile
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --wallet <YOUR_WALLET_ADDRESS>
-```
+#### Paying with GasFree from the CLI
 
-**Activate a GasFree account** (required before first use):
 ```bash
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network mainnet
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --token USDT
+x402-cli pay <url> \
+  --scheme exact_gasfree \
+  --max-amount 0.01 \
+  --max-gasfree-fee 0.5 \
+  --json
 ```
 
+The CLI takes the first requirement in the server's `accepts` list that matches your filters — it does not prefer GasFree — so pass `--scheme exact_gasfree` whenever the endpoint also advertises plain `exact`. `--max-amount` does not cover the relayer fee — cap that separately with `--max-gasfree-fee` (or `--max-gasfree-fee-raw`). See the [CLI command reference](../cli/command-reference.md#gasfree-payments-tron).
+
 ### How Payment Schemes Work
 
 1. **Authorize**
diff --git a/docs/x402/core-concepts/wallet.md b/docs/x402/core-concepts/wallet.md
index 0a65385..32e547e 100644
--- a/docs/x402/core-concepts/wallet.md
+++ b/docs/x402/core-concepts/wallet.md
@@ -15,7 +15,7 @@ Buyers use their wallet as the primary interaction anchor, responsible for:
 - **Asset Custody**: Securely storing USDT or other TRC-20/BEP-20 tokens.
 - **Signature Authorization**: Cryptographically signing payment payloads using their private key.
 - **Programmatic Payments**: Authorizing on-chain fund transfers via code (especially suitable for autonomous AI agents).
-- **Allowance Management**: Managing token allowances granted to the Facilitator contract.
+- **Allowance Management**: Managing the one-time `approve(Permit2, max)` allowance granted to the Permit2 contract — the facilitator then pulls the funds through the x402 Permit2 proxy.
 
 > **Stateless Authentication**: With wallet-based identity, buyers can initiate transactions without account registration, API keys, or login sessions.
 
diff --git a/docs/x402/faq.md b/docs/x402/faq.md
index 52ae0e1..c76da13 100644
--- a/docs/x402/faq.md
+++ b/docs/x402/faq.md
@@ -41,7 +41,7 @@ The previous Python SDK lives under `legacy/` for reference.
 
 #### Who runs the Facilitator?
 
-Typically, you run your own Facilitator service. x402 is designed for self-hosting, and the built-in Facilitator in the repository is production-ready.
+Typically, you run your own Facilitator service. x402 is designed for self-hosting: the repository ships a runnable reference implementation at `examples/typescript/facilitator/basic` that you harden for your own production use.
 
 An [officially hosted Facilitator](https://github.com/BofAI/x402-facilitator) service is also available, allowing you to use x402 without deploying infrastructure yourself.
 
@@ -73,7 +73,7 @@ x402 supports four payment schemes:
 - **`exact`**: Pay the exact advertised amount. EIP-3009 tokens (e.g. official Base USDC and BSC testnet DHLU) settle gaslessly via `transferWithAuthorization`; plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT, TRON USDT/USDD) settle via the Permit2 path with a one-time `approve(Permit2)`. The `exact` wire payload conforms to the **x402 Foundation** v2 spec.
 - **`upto`**: Usage-based billing — the client signs a Permit2 authorization for up to a **maximum**; the server settles only the **real usage** (≤ max). Ideal for **metered billing**, **LLM token usage**.
 - **`batch-settlement`**: Payment-channel for high-frequency micro-payments — deposit once, pay many requests with off-chain vouchers, settle in one batch tx. Includes a refund path.
-- **`exact_gasfree`** (TRON only): Allows buyers to pay with USDT/USDD without holding TRX for gas. A relayer pays the on-chain energy via the GasFree API — no API keys required on the client side.
+- **`exact_gasfree`** (TRON only): Allows buyers to pay with USDT/USDD without holding TRX for gas. A relayer pays the on-chain energy via the GasFree API — no API keys required on the client side. The relayer deducts its own fee from the payment token, on top of the payment amount.
 
 #### Can this SDK interoperate with the x402 Foundation (formerly Coinbase) v2 reference implementation?
 
@@ -81,10 +81,10 @@ x402 supports four payment schemes:
 
 - A stock v2 client can directly access this SDK's `exact` protected endpoints with no project-specific adapter layer.
 - This SDK's client can pay v2-compatible servers directly.
-- In the V2 structure, transfer authorization data is carried in the `payload.authorization` field (a structured object). As a migration fallback, the client also populates `extensions.transferAuthorization` so that servers still running older versions can parse the payload.
+- In the V2 structure, transfer authorization data is carried in the `payload.authorization` field (a structured object).
 - BSC USDT/USDC are plain ERC-20s (no ERC-3009). They settle via the Permit2 path under the `exact` scheme — the client auto-broadcasts a one-time `approve(Permit2)` on first payment. ERC-3009 tokens like BSC testnet **DHLU** settle gaslessly with no approve.
 - Base Mainnet official USDC uses EIP-3009 under `exact`: the payer signs `transferWithAuthorization`, so no Permit2 approval is required.
-- The `examples/bsc-testnet-smoke/` directory contains smoke tests for bidirectional interoperability (Coinbase official client → BANK OF AI server, BANK OF AI client → Coinbase official server) that you can use as a debugging and integration reference.
+- The `legacy/examples/bsc-testnet-smoke/` directory (part of the `legacy/` tree, kept for reference) contains smoke tests for bidirectional interoperability (Coinbase official client → BANK OF AI server, BANK OF AI client → Coinbase official server) that you can use as a debugging and integration reference.
 
 ---
 
@@ -107,6 +107,8 @@ x402 supports four payment schemes:
 | Base Mainnet (`eip155:8453`) | Official USDC (ERC-20, EIP-3009) | **Mainnet** |
 | Base Sepolia (`eip155:84532`) | USDC (ERC-20, EIP-3009) | **Testnet** |
 
+Only some of these are **default assets** (USDT on TRON and BSC Mainnet, USDC on BSC Testnet and Base). Since SDK 1.1.0 a client's spend controls reject any other asset — including TRON USDD, BSC Mainnet USDC and BSC Testnet USDT — unless it is allowlisted via `spendControls.allowedAssets`.
+
 Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` from `@bankofai/x402-tron`); custom BEP-20 tokens are advertised by adding an entry to the server's `EVM_TOKENS` config table.
 
 #### What fees are involved?
@@ -115,7 +117,7 @@ Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` f
   - TRON: TRX for Energy and Bandwidth (paid by the Facilitator)
   - BSC: BNB for gas (paid by the Facilitator)
   - Base: ETH for gas (paid by the Facilitator)
-- **Facilitator Service Fee**: Configurable by each Facilitator (can be set to zero)
+- **Facilitator service fee**: none. The current schemes carry no fee field — `base_fee` config and the `/fee/quote` endpoint were removed in SDK 1.0.1. On TRON `exact_gasfree`, the GasFree relayer charges its own fee in the payment token; cap it with the client's GasFree fee limit.
 
 ---
 
@@ -127,7 +129,7 @@ Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` f
 
 1. **Buyer (client/agent)** signs locally (browser, serverless function, or agent VM).
 2. **Seller** verifies signatures without accessing private keys.
-3. **Facilitator** uses its own key to submit transactions on-chain.
+3. **Facilitator** submits transactions with its own settlement wallet, resolved through `@bankofai/agent-wallet` — the raw key never enters the facilitator process.
 
 #### How does refunds work?
 
diff --git a/docs/x402/getting-started/quickstart-for-agent.md b/docs/x402/getting-started/quickstart-for-agent.md
index f193098..2e73308 100644
--- a/docs/x402/getting-started/quickstart-for-agent.md
+++ b/docs/x402/getting-started/quickstart-for-agent.md
@@ -113,19 +113,19 @@ export EVM_RPC_URL="https://bsc-testnet-rpc.publicnode.com"
 Run the following command to install all BANK OF AI Skills (including x402-payment) at once:
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
-The `-y` flag skips all interactive prompts and installs all available Skills by default. The installer auto-detects AI tools on your computer (Cursor, Claude Code, Cline, OpenCode, etc.) and copies the skills into the correct directories.
+The `-y` flag skips all interactive prompts and installs all available Skills by default; `-g` installs them globally (user-level, under `~/.agents/skills/`) instead of into the current directory. The installer auto-detects AI tools on your computer (Cursor, Claude Code, Cline, OpenCode, etc.) and copies the skills into the correct directories.
 
 > ✅ **Success indicator:** Terminal shows `✓ x402-payment (copied)` along with other installed skills
 
 ### Interactive Installation
 
-If you prefer to select specific skills or choose the installation scope:
+If you prefer to select specific skills or the AI tools to install them to:
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -g
 ```
 
 For a detailed walkthrough of the interactive installation process, see the [Skills Quick Start](../../McpServer-Skills/SKILLS/QuickStart.md).
@@ -194,7 +194,7 @@ Go to the [BSC Testnet Explorer](https://testnet.bscscan.com/), search for your
 </TabItem>
 </Tabs>
 
-> ✅ **Success indicator:** The agent returns content in `{"data": "..."}` format, and the corresponding transaction appears on the block explorer
+> ✅ **Success indicator:** The agent returns the endpoint's JSON payload — the bundled Express example answers `{"report":{"weather":"sunny","temperature":70}}` — and the corresponding transaction appears on the block explorer
 
 ---
 
diff --git a/docs/x402/getting-started/quickstart-for-sellers.md b/docs/x402/getting-started/quickstart-for-sellers.md
index 29f1785..b2dabe4 100644
--- a/docs/x402/getting-started/quickstart-for-sellers.md
+++ b/docs/x402/getting-started/quickstart-for-sellers.md
@@ -125,7 +125,7 @@ Deposit a small amount of official USDC on Base Mainnet. The resource server onl
 
 **Testnet vs. Mainnet:**
 
-- **Testnet**: Uses free test tokens, no real funds involved, suitable for development and debugging. Network identifiers: `tron:0xcd8690dc` / `eip155:97`
+- **Testnet**: Uses free test tokens, no real funds involved, suitable for development and debugging. Network identifiers: `tron:0xcd8690dc` / `eip155:97` / `eip155:84532` (Base Sepolia, USDC — test here before going to Base Mainnet)
 - **Mainnet**: Involves real payments, used when going live. Network identifiers: `tron:0x2b6653dc` / `eip155:56` / Base `eip155:8453`
 
 ---
@@ -208,7 +208,7 @@ express()
       credit: 1000000,
     })
   )
-  .listen(4021);
+  .listen(4021, () => console.log("Resource server on http://localhost:4021"));
 ```
 
 </TabItem>
@@ -255,7 +255,7 @@ express()
       credit: 1000000,
     })
   )
-  .listen(4021);
+  .listen(4021, () => console.log("Resource server on http://localhost:4021"));
 ```
 
 </TabItem>
@@ -290,7 +290,7 @@ A Facilitator is an **automated settlement service**: when someone pays your API
 | **Maintenance required** | No — officially hosted | Yes — you run it yourself |
 | **Wallet private key required** | No | Yes (to settle on-chain) |
 | **Difficulty** | Low (just apply for an API Key) | Medium (run the example facilitator) |
-| **Best for** | Fast deployment, most users | Full control over fee strategy |
+| **Best for** | Fast deployment, most users | Full control over the settlement wallet, RPC endpoints, and registered networks/schemes |
 
 <Tabs>
 <TabItem value="official" label="✅ Official Facilitator (Recommended)">
@@ -336,7 +336,9 @@ FACILITATOR_API_KEY=paste_your_api_key_here
 </TabItem>
 <TabItem value="selfhost" label="Self-Hosted Facilitator">
 
-The self-hosted option gives you full control over fee strategy. It runs the example facilitator (`examples/typescript/facilitator/basic`), which exposes `/verify`, `/settle`, `/supported` over HTTP and dispatches by the payment's `network` field.
+The self-hosted option gives you full control over the settlement wallet, RPC endpoints, and which networks and schemes you register — neither the SDK nor the facilitator charges a fee of its own. It runs the example facilitator (`examples/typescript/facilitator/basic`), which exposes `/verify`, `/settle`, `/supported` over HTTP and dispatches by the payment's `network` field.
+
+> **Base sellers:** the bundled example facilitator registers only `eip155:97` and `eip155:56` (`EVM_NETWORKS` in `facilitator/basic/src/chains/evm.ts`). To settle on Base, either use the official facilitator — which enables `eip155:8453` and `eip155:84532` — or add those ids to `EVM_NETWORKS` yourself.
 
 > ⚠️ **Security reminder — please read first:**
 > - A self-hosted Facilitator uses your wallet to submit on-chain settlement transactions — **this wallet should be separate from your receiving wallet**
@@ -404,6 +406,12 @@ Open a **new terminal window** (do not close the facilitator), and run your serv
 pnpm tsx src/server.ts
 ```
 
+**On success you should see:**
+
+```
+Resource server on http://localhost:4021
+```
+
 > ✅ **Success:** The process keeps running and the resource server listens on `http://localhost:4021`
 
 ### 5.2 Test Unpaid Access (Should Be Rejected)
@@ -470,7 +478,7 @@ EVM_RPC_URL=https://bsc-rpc.publicnode.com
 
 ### 3. (Self-Hosted) Switch the Facilitator to Mainnet
 
-The facilitator's `TRON_NETWORKS` already includes `TRON_MAINNET` (`tron:0x2b6653dc`), and `EVM_NETWORKS` includes `eip155:56`. Fund the Facilitator wallet with real TRX/BNB to cover settlement gas, then restart:
+The example facilitator's `TRON_NETWORKS` already includes `TRON_MAINNET` (`tron:0x2b6653dc`), and `EVM_NETWORKS` includes `eip155:97` and `eip155:56` — Base (`eip155:8453` / `eip155:84532`) is not registered there, so add it if you settle on Base. Fund the Facilitator wallet with real TRX/BNB to cover settlement gas, then restart:
 
 ```bash
 pnpm dev:facilitator
diff --git a/docs/x402/index.md b/docs/x402/index.md
index d2b0c21..55bf693 100644
--- a/docs/x402/index.md
+++ b/docs/x402/index.md
@@ -87,11 +87,12 @@ Our goal is to build a low-barrier, permissionless, developer-friendly programma
 x402 currently supports the following networks:
 
 - **TRON Mainnet** (`tron:0x2b6653dc`)
-- **TRON Shasta Testnet** (`tron:0x94a9059e`)
+- **TRON Shasta Testnet** (`tron:0x94a9059e`) — SDK/CLI only; not settled by the official facilitator
 - **TRON Nile Testnet** (`tron:0xcd8690dc`)
 - **BSC Mainnet** (`eip155:56`)
 - **BSC Testnet** (`eip155:97`)
 - **Base Mainnet** (`eip155:8453`)
+- **Base Sepolia Testnet** (`eip155:84532`)
 
 Base Mainnet payments use official USDC with the `exact` scheme and EIP-3009 authorization.
 
diff --git a/docs/x402/sdk-features.md b/docs/x402/sdk-features.md
index a3a6ad1..9d8f3f4 100644
--- a/docs/x402/sdk-features.md
+++ b/docs/x402/sdk-features.md
@@ -8,6 +8,8 @@ description: 'Feature support matrix for the x402 TypeScript SDK, published as g
 This page tracks the feature support of the x402 SDK.
 
 > **SDK (TypeScript-only)**: x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` npm packages. The source is maintained in a pnpm/turbo monorepo, but applications should depend on the published packages. The previous-generation Python + TypeScript SDK lives under `legacy/` for reference.
+>
+> **Current release: 1.1.0** (2026-08-25). All 11 `@bankofai/x402-*` packages ship together and pin their internal dependencies to `~1.1.0`, so upgrade them as a set. The SDK requires **Node.js 22+**.
 
 ---
 
@@ -58,7 +60,7 @@ This page tracks the feature support of the x402 SDK.
 | `eip155:8453` (Base Mainnet) | - | ✅ |
 | `eip155:84532` (Base Sepolia) | - | ✅ (CLI/SDK testing) |
 
-> Other upstream EVM chains (MegaETH, Monad, Hyperliquid) are also wired in the EVM default-asset registry. The public API Catalog publishes Base Mainnet routes only; Base Sepolia remains available for CLI/SDK testing.
+> Around 20 further upstream EVM chains (MegaETH, Monad, Polygon, Arbitrum One/Sepolia, Celo, XDC, Flare, Mezo, Radius, Stable, ADI, HPP, Igra, …) are also wired into the EVM default-asset registry. The public API Catalog publishes Base Mainnet routes only; Base Sepolia remains available for CLI/SDK testing.
 
 ---
 
@@ -73,6 +75,20 @@ x402 supports four payment schemes. Each is implemented as a client + server + f
 | `batch-settlement` | ✅ | ✅ | Payment-channel: deposit once on-chain, then pay many requests with off-chain vouchers; the facilitator claims a batch and settles in one tx. Includes a refund path. |
 | `exact_gasfree` | ❌ | ✅ | TRON-only. Pay with USDT/USDD **without holding TRX for gas** — a relayer pays the on-chain energy via the GasFree API. |
 
+### Payment flows (new in 1.1.0)
+
+A scheme/network server now declares which payment flows it supports per asset-transfer method. `upfront` and `escrow` travel on the wire as `extra.paymentFlow`; `authorization` is the default and is omitted from `extra` — its absence is the signal:
+
+| Flow | What it means |
+|------|---------------|
+| `authorization` | The client signs an authorization and the facilitator pulls the funds at settlement — the classic `exact` / `upto` behavior, and the default. |
+| `upfront` | The client moves the funds before the resource is served. |
+| `escrow` | Funds are locked in escrow first, then captured, voided, or refunded later, instead of moving straight to the seller. |
+
+Legacy v1.0 `SchemeNetworkServer` implementations may omit their payment-flow declaration; they continue to use the authorization flow.
+
+`upfront` and `escrow` are orchestration hooks for custom schemes. As of 1.1.0 every built-in server scheme (`exact`, `upto`, `batch-settlement`, `exact_gasfree`) declares `authorization` only, so `extra.paymentFlow` does not appear on the wire with the shipped schemes.
+
 > **x402 Foundation v2 compatibility**: The `exact` scheme (EVM and TRON) conforms to the v2 wire format published by the **x402 Foundation**. Stock v2 clients interoperate with this SDK's server and vice versa. See [Network & Token Support → `exact` Scheme](./core-concepts/network-and-token-support.md#exact-scheme) for details.
 
 ---
@@ -88,6 +104,7 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 | `createFacilitatorTronSigner` | Facilitator (TRON) |
 | `createFacilitatorEvmSigner` | Facilitator (EVM) |
 | `createAuthorizerTronSigner` | Authorizer (TRON, batch-settlement) |
+| `createAuthorizerEvmSigner` | Authorizer (EVM, batch-settlement) |
 
 ---
 
@@ -103,6 +120,14 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 | Balance-aware payment selection (`filterAffordableRequirements`) | ✅ |
 | Cheapest-token selection strategy | ✅ |
 | GasFree (zero-gas TRON payments) | ✅ |
+| Spend controls (default-asset allowlist + per-payment cap) | ✅ — **on by default since 1.1.0** |
+| Per-asset atomic caps (`allowedAssets[].maxAmountPerPayment`) | ✅ |
+| Payment-selection policies (`PaymentPolicy`) | ✅ |
+| Lifecycle hooks (`onBeforePaymentCreation`, `onAfterPaymentCreation`, `onPaymentCreationFailure`, `onPaymentResponse`) | ✅ |
+
+:::caution Spend controls are on by default
+Since 1.1.0 a client will only pay assets it recognizes from the default-asset registry, and caps each payment at `DEFAULT_MAX_AMOUNT_PER_PAYMENT` (`$1` worth). To pay more than that, raise the cap with `spendControls.maxAmountPerPayment` (a `Money` value, or `false` to remove it). To pay a custom token, list it under `spendControls.allowedAssets` — optionally with its own `maxAmountPerPayment`, which must be an integer atomic amount rather than a dollar value — or set `allowedAssets: true` to allow any asset. `spendControls: false` turns the guard off entirely.
+:::
 
 ---
 
@@ -115,7 +140,6 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 | Gas-sponsoring extension (Permit2 approve) | ✅ |
 | Payment verification (via facilitator) | ✅ |
 | Payment settlement (via facilitator) | ✅ |
-| Fee support | ✅ |
 
 ---
 
@@ -129,8 +153,11 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 | Submit on-chain transaction | ✅ |
 | Confirm transaction (receipt polling) | ✅ |
 | Extension hooks (`onBeforeSettle` / `onAfterSettle` / `onSettleFailure`) | ✅ |
+| EVM smart accounts — deployed accounts, ERC-7702 delegation, ERC-6492 counterfactual wallets | ✅ — signature verification is facilitator-side; ERC-6492 requires an explicit `eip6492AllowedFactories` allowlist |
 
-> The self-hosted example facilitator (`facilitator/basic`) exposes `/verify`, `/settle`, `/supported`. The official hosted facilitator additionally offers `/fee/quote` and `/payments/{id}` query endpoints — see [Official Facilitator](./core-concepts/OfficialFacilitator.md).
+> The self-hosted example facilitator (`facilitator/basic`) exposes `/verify`, `/settle`, `/supported`. The official hosted facilitator additionally offers the settlement-record queries `GET /payments/tx/{tx_hash}` and `GET /payments`, plus `/health` — see [Official Facilitator](./core-concepts/OfficialFacilitator.md). Prometheus metrics are served on a separate monitoring port (`9001` in the shipped configs), not on the public API base. There is no `/fee/quote` endpoint: the SDK schemes carry no facilitator fee.
+>
+> `HTTPFacilitatorClient` uses typed timeout errors, rate-limit retries, and a 90-second default timeout since 1.1.0.
 
 ---
 
@@ -138,7 +165,7 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 
 | Token | Network | Status |
 |--------|---------|--------|
-| USDT (TRC-20) | `tron:0x2b6653dc`, `tron:0xcd8690dc` | ✅ |
+| USDT (TRC-20) | `tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e` | ✅ |
 | USDD (TRC-20) | `tron:0x2b6653dc`, `tron:0xcd8690dc` | ✅ |
 | USDT (BEP-20) | `eip155:56`, `eip155:97` | ✅ |
 | USDC (BEP-20) | `eip155:56`, `eip155:97` | ✅ |
@@ -146,6 +173,8 @@ Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wall
 | Official USDC (ERC-20, EIP-3009) | `eip155:8453`, `eip155:84532` | ✅ |
 | Custom TRC-20 / BEP-20 | any | ✅ (via token registry / `EVM_TOKENS` config) |
 
+> Only some of these are **default assets**: USDT on TRON and BSC Mainnet, USDC on BSC Testnet and Base. Since 1.1.0 a client's spend controls reject every other asset — USDD, BSC Mainnet USDC, BSC Testnet USDT, DHLU, custom tokens — unless it is allowlisted via `spendControls.allowedAssets`. See [Network & Token Support](./core-concepts/network-and-token-support.md#supported-tokens).
+
 ---
 
 ## Observability
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
index 3ebc33e..1df9713 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
@@ -7,6 +7,33 @@ description: 'BANK OF AI 各产品的更新与公告——全部产品，按时
 
 BANK OF AI 各产品的更新与公告。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-08-25</div>
+<div className="changelog-body">
+
+### x402 SDK v1.1.0 · 文档
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">x402</span><span className="changelog-tag">文档</span></div>
+
+- **x402 SDK 1.1.0**——付款流程显式化（`upfront` / `escrow` 通过 `extra.paymentFlow` 在协议中传递，默认 `authorization`）、客户端消费管控默认开启（单笔约 `$1` 上限 + 默认资产白名单）、付款选择策略与生命周期钩子、EVM 智能账户支持（ERC-7702、白名单内 ERC-6492），`HTTPFacilitatorClient` 默认超时 90 秒。11 个包需整体升级，要求 Node.js 22+。[SDK 功能矩阵](../x402/sdk-features/)
+- **文档订正**——移除已废弃的 facilitator 计费内容（`base_fee`、`extra.fee`、`/fee/quote`）；官方部署的匿名 `/settle` 限速为每分钟 1 次；不再宣称 GasFree 会被自动优选——CLI 取第一条匹配过滤条件的支付要求，需要强制时请传 `--scheme exact_gasfree`；TRON Shasta 现已注明「SDK/CLI 可签名、但官方 facilitator 不结算」（请用 Nile 或自建）；CLI 页面标明了它的**锁定依赖**——CLI 1.0.2 内含的 `@bankofai/x402-*` SDK 包仍是 1.0.1（`x402-gateway` 为 1.0.2），因此尚不具备 1.1.0 的客户端消费管控；Skills 各页的安装命令统一改为 `npx skills add … -g`。[x402 文档](../x402/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-08-20</div>
+<div className="changelog-body">
+
+### Facilitator —— BSC 回执可靠性
+
+<div className="changelog-tags"><span className="changelog-tag">修复</span><span className="changelog-tag">Facilitator</span></div>
+
+- **BSC 主网**（`eip155:56`）的结算回执查询新增备用 RPC 兜底，单个节点无响应不再把已结算的付款误判为失败。[官方 Facilitator](../x402/core-concepts/OfficialFacilitator/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-07-30</div>
 <div className="changelog-body">
@@ -22,13 +49,29 @@ BANK OF AI 各产品的更新与公告。
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-07-29</div>
+<div className="changelog-body">
+
+### 官方 Facilitator —— 支持 Base 结算
+
+<div className="changelog-tags"><span className="changelog-tag">更新</span><span className="changelog-tag">Facilitator</span><span className="changelog-tag">Base</span></div>
+
+- 官方 facilitator 现已结算 **Base USDC**——在 TRON 主网/Nile 与 BSC 主网/测试网之外，新增启用 `eip155:8453`（主网）与 `eip155:84532`（Sepolia）。仓库自带的示例 facilitator 在 EVM 侧仍只注册 `eip155:97` 与 `eip155:56`，自托管的 Base 卖家需自行添加。[官方 Facilitator](../x402/core-concepts/OfficialFacilitator/)
+- **自托管破坏性变更**——facilitator 配置只接受规范 CAIP-2 标识符；`bsc:mainnet`、`tron:nile` 这类友好别名不再解析，启动时直接报错。
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-07-21</div>
 <div className="changelog-body">
 
 ### 文档
 
-<div className="changelog-tags"><span className="changelog-tag">产品更新</span><span className="changelog-tag">文档</span><span className="changelog-tag">x402</span></div>
+<div className="changelog-tags"><span className="changelog-tag">产品更新</span><span className="changelog-tag">文档</span><span className="changelog-tag">x402</span><span className="changelog-tag">SKILLS</span></div>
+
+- **SKILLS —— `x402-payment` 改用 `x402-cli` 付款**（1.0.1 及以上），不再使用内置本地脚本；新增 `--dry-run` 预览、`--max-amount` 限额、GasFree 必须限费，以及规范的 CAIP-2 TRON 标识符。[详情](./skills/)
 
 - **TRON 网络标识符全面改用 CAIP-2 格式**——`tron:0x2b6653dc`（主网）、`tron:0xcd8690dc`（Nile）、`tron:0x94a9059e`（Shasta）。应用代码中建议使用 SDK 常量 `TRON_MAINNET` / `TRON_NILE` / `TRON_SHASTA`，而不是硬编码十六进制字符串。[网络与代币支持](../x402/core-concepts/network-and-token-support/)
 - **移除 `auth-capture` 方案**——x402 现记录四种支付方案：`exact`、`upto`、`batch-settlement` 与 `exact_gasfree`（TRON）。[SDK 功能](../x402/sdk-features/)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
index 7781657..48f175c 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
@@ -7,6 +7,24 @@ description: 'SKILLS 的版本发布记录。'
 
 SKILLS 的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-07-21</div>
+<div className="changelog-body">
+
+### x402-payment 改用 x402 CLI
+
+<div className="changelog-tags"><span className="changelog-tag">更新</span><span className="changelog-tag">x402</span></div>
+
+- **支付统一走 `x402-cli`**（1.0.1 及以上），不再使用技能内置的本地 TypeScript 脚本。技能会校验你已装的版本，缺失时告诉你如何安装。
+- **每笔付款先预览、再限额**——首次调用陌生端点前先跑 `--dry-run --json` 预览，真实付款带 `--max-amount`。GasFree 付款还必须用 `--max-gasfree-fee` 给中继费单独限额，因为付款上限并不包含它。
+- **只接受规范的 CAIP-2 TRON 标识符**——`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`；`tron:mainnet` 这类简写会被拒绝。`agent-wallet` 技能同样改用这套标识符。
+- 已下线的 `--gasfree-info` / `--gasfree-activate` 脚本参数被移除；卸载脚本现在支持自定义技能目录。
+
+👉 [技能目录](/zh-Hans/McpServer-Skills/SKILLS/BANKOFAISkill/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-07-10</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
index 65faa74..b290d32 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
@@ -5,7 +5,40 @@ description: 'x402 支付协议、SDK 与 CLI 的版本发布记录。'
 
 # x402支付协议
 
-x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
+x402 协议、SDK 与 [CLI](/zh-Hans/x402/cli/) 的版本发布记录。
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-08-25</div>
+<div className="changelog-body">
+
+### x402 SDK v1.1.0 —— 付款流程与钱包兼容
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">SDK</span></div>
+
+- **付款流程改为显式声明**——scheme/network server 按资产转账方式声明支持的流程。`upfront` 与 `escrow` 通过 `extra.paymentFlow` 传递；`authorization` 仍是默认流程，不写入 `extra`。未声明流程的 v1.0 服务端继续沿用 authorization。
+- **客户端消费管控默认开启**——client 只支付默认资产注册表中认识的资产，且每笔上限为 `DEFAULT_MAX_AMOUNT_PER_PAYMENT`（约合 `$1`）。可用 `spendControls.maxAmountPerPayment` 提高上限、用 `spendControls.allowedAssets` 放行自定义代币，或用 `spendControls: false` 关闭该防护。
+- **付款选择策略与生命周期钩子**——新增 `PaymentPolicy`，以及 `onBeforePaymentCreation` / `onAfterPaymentCreation` / `onPaymentCreationFailure` / `onPaymentResponse`。
+- **EVM 钱包兼容性**——支持已部署的智能账户、ERC-7702 委托，以及白名单内的 ERC-6492 反事实钱包；ERC-6492 需要在 facilitator 上显式配置 `eip6492AllowedFactories`。
+- **`HTTPFacilitatorClient`** 新增带类型的超时错误、限流重试、更严格的响应校验，默认超时 90 秒。
+- **11 个 `@bankofai/x402-*` 包需整体升级**——内部依赖解析为 `~1.1.0`。SDK 要求 **Node.js 22+**。自定义 money parser 现在接收十进制字符串。
+
+👉 [SDK 功能矩阵](/zh-Hans/x402/sdk-features/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-08-20</div>
+<div className="changelog-body">
+
+### Facilitator —— BSC 回执可靠性
+
+<div className="changelog-tags"><span className="changelog-tag">修复</span><span className="changelog-tag">Facilitator</span></div>
+
+- **BSC 主网**（`eip155:56`）上的结算回执查询新增备用 RPC 兜底，单个节点无响应不再把已结算的付款误判为失败。
+
+</div>
+</div>
 
 <div className="changelog-entry">
 <div className="changelog-date">2026-07-30</div>
@@ -16,13 +49,13 @@ x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
 <div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">CLI</span><span className="changelog-tag">Base</span></div>
 
 - **支持 Base**——`eip155:8453`（主网）与 `eip155:84532`（Sepolia），均支持 USDC，并提供 `base-mainnet` / `base-sepolia` 别名。Base 走标准 `exact` 方案，但使用 **EIP-3009** 授权而非 Permit2。生产环境请通过 `--rpc-url` 或 `EVM_RPC_URL_8453` / `EVM_RPC_URL_84532` 自备 RPC。
-- **Agent Wallet 成为默认付款方**——`pay` 会解析你当前激活的 [Agent Wallet](/Agent-Wallet/Intro/) 并交由它签名，私钥不再需要放进环境变量。如果配置了钱包但没有激活项，CLI 会**在签名前停下**而不是替你选一个。可用 `--wallet-id` / `AGENT_WALLET_ID` 显式指定，或用 `AGENT_WALLET_DIR` 指向其他目录。私钥现在只作为开发/CI 的覆盖手段。
+- **Agent Wallet 成为默认付款方**——`pay` 会解析你当前激活的 [Agent Wallet](/zh-Hans/Agent-Wallet/Intro/) 并交由它签名，私钥不再需要放进环境变量。如果配置了钱包但没有激活项，CLI 会**在签名前停下**而不是替你选一个。可用 `--wallet-id` / `AGENT_WALLET_ID` 显式指定，或用 `AGENT_WALLET_DIR` 指向其他目录。私钥现在只作为开发/CI 的覆盖手段。
 - **付费请求不再跟随重定向**，确保 `PAYMENT-SIGNATURE` 不会被转发到其他源。
 - **EVM 余额预检**——签名前校验付款方代币余额，并返回解析出的钱包 ID、地址与原始余额。
 - 新增：`pay --asset` / `--decimals`、`serve --valid-for-seconds`（默认 `300`），以及 `roundtrip --json` 输出单个文档、内含独立的 `serve` 与 `pay` 结果。
 - 新增钱包类错误码：`WALLET_PASSWORD_REQUIRED`、`WALLET_DECRYPTION_FAILED`、`WALLET_CONFIG_CORRUPT`、`WALLET_NETWORK_ERROR`。
 
-👉 [x402 CLI 文档](/x402/cli/)
+👉 [x402 CLI 文档](/zh-Hans/x402/cli/)
 
 </div>
 </div>
@@ -38,7 +71,24 @@ x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
 - 发布 `eip155:8453` **Base 主网目录路由**，配套支付指引与代码示例。CLI 仍支持 Base Sepolia，但服务目录未发布 Base Sepolia 路由。
 - `assetTransferMethod` 现在除 `permit2` 外还接受 **`eip3009`**——Base USDC 路由使用 `eip3009`。
 
-👉 [API Catalog 参考](/x402/api-catalog/reference/)
+👉 [API Catalog 参考](/zh-Hans/x402/api-catalog/reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-07-29</div>
+<div className="changelog-body">
+
+### 官方 Facilitator —— 支持 Base 结算
+
+<div className="changelog-tags"><span className="changelog-tag">更新</span><span className="changelog-tag">Facilitator</span><span className="changelog-tag">Base</span></div>
+
+- 官方 facilitator 现已结算 **Base USDC**：在 TRON 主网/Nile、BSC 主网/测试网之外，新增启用 `eip155:8453`（主网）与 `eip155:84532`（Sepolia）。
+- 所有已启用网络均注册 `exact`、`upto` 与 `batch-settlement`；TRON 在服务持有 GasFree 中继凭证的网络上额外注册 `exact_gasfree`。以 `/supported` 返回为准。仓库自带的示例 facilitator（`facilitator/basic`）在 EVM 侧仍只注册 `eip155:97` 与 `eip155:56`（其 `TRON_NETWORKS` 已含 Nile/Shasta/主网），自托管的 Base 卖家需自行把 Base 的网络 ID 加进 `EVM_NETWORKS`。
+- **自托管破坏性变更**——facilitator 配置只接受规范 CAIP-2 标识符；`bsc:mainnet`、`tron:nile` 这类友好别名不再解析，启动时直接报错。[网络与代币支持](/zh-Hans/x402/core-concepts/network-and-token-support/)
+
+👉 [官方 Facilitator](/zh-Hans/x402/core-concepts/OfficialFacilitator/)
 
 </div>
 </div>
@@ -56,7 +106,7 @@ x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
 - **结算状态**——已付款响应区分 `settled`（支付已在链上结算）与 `delivered`（上游 HTTP 响应成功）。
 - 基于 x402 SDK 1.0.1 构建。
 
-👉 [x402 CLI 文档](/x402/cli/)
+👉 [x402 CLI 文档](/zh-Hans/x402/cli/)
 
 </div>
 </div>
@@ -73,7 +123,7 @@ x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
 - 网络标识必须使用**标准 CAIP-2**；旧的 TRON 别名如 `tron:nile` 会被 schema 校验拒绝。
 - 在 x402 SDK 1.0.1 下，GasFree 费用由客户端估算——目录路由不再发布旧的 `fee` / `feeConfig` 字段。
 
-👉 [API Catalog 参考](/x402/api-catalog/reference/)
+👉 [API Catalog 参考](/zh-Hans/x402/api-catalog/reference/)
 
 </div>
 </div>
@@ -95,7 +145,7 @@ x402 协议、SDK 与 [CLI](/x402/cli/) 的版本发布记录。
 - 基于已发布的 `@bankofai/x402-core` / `x402-evm` / `x402-tron` SDK 1.0 包构建；`scheme=exact` 配合 Permit2
 - 支持网络：TRON（`tron:mainnet` / `tron:nile` / `tron:shasta`）与 BSC（`eip155:56` / `eip155:97`）
 
-👉 立即上手：[x402 CLI 快速开始](/x402/cli/quickstart/)
+👉 立即上手：[x402 CLI 快速开始](/zh-Hans/x402/cli/quickstart/)
 
 </div>
 </div>
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/x402-stablecoin-payments-for-agents.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/x402-stablecoin-payments-for-agents.md
index d264111..7e90baf 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/x402-stablecoin-payments-for-agents.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/x402-stablecoin-payments-for-agents.md
@@ -81,7 +81,7 @@ BANK OF AI x402 完全兼容 Coinbase x402 的核心 HTTP 支付协议与交互
 
 `exact_gasfree` 是 TRON 专用的固定金额方案。付款人可使用 USDT 或 USDD 支付，而无需在自己的普通钱包中持有 TRX；官方 GasFree Proxy/中继路径负责提交交易并支付相应的链上资源费用。
 
-这不是普适的「免成本」付款。该方案要求钱包、Token、GasFree 服务与 Facilitator 都支持相应流程；费用可能通过服务规则、资产余额或报价结构体现。生产部署应显式检查可用资产、GasFree 账户状态、费用配置和失败回退路径，不能仅根据主钱包的 TRX 余额判断是否可付。
+这不是普适的「免成本」付款。该方案要求钱包、Token、GasFree 服务与 Facilitator 都支持相应流程；其成本体现为 GasFree **中继费**：由客户端估算，并在付款金额之外从支付代币中扣除——支付要求本身不含任何费用对象。生产部署应显式检查可用资产、GasFree 账户状态、费用配置和失败回退路径，不能仅根据主钱包的 TRX 余额判断是否可付。
 
 ### 4.3 Upto：按实际用量支付
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
index 102932a..1e5d90c 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
@@ -19,7 +19,7 @@
 在你正在用的 AI 客户端（OpenClaw / Claude Code / Cursor / Codex 等）里粘贴这段指令：
 
 ```
-运行 npx skills add BofAI/skills 安装 BANK OF AI 全部技能，安装完成后使用 bankofai-guide 进行引导后续操作。
+运行 npx skills add BofAI/skills -g 安装 BANK OF AI 全部技能，安装完成后使用 bankofai-guide 进行引导后续操作。
 注意：请安装到当前 Agent 对应的 skill 目录
 ```
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
index a25572b..1610e88 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
@@ -93,7 +93,7 @@ AI 的安全签名引擎。这个技能帮你的 AI 创建和管理加密钱包
 
 > 第一次设置？ "帮我创建一个新的 agent 钱包"——AI 会引导你选择钱包类型（`local_secure` 是加密的本地私钥，`privy` 则是通过 API 凭证接入的托管钱包）、生成密钥并保存主密码。
 
-> 管理多条链？ "帮我看看所有钱包和它们的地址"——同一个钱包会自动生成 EVM 和 TRON 两个地址。EVM 网络使用 `eip155:<chainId>`（如 `eip155:1` 以太坊、`eip155:56` BSC、`eip155:137` Polygon、`eip155:42161` Arbitrum、`eip155:8453` Base），TRON 使用 `tron:mainnet` / `tron:nile`。
+> 管理多条链？ "帮我看看所有钱包和它们的地址"——同一个钱包会自动生成 EVM 和 TRON 两个地址。EVM 网络使用 `eip155:<chainId>`（如 `eip155:1` 以太坊、`eip155:56` BSC、`eip155:137` Polygon、`eip155:42161` Arbitrum、`eip155:8453` Base），TRON 使用规范的 CAIP-2 ID：`tron:0x2b6653dc`（主网）、`tron:0xcd8690dc`（Nile）、`tron:0x94a9059e`（Shasta）。
 
 > 需要签名？ "帮我在 BSC 上签名这笔交易"——AI 在本地完成签名，不会广播上链。支持原始交易、EIP-191 消息以及 EIP-712 typed data（仅 EVM）。
 
@@ -422,28 +422,36 @@ PSM 支持 **USDT ↔ USDD 即时 1:1 兑换**——是获取 USDD 最简单的
 
 ## x402-payment {#x402-payment}
 
-有些高级 API 和 AI 智能体是收费的——需要你先完成链上付费才能使用。这个技能通过 x402 协议帮你自动完成"先付费、再获取"的链上结算流程：AI 发现对方要收费，自动帮你完成链上支付，拿到结果后汇报给你。每次付款前同样会先问你确认。支持多条链付款——**TRON（TRC20：USDT、USDD）**和 **BSC（ERC20：USDT、USDC）** 都可选（付款各自在对应链上结算，不是跨链桥接），主网与测试网（Nile / BSC testnet）均兼容。
+有些高级 API 和 AI 智能体是收费的——需要你先完成链上付费才能使用。这个技能通过 x402 协议帮你自动完成"先付费、再获取"的链上结算流程：AI 发现对方要收费，先预览费用，再帮你完成链上支付，拿到结果后汇报给你。每次付款前同样会先问你确认。支付统一走 `x402-cli` 命令行工具（要求 **1.0.1 及以上**）。技能会先检查你已装的版本，缺失时会告诉你如何安装（`npm install -g @bankofai/x402-cli@1.0.1`，技能锁定的版本；CLI 自身最新版为 1.0.2）——不再使用本地支付脚本。支持在 **TRON（TRC20：USDT、USDD）** 与 **BSC（ERC20：主网 USDT；测试网 USDT、USDC）** 上结算——付款各自在对应链上完成，不是跨链桥接。
 
 **绝对安全，只看不花钱：**
 
-> 验证一下我的 x402 钱包状态（地址和就绪情况）。
+> 看一下我装没装 x402-cli，版本是多少。
 
-> 查一下我的 GasFree 钱包信息（地址、激活状态、余额）。
+> 先别付款，帮我预览一下这个端点会收多少钱：https://api.example.com/protected
 
-> 帮我拉取这个 x402 智能体的 manifest：https://api.example.com/.well-known/agent.json
+> 先别付款，把这个端点会收多少钱列给我看：https://api.example.com/protected
 
 **需要你确认才会执行：**
 
-> 使用 x402 协议调用这个付费智能体端点：https://api.example.com （请替换为你实际要调用的付费端点地址）
+> 使用 x402 协议调用这个付费智能体端点，最多花 0.01 USDT：https://api.example.com （请替换为你实际要调用的付费端点地址）
 
-> 在 nile 上用 USDT 激活我的 GasFree 账户。
+> 在 Nile 上用 USDT 走 GasFree 付这个端点，付款上限 0.01，中继费上限 0.5。
+
+:::tip 先预览，再限额
+第一次调用陌生端点时，技能会先跑一次空跑预览（`x402-cli pay <url> --dry-run --json`），把网络、方案、代币和确切金额摆给你看。除非你明确认可端点公布的确切金额，真正付款时都会带上花费上限（`--max-amount`），付款本身不会超过你批准的金额——GasFree 的中继费另计，需单独限额（见下方说明）。
+:::
 
 :::tip GasFree 支持（TRON）
-在 TRON 上付款时，技能会优先选择 `exact_gasfree` 方案；如果 GasFree 创建支付载荷失败，会自动回退到 `exact`。GasFree 钱包需要有足够代币余额；未激活账户在服务端声明的费用允许时可在首次付款时激活。可用 `--gasfree-info` 查看 GasFree 地址、激活状态、余额和 nonce；需要手动激活时用 `--gasfree-activate`。
+GasFree（`scheme=exact_gasfree`）让你在 TRON 上付款时不必持有 TRX 抵扣能量——由中继方垫付网络开销，改从支付代币里收取一笔中继费（即中继服务的服务费：每笔一个固定转账费，账户首次使用另加一次性激活费，从你的 GasFree 账户扣除）。CLI 取的是端点提供的、第一条符合你条件的付款方式，并不会优先选 GasFree；只要端点同时也提供普通 TRON 付款，就直接说"必须用 GasFree"。你的 GasFree 账户需要有足够代币，**同时**覆盖付款金额和中继费。由于付款上限并不包含中继费，除非你明确认可估算值，否则每笔 GasFree 付款都会再加一道中继费上限（`--max-gasfree-fee`）。GasFree 仅支持 TRON，不能与 BSC（`eip155:*`）网络组合使用。
+:::
+
+:::info 网络统一使用规范的 CAIP-2 ID
+`tron:0x2b6653dc`（TRON 主网 —— USDT、USDD）、`tron:0xcd8690dc`（Nile —— USDT、USDD）、`tron:0x94a9059e`（Shasta —— USDT）、`eip155:56`（BSC —— USDT）、`eip155:97`（BSC 测试网 —— USDT、USDC）。`tron:mainnet` 这类简写别名已不再受支持。
 :::
 
 :::caution 钱包凭证来自 agent-wallet
-这个技能只通过 `agent-wallet` 加载签名凭证，**不会**从其他随意的配置文件里读取明文私钥。加密本地模式请设置 `AGENT_WALLET_PASSWORD`，静态模式请设置 `AGENT_WALLET_PRIVATE_KEY` 或 `AGENT_WALLET_MNEMONIC`。需要 Node.js 20+。
+这个技能只通过 `agent-wallet` 加载签名凭证，**不会**从其他随意的配置文件里读取明文私钥，也不会接受你在对话里直接输入的私钥。加密本地模式请设置 `AGENT_WALLET_PASSWORD`，静态模式请设置 `AGENT_WALLET_PRIVATE_KEY` 或 `AGENT_WALLET_MNEMONIC`。需要 Node.js 20+。
 :::
 
 ---
@@ -500,9 +508,9 @@ PSM 支持 **USDT ↔ USDD 即时 1:1 兑换**——是获取 USDD 最简单的
 
 把整套技能串起来的引导助手。你通常不需要主动调用它——它会在下面三种场景里自动登场：
 
-1. **安装后首次配置。** 你一跑完 `npx skills add BofAI/skills`，安装器就会把控制权交给 `bankofai-guide`。它会全局安装 `@bankofai/agent-wallet` CLI，检查你是否已经有钱包，并询问你是现在就创建一个，还是稍后再说。
+1. **安装后首次配置。** 你一跑完 `npx skills add BofAI/skills -g`，安装器就会把控制权交给 `bankofai-guide`。它会全局安装 `@bankofai/agent-wallet` CLI，检查你是否已经有钱包，并询问你是现在就创建一个，还是稍后再说。
 2. **首个钱包创建。** 如果你还没钱包，它会给你两条路：**快速模式**（强烈推荐——全自动，约 10 秒搞定，生成加密的 `local_secure` 钱包和一个强随机密码）和**详细模式**（一步一步走，自定义选项更多）。钱包就绪后，它会把 EVM 地址和 TRON 地址一起展示给你，并告诉你该往哪充 USDT。
-3. **钱包守门员。** 需要签名的技能（`sunswap`、`sunperp-skill`、`trc20-toolkit-skill`、`multisig-permissions`、`x402-payment`）在执行链上操作之前会先跑 `agent-wallet list` 自查钱包状态；**只有在发现没有钱包时**，才会调用 `bankofai-guide` 暂停当前操作，用一两分钟帮你补上，然后回到原来的流程。
+3. **钱包守门员。** 需要签名的技能（`sunswap`、`sunperp-skill`、`sunpump-agent-skill`、`trc20-toolkit-skill`、`multisig-permissions`）在执行链上操作之前会先跑 `agent-wallet list` 自查钱包状态；**只有在发现没有钱包时**，才会调用 `bankofai-guide` 暂停当前操作，用一两分钟帮你补上，然后回到原来的流程。
 
 **可以触发它的参考话术：**
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
index b3c5c7f..7efe995 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
@@ -173,10 +173,10 @@ export TRON_HUMAN_PRIVATE_KEY="人类审批者的私钥"
 rm -rf ~/.agents/skills/sunswap-dex-trading
 ```
 
-**更新：** 重新运行安装命令，会自动更新所有技能到最新版本。
+**更新：** 重新运行安装命令（保留 `-g`，更新的才是全局那份），会自动更新所有技能到最新版本。
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
 ---
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
index 5fbdc91..5accd65 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
@@ -22,7 +22,7 @@
 2. 复制下面这段 prompt 发送给 AI：
 
    ```
-   运行 npx skills add BofAI/skills 安装 BANK OF AI 全部技能，安装完成后使用 bankofai-guide 进行引导后续操作。
+   运行 npx skills add BofAI/skills -g 安装 BANK OF AI 全部技能，安装完成后使用 bankofai-guide 进行引导后续操作。
    注意：请安装到当前 Agent 对应的 skill 目录
    ```
 
@@ -42,19 +42,19 @@
 如果你已经装好 Node.js 并习惯使用命令行，告诉你的 AI Agent 执行以下命令：
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
-`-y` 参数会跳过所有交互选择，默认安装所有 Skills。安装完成后会显示 ✅ 安装完成！以及安装的所有 Skills 列表。
+`-y` 参数会跳过所有交互选择，默认安装所有 Skills；`-g` 参数把技能装到**全局**（用户级，目录为 `~/.agents/skills/`），所有项目都能用——这个参数请保留，否则只会装进你当前所在的目录。安装完成后会显示 ✅ 安装完成！以及安装的所有 Skills 列表。
 
 ---
 
 ### 方式三：交互式安装（最精细控制）
 
-如果你想手动选择安装哪些 Skills 以及安装范围，去掉 `-y` 参数即可：
+如果你想手动选择安装哪些 Skills、装到哪些 AI 工具，去掉 `-y` 参数、保留 `-g` 即可：
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -g
 ```
 
 :::tip 提示
@@ -89,16 +89,16 @@ npx skills add https://github.com/BofAI/skills
 安装器会自动检测你电脑上装了哪些 AI 工具（如 Cursor、Claude Code、Cline 等），用空格键勾选你要用的：
 
 ```
-◇  71 agents
+◇  77 agents
 ◇  Which agents do you want to install to?
 │  Amp, Antigravity, Antigravity CLI, Cline, Codex, Cursor, Deep Agents,
 │  Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp, Zed,
-│  Claude Code, OpenClaw … （共 71 个，按空格勾选你实际在用的）
+│  Claude Code, OpenClaw … （共 77 个，按空格勾选你实际在用的）
 ```
 
-**3️⃣ 选择安装范围**
+**3️⃣ 安装范围**
 
-选择 `Project`（当前项目）或 `User`（所有项目全局可用），按需选择即可：
+因为你带了 `-g`，安装器会跳过这一步，直接装到用户级目录 `~/.agents/skills/`。不带 `-g` 时才会问你选 `Project`（当前项目）还是 `User`（所有项目全局可用）：
 
 ```
 ◇  Installation scope
@@ -274,6 +274,10 @@ npx skills add https://github.com/BofAI/skills
 └  Done!  Review skills before use; they run with full agent permissions.
 ```
 
+:::info 结尾出现 “Failed to install” 属正常现象
+全局安装的有时会打印 `■  Failed to install 14`，并对每个技能提示 `PromptScript: PromptScript does not support global skill installation`。这只是 PromptScript 这一个客户端没有全局安装位置，不影响其他任何工具。以它上方的 `✓ Installed 14 skills` 清单为准——Claude Code、OpenClaw、Codex 等都已安装成功。
+:::
+
 ### 验证安装
 
 打开你的 AI 对话框，输入：
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
index a0cfb6d..829bf58 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
@@ -87,7 +87,7 @@ x402-cli pay 'https://x402-gateway.bankofai.io/providers/<fqn>/<path>' \
 
 ## 一次付费调用发生了什么
 
-每一笔调用都通过 x402 在链上清算，报价即为实付，始终一致：
+每一笔调用都通过 x402 在链上清算。`exact` 路由报价即为实付；TRON `exact_gasfree` 路由则会由 relayer 额外从支付代币里扣除能量费，请用 `--max-gasfree-fee` 限额：
 
 1. **Agent 发起调用** —— 请求目标端点。
 2. **网关报价** —— 返回价格（HTTP `402`）。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
index c1d5059..4118f5c 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
@@ -63,13 +63,13 @@ description: catalog.json / pay.md 的字段定义、合法类目与链 ID，以
 | `network` | string | 该路由结算所在的标准 CAIP-2 链 ID（如 `tron:0x2b6653dc`、`eip155:56`、`eip155:8453`）。旧的 TRON 别名如 `tron:nile` 会被 schema 校验拒绝。 |
 | `provider` | string | 处理该网络的 gateway provider `fqn` |
 | `scheme` | string | 该路由的 x402 支付方案：`exact`，或在 TRON 上 `exact_gasfree` —— 由每条路由各自声明 |
-| `assetTransferMethod` | string | `exact` 路由使用的授权方式：TRON 与 BSC 填 `permit2`，Base USDC 填 `eip3009`；`exact_gasfree` 路由**不要**带该字段。 |
+| `assetTransferMethod` | string | `exact` 路由使用的授权方式——只有 `permit2`（TRON 与 BSC）有意义。Base USDC 路由与 `exact_gasfree` 路由**不要**带该字段：Base 的 EIP-3009 `name` / `version` 由 gateway 自行下发，而 `x402-cli` 遇到其他取值会以 `INVALID_PAYMENT_REQUIREMENT` 拒绝。 |
 | `url` | string | 该网络路由的完整 gateway URL |
 
 构建时该字段以 `x402_routes` 透传到产物。存在时，调用方/Agent 按目标支付链选择对应路由；顶层 `url` 仍是默认路由。
 
 :::note GasFree 路由
-在 TRON 上，可以为同一端点在 `exact` 路由之外再加一条 `exact_gasfree` 路由：由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需 TRX。GasFree 路由仅限 TRON，且不能带 `assetTransferMethod`。在 x402 SDK 1.0.1 下，relayer 费用由客户端估算，因此目录路由**不得**再发布旧的 `fee` 或 `feeConfig` 字段。
+在 TRON 上，可以为同一端点在 `exact` 路由之外再加一条 `exact_gasfree` 路由：由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需 TRX。GasFree 路由仅限 TRON，且不能带 `assetTransferMethod`。自 x402 SDK 1.0.1 起（当前版本 1.1.0），relayer 费用由客户端估算，因此目录路由**不得**再发布旧的 `fee` 或 `feeConfig` 字段。
 :::
 
 例如一个端点可以为每条支持的链各提供一条路由 —— TRON 主网、BSC 主网和 Base 主网，各有自己的 `provider` 和 `scheme`。调用时把 `x402-cli pay` 指向所选路由的 `url`，并传入匹配的 `--network` / `--scheme`：
@@ -118,12 +118,13 @@ security   shopping    storage     translation
 |---|---|
 | TRON 主网 | `tron:0x2b6653dc` |
 | TRON Nile 测试网 | `tron:0xcd8690dc` |
-| TRON Shasta 测试网 | `tron:0x94a9059e` |
+| TRON Shasta 测试网 | `tron:0x94a9059e` —— 仅 schema 层面接受：gateway 没有 Shasta 代币注册表，官方 facilitator 也不结算，因此无法支撑真实路由 |
 | BNB Chain (BSC) | `eip155:56` |
 | BNB 测试网 | `eip155:97` |
 | Base 主网 | `eip155:8453` |
+| Base Sepolia 测试网 | `eip155:84532` |
 
-构建时会把每个链 ID 解析为展示元数据（`kind` / `label` / `label_zh`），前端无需自己解析 CAIP-2 —— 见[前端展示字段](#前端展示字段)。
+各条链上实际已上线的路由，以已发布的 `catalog.json` 为准。构建时会把每个链 ID 解析为展示元数据（`kind` / `label` / `label_zh`），前端无需自己解析 CAIP-2 —— 见[前端展示字段](#前端展示字段)。
 
 ## 校验与安全扫描
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/command-reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/command-reference.md
index abcf45f..a09102f 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/command-reference.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/command-reference.md
@@ -43,9 +43,9 @@ x402-cli pay <url> [options]
 
 | 选项 | 说明 |
 | :--- | :--- |
-| `--method <method>` | HTTP 方法（默认：`GET`） |
+| `--method <method>` | HTTP 方法——需大写，且为 `DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST`、`PUT` 之一（默认：`GET`）；其他值会以 `INVALID_ARGUMENT` 失败（退出码 2） |
 | `--header "Name: Value"` | 请求头，可重复 |
-| `--body <body>` | 非 `GET`/`HEAD` 方法的请求体 |
+| `--body <body>` | 请求体；`GET` 与 `HEAD` 会忽略该参数 |
 | `--network <caip2>` | 要求特定网络（如 `tron:0xcd8690dc`、`base-mainnet`） |
 | `--token <symbol>` | 要求特定代币（如 `USDT`、`USDC`） |
 | `--asset <address>` | 要求特定资产合约地址 |
@@ -99,9 +99,9 @@ x402-cli pay https://api.example.com/paid \
 
 ### GasFree 支付（TRON） {#gasfree-payments-tron}
 
-在 TRON 上，`scheme=exact_gasfree` 让一个 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需持有 TRX。当服务端的 `402` 支付要求宣告了该 scheme 时，CLI 通常会自动选用；也可以用 `--scheme exact_gasfree` 显式要求。
+在 TRON 上，`scheme=exact_gasfree` 让一个 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需持有 TRX。CLI **不会**优先选择 GasFree：它取服务端 `accepts` 列表中第一条通过 `--network` / `--scheme` / `--token` 过滤的支付要求。若该端点同时也宣告了普通 `exact`，请传 `--scheme exact_gasfree` 才能确保走免 gas 路径。
 
-GasFree 手续费与宣告的支付金额是**分开**的。设一个手续费上限，CLI 会先估算 relayer 手续费，若估值过高则在签名前拒绝：
+GasFree 手续费与宣告的支付金额是**分开**的——它是中继方的服务费（每笔固定转账费，GasFree 账户未激活时首笔另加一次性激活费），以支付代币从你的 GasFree 账户扣除。对 `exact_gasfree` 支付要求，CLI 一定会估算 relayer 手续费，并在结果中以 `gasfreeEstimate`（含 `fee` 与 `total`）返回；再加上手续费上限后，只要估值或最终签名中的 `maxFee` 超限，就会在签名前中止：
 
 ```bash
 x402-cli pay https://api.example.com/pay \
@@ -112,9 +112,9 @@ x402-cli pay https://api.example.com/pay \
   --json
 ```
 
-`--max-gasfree-fee` 与 `--max-gasfree-fee-raw` 互斥，且仅对 `exact_gasfree` 支付要求生效。用 `--gasfree-api-url <url>` 或 `X402_GASFREE_API_URL` 覆盖 relayer 地址。
+`--max-gasfree-fee` 与 `--max-gasfree-fee-raw` 互斥；若 CLI 选中的支付要求不是 `exact_gasfree`，传这两个参数会以 `INVALID_ARGUMENT` 报错（退出码 2）。用 `--gasfree-api-url <url>` 或 `X402_GASFREE_API_URL` 覆盖 relayer 地址。
 
-已付款的响应会区分 `settled`（支付已在链上结算）与 `delivered`（上游 HTTP 业务响应成功）。一次"结算成功但上游失败"的情况会返回 `paid=true`、`settled=true`、`delivered=false`，并仍带上交易信息——重试前请先核查交易与 provider 行为。
+已付款的响应会区分 `settled`（支付已在链上结算）与 `delivered`（上游 HTTP 业务响应成功）。「结算成功但上游失败」会以退出码 1 和错误封装返回（`ok: false`，`error.code` 为 `HTTP_ERROR`，429 时为 `RATE_LIMITED`），其中 `paid` / `settled` / `delivered` 与 `paymentResponse` 位于 `error.details` 之下。请从那里读取用于对账，切勿盲目重试。
 
 ### 在 Base 上付款 {#paying-on-base}
 
@@ -146,10 +146,13 @@ x402-cli pay https://api.example.com/pay \
 | `TRON_GRID_API_KEY` | TronGrid API Key——设置后可避免公共节点限流 |
 | `X402_TRON_ALLOWANCE_MODE` | TRON 授权额度处理方式，默认 `auto` |
 | `EVM_RPC_URL` | 默认 EVM RPC 地址 |
-| `EVM_RPC_URL_8453` / `EVM_RPC_URL_84532` | Base 主网 / Base Sepolia 的专用 RPC |
+| `EVM_RPC_URL_<chainId>` | 按链的专用 RPC，如 `EVM_RPC_URL_8453`、`EVM_RPC_URL_84532`、`EVM_RPC_URL_56`、`EVM_RPC_URL_97` |
+| `RPC_URL` | 通用 EVM RPC 兜底 |
 | `X402_GASFREE_API_URL` | 覆盖 TRON GasFree relayer 接口地址 |
 | `EVM_PRIVATE_KEY` / `TRON_PRIVATE_KEY` / `PRIVATE_KEY` | 覆盖 Agent Wallet——仅限开发与 CI |
 
+> EVM RPC 取值优先级：`--rpc-url` → `EVM_RPC_URL_<chainId>` → `RPC_URL` → `EVM_RPC_URL` → 内置公共节点。内置节点（BSC 与 Base 都有）仅供开发使用。
+
 ---
 
 ## `serve`
@@ -174,19 +177,18 @@ x402-cli serve --pay-to <address> [options]
 | `--port <port>` | 绑定端口（默认：`4020`） |
 | `--resource-url <url>` | 在支付要求中对外宣告的 URL |
 | `--facilitator-url <url>` | Facilitator 基础 URL（默认：`https://facilitator.bankofai.io`） |
-| `--valid-for-seconds <n>` | 支付要求的有效时长（默认：`300`） |
+| `--valid-for-seconds <n>` | 支付要求的有效时长——整数，1–86400（默认：`300`） |
 | `--timeout-ms <ms>` | Facilitator 超时（毫秒，默认：`30000`） |
 | `-d, --daemon` | 在后台运行并打印子进程 pid |
 | `--json` | 打印结构化 JSON 输出 |
 
-服务暴露四个路由：
+服务暴露以下路由——付费判定看的是 `PAYMENT-SIGNATURE` 请求头，而非 HTTP 方法：
 
 | 路由 | 用途 |
 | :--- | :--- |
 | `GET /health` | 返回 `{ "ok": true }` |
 | `GET /.well-known/x402` | 机器可读的支付元数据（网络、scheme、资产、金额、`payTo`） |
-| `GET /pay` | 返回带 `PAYMENT-REQUIRED` 头的 `402 Payment Required` |
-| `POST /pay` | 校验支付、结算，并返回交易 |
+| `/pay`（任意方法） | 请求未带 `PAYMENT-SIGNATURE` 时返回带 `PAYMENT-REQUIRED` 头的 `402 Payment Required`；带该头时通过 facilitator 校验并结算，返回交易 |
 
 **示例：**
 
@@ -235,7 +237,9 @@ x402-cli gateway <search|start|check|scaffold|catalog> [options]
 | `scaffold <name>` | 生成一个起步用的 `provider.yml` |
 | `catalog <command>` | 构建/校验/搜索网关目录资产 |
 
-`start` 与 `gateway catalog` 需要 `@bankofai/x402-gateway` 运行时。请安装它（`npm install -g @bankofai/x402-gateway`）、从含有 `../x402-gateway/dist/cli.js` 的代码检出中运行，或通过 `--gateway-bin <path>` 指定。
+`gateway start` 会拉起一个 gateway 运行时，但 CLI 本身已经带了一份：发布包内含 `dist/gateway/cli.js`，并依赖 `@bankofai/x402-gateway`，因此正常 `npm install -g @bankofai/x402-cli` 之后无需额外安装。它按以下顺序解析运行时——`--gateway-bin`、`@bankofai/x402-gateway` 依赖、内置的 `dist/gateway/cli.js`、`PATH` 上的 `x402-gateway`，最后是代码检出里的 `../x402-gateway/dist/cli.js`。`gateway check`、`gateway catalog build`、`gateway catalog pay-assets` 与 `catalog build` 在进程内直接调用 gateway 库；`gateway scaffold` 只是写出一个模板文件，`gateway search` / `gateway catalog search` 则读取目录数据源。
+
+默认值：`gateway start` 绑定 `--host 127.0.0.1 --port 4020`，读取 `--providers providers`；`gateway check` 同样默认 `providers`；`gateway scaffold` 输出到 `--output-dir providers/<name>`，`--forward-url` 默认 `https://api.example.com`；直接执行 `x402-cli gateway catalog` 等同于 `build`。
 
 **校验 provider 文件：**
 
@@ -300,7 +304,9 @@ x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build> [o
 | :--- | :--- |
 | `--catalog <source>` | `catalog.json` 路径或 URL |
 | `--provider <fqn>` | 服务 FQN（用于 `export-gateway`） |
-| `--output-dir <dir>` | 生成文件的输出目录 |
+| `--output-dir <dir>` | 生成文件的输出目录（用于 `export-gateway`） |
+| `--output <file>` | 把构建出的目录 JSON 写入该文件（用于 `build`） |
+| `--dist-dir <dir>` | 把构建结果写入 `<dir>/catalog.json`（用于 `build`） |
 | `-n, --limit <count>` | 搜索结果数量上限（默认：`10`） |
 | `--include-blocked` | 在搜索结果中包含被屏蔽的服务 |
 | `--timeout-ms <ms>` | 网络超时（毫秒，默认：`30000`） |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/faq.md
index 6553e49..371d9f1 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/faq.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/faq.md
@@ -69,7 +69,7 @@ Base 结算 USDC 用的是 **EIP-3009**（`transferWithAuthorization`）而非 P
 
 ### 可以在不持有 TRX 的情况下付款吗？
 
-可以，在 TRON 上通过 GasFree 实现。使用 `scheme=exact_gasfree` 时，由一个 relayer 代付网络能量、并从支付代币里扣除手续费，所以付款钱包只需要稳定币、无需 TRX。当接口宣告了该 scheme 时 CLI 会自动选用，也可以用 `--scheme exact_gasfree` 显式要求。由于 relayer 手续费与支付金额分开，用 `--max-gasfree-fee <amount>` 给它封顶。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
+可以，在 TRON 上通过 GasFree 实现。使用 `scheme=exact_gasfree` 时，由一个 relayer 代付网络能量、并从支付代币里扣除手续费，所以付款钱包只需要稳定币、无需 TRX。CLI 取的是第一条匹配你过滤条件的支付要求，并不会优先选 GasFree，因此只要接口同时提供普通 `exact`，就请用 `--scheme exact_gasfree` 显式要求。由于 relayer 手续费与支付金额分开，用 `--max-gasfree-fee <amount>` 给它封顶。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
 
 ---
 
@@ -99,7 +99,13 @@ Base 结算 USDC 用的是 **EIP-3009**（`transferWithAuthorization`）而非 P
 | `DEADLINE_OR_CLOCK_SKEW` | 支付要求过期或本地时钟偏差 | 校准本地时钟，用全新支付要求重试 |
 | `RATE_LIMITED` | 上游服务或 RPC 在限流 | 稍候再重试 |
 | `NETWORK_ERROR` | 无法访问 URL/RPC | 检查 URL、本地服务、代理和网络连通性 |
-| `SDK_API_DRIFT` | 已安装的 SDK 包与 CLI 不匹配 | 重装 `@bankofai/x402-cli` 及其 SDK 依赖 |
+| `SDK_API_DRIFT` | 已安装的 SDK 包与 CLI 不匹配 | 重装 `@bankofai/x402-cli`（其 SDK 依赖为锁定版本，请勿单独升级） |
+| `INVALID_SETTLEMENT` | 网关返回的 `PAYMENT-RESPONSE` 不是成功结算 | 不要按已付款处理，请联系网关运营方 |
+| `WALLET_ADDRESS_MISMATCH` | 选中的钱包与签名数据里的付款方不一致 | 重新选择钱包，并用全新的支付要求重试 |
+| `INVALID_PAYMENT_REQUIREMENT` | `402` 支付要求未通过结构校验（scheme、网络、金额、地址、超时、资源 URL） | 接口配置有误，请联系服务方 |
+| `TOKEN_BALANCE_CHECK_FAILED` | 支付代币的余额检查失败 | 检查 RPC 端点与代币/网络组合 |
+| `HTTP_ERROR` | 付款后的重试请求返回非 2xx | 重试前先读 `error.details` 中的 `settled` / `paymentResponse` |
+| `IO_ERROR` | 无法归类的错误的兜底码（本地文件读写失败也归到这里） | 加 `--json` 重跑并查看原始 `message`，同时检查 provider/网关日志 |
 
 ### "402 response missing PAYMENT-REQUIRED header"
 
@@ -115,7 +121,7 @@ Base 结算 USDC 用的是 **EIP-3009**（`transferWithAuthorization`）而非 P
 
 ### `gateway start` 提示找不到运行时
 
-`gateway start` 与 `gateway catalog` 需要独立的 `@bankofai/x402-gateway` 包。请安装它（`npm install -g @bankofai/x402-gateway`）、从含有 `../x402-gateway/dist/cli.js` 的检出中运行，或用 `--gateway-bin <path>` 指向可执行文件。
+这通常说明安装不完整：CLI 正常情况下自带 gateway 运行时（`dist/gateway/cli.js`）并依赖 `@bankofai/x402-gateway`，请先重装 `@bankofai/x402-cli`，或用 `--gateway-bin <path>` 指向别的运行时。而且只有 `gateway start` 需要这个运行时：`gateway check`、`gateway catalog build`、`gateway catalog pay-assets` 与 `catalog build` 在进程内调用 gateway 库，`gateway scaffold` 只是写一个模板文件，search 类命令则读取目录数据源。
 
 ### 部署前如何校验我的 provider 文件？
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/index.md
index 1c60944..ab379e2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/index.md
@@ -8,7 +8,7 @@ description: >-
 
 ## 什么是 x402 CLI？
 
-x402 CLI（`@bankofai/x402-cli`）把 [x402 支付协议](../index.md)搬进了你的终端。它是一个依赖极简的命令，让人工操作者、Shell 脚本，或者一个 AI Agent 都能**支付一个受 x402 保护的 URL、启动本地付费端点、浏览服务目录**——不用写任何集成代码。
+x402 CLI（`@bankofai/x402-cli`）把 [x402 支付协议](../index.md)搬进了你的终端。它是一条命令，让人工操作者、Shell 脚本，或者一个 AI Agent 都能**支付一个受 x402 保护的 URL、启动本地付费端点、浏览服务目录**——不用写任何集成代码。
 
 可以这样理解：[x402 SDK](../sdk-features.md) 是你嵌进应用里、用来收费或付费的那层能力；而 CLI 是同一套能力，被包装成一条你现在就能敲的命令：
 
@@ -17,7 +17,7 @@ x402 CLI（`@bankofai/x402-cli`）把 [x402 支付协议](../index.md)搬进了
 x402-cli pay https://api.example.com/paid --network tron:0xcd8690dc --token USDT
 ```
 
-它完全构建在已发布的 TypeScript SDK 包之上——`@bankofai/x402-core`、`@bankofai/x402-evm`、`@bankofai/x402-fetch`、`@bankofai/x402-tron`。稳定币支付使用 `scheme=exact`：TRON 与 BSC 走 Permit2 授权，Base USDC 走 EIP-3009。TRON 上还支持 `scheme=exact_gasfree`——由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需持有 TRX。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
+它完全构建在已发布的 TypeScript SDK 包之上，且是锁定版本打包、并不跟随 SDK 最新版：CLI 1.0.2 内含 1.0.1 的 `@bankofai/x402-core`、`-evm`、`-fetch`、`-tron`，以及 `@bankofai/x402-gateway` 1.0.2 和 `@bankofai/agent-wallet` 2.4.0。稳定币支付使用 `scheme=exact`：TRON 与 BSC 走 Permit2 授权，Base USDC 走 EIP-3009。TRON 上还支持 `scheme=exact_gasfree`——由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需持有 TRX。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
 
 默认情况下，`pay` 使用你当前激活的 [Agent Wallet](../../Agent-Wallet/Intro.md) 签名——不需要把私钥放进环境变量。详见 [用 Agent Wallet 付款](./command-reference.md#paying-with-agent-wallet)。
 
@@ -41,7 +41,7 @@ CLI 把能力归为五条命令。
 
 ## 默认给人看，需要时给机器看
 
-输出默认是人类友好的文本。给任意命令加上 `--json`，就能得到一份稳定的、机器可读的结构化 JSON 输出——非常适合脚本和 AI Agent：
+输出默认是人类友好的文本。给任意会返回结果的命令加上 `--json`，就能得到一份稳定的、机器可读的结构化 JSON 输出——非常适合脚本和 AI Agent。（`gateway start` 直接透传网关自身的输出，不产生 JSON 封装；`catalog pay-json --raw` 打印裸载荷。）
 
 ```bash
 x402-cli pay 'https://x402-gateway.bankofai.io/providers/defillama-tvl-tron/protocols' \
@@ -89,7 +89,7 @@ CLI 内置了代币注册表。用 `--network` 指定网络，用 `--token` 指
 | :--- | :--- | :--- |
 | **TRON 主网** | `tron:0x2b6653dc` | USDT、USDD |
 | **TRON Nile 测试网** | `tron:0xcd8690dc` | USDT、USDD |
-| **TRON Shasta 测试网** | `tron:0x94a9059e` | USDT |
+| **TRON Shasta 测试网** | `tron:0x94a9059e` | USDT（仅能签名，见下方说明） |
 | **BSC 主网** | `eip155:56` | USDT |
 | **BSC 测试网** | `eip155:97` | USDT、USDC |
 | **Base 主网** | `eip155:8453` | USDC |
@@ -104,6 +104,10 @@ TRON 网络必须使用标准的 CAIP-2 标识符（`tron:0x…`）。旧的别
 | `base-mainnet` | `eip155:8453` |
 | `base-sepolia` | `eip155:84532` |
 
+:::caution 官方 facilitator 不结算 Shasta
+CLI 接受 `tron:0x94a9059e`，但官方 facilitator（`https://facilitator.bankofai.io`）只启用了 TRON 主网/Nile、BSC 主网/测试网、Base 主网/Sepolia。因此 Shasta 上的支付无法在那里校验与结算——TRON 测试请用 `tron:0xcd8690dc`（Nile），或自建注册了 Shasta 的 facilitator。
+:::
+
 已注册代币的精度以注册表为准，不可覆盖。只有未注册的非 Base 资产，才需要用 `--asset <address>` 搭配 `--decimals <count>` 传入。
 
 :::note 不同链的授权方式不同
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/quickstart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/quickstart.md
index 028dc03..d77c57f 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/quickstart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/cli/quickstart.md
@@ -97,7 +97,7 @@ x402-cli pay '<x402-url>' \
 `--max-amount` 给你愿意支付的金额封顶：如果接口价格超过它，CLI 会在签名前中止。同一条命令在 EVM 网络上同样适用——把 `--network` 指向 `eip155:97`（BSC 测试网）或 `base-sepolia`（Base Sepolia，USDC）即可。
 
 :::tip 没有 TRX？用 GasFree
-在 TRON 上，如果接口宣告了 `exact_gasfree`，CLI 可以在钱包里没有 TRX 的情况下付款——由一个 relayer 代付网络能量、并从支付代币里扣除手续费。CLI 会自动选用，你也可以用 `--scheme exact_gasfree` 显式要求，并用 `--max-gasfree-fee` 给 relayer 手续费封顶。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
+在 TRON 上，如果接口宣告了 `exact_gasfree`，CLI 可以在钱包里没有 TRX 的情况下付款——由一个 relayer 代付网络能量、并从支付代币里扣除手续费。CLI 取的是第一条匹配你过滤条件的支付要求、并不会优先选 GasFree，因此端点同时提供普通 `exact` 时，请用 `--scheme exact_gasfree` 显式要求，并用 `--max-gasfree-fee` 给 relayer 手续费封顶。详见 [GasFree 支付](./command-reference.md#gasfree-payments-tron)。
 :::
 
 ---
@@ -119,8 +119,7 @@ x402-cli serve \
 
 - `GET /health` —— 存活检查
 - `GET /.well-known/x402` —— 机器可读的支付元数据
-- `GET /pay` —— 返回 `402 Payment Required`
-- `POST /pay` —— 通过 Facilitator 校验并结算已提交的支付
+- `/pay` —— 请求未带 `PAYMENT-SIGNATURE` 时返回 `402 Payment Required`；带该头时通过 Facilitator 校验并结算（任意 HTTP 方法均可）
 
 在另一个终端里支付它：
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
index 1598aac..22d4245 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
@@ -62,7 +62,7 @@ Facilitator 由官方持续维护和升级，包括：
 
 | 模式 |限速 |说明 |
 |-----|-----|-----|
-| **匿名调用（Anonymous Mode）** | 10 次 / 分钟（默认值，可配置） | 不需要 API Key，适用于本地开发和功能测试 |
+| **匿名调用（Anonymous Mode）** | 官方部署为 1 次 / 分钟（可配置；未配置时代码默认 10 次 / 分钟） | 不需要 API Key，适用于本地开发和功能测试 |
 | **API Key 调用（API Key Mode）** | 1000 次 / 分钟 | 需要 API Key，适用于生产环境和高频支付请求 |
 
 两种模式的调用方式完全相同，但在 **身份识别与接口限速策略** 上有所不同。 
@@ -79,7 +79,7 @@ Facilitator 由官方持续维护和升级，包括：
 在匿名模式下：
 
 - `/settle` 接口会启用 **限速**
-- **每分钟最多 10 次调用（默认值，可配置）**
+- **官方部署为每分钟 1 次调用**（可配置；未配置时代码默认 10 次 / 分钟）
 
 该模式主要用于：
 
@@ -262,7 +262,17 @@ curl -X POST https://facilitator.bankofai.io/settle \
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | 按链上授权身份查询支付记录 |
 | GET | `/payments` | 已认证卖家的结算记录流（`?limit=&offset=`） |
 
-> **不存在** `/fee/quote` 端点——费用条款随支付要求的 `extra` 字段一起下发。限速仅作用于 `/settle` 接口，其他接口不受限速影响。
+> **不存在** `/fee/quote` 端点，各方案也不收取 facilitator 费用。限速仅作用于 `/settle` 接口，其他接口不受限速影响。
+
+### 官方服务结算的网络与方案
+
+| 网络 | 环境 |
+|---|---|
+| `tron:0x2b6653dc`（TRON 主网）· `tron:0xcd8690dc`（Nile） | 主网 · 测试网 |
+| `eip155:56`（BSC）· `eip155:97`（BSC 测试网） | 主网 · 测试网 |
+| `eip155:8453`（Base）· `eip155:84532`（Base Sepolia） | 主网 · 测试网 |
+
+以上网络均注册了 `exact`、`upto` 与 `batch-settlement`；TRON 在服务持有 GasFree 中继凭证的网络上（TRON 主网与 Nile）额外注册 `exact_gasfree`。以所连接部署的 `/supported` 返回为准。
 
 ### 支付记录查询
 
@@ -287,7 +297,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 
 **Q：不配置 API Key 能正常运行吗？**
 
-可以运行，但 `/settle` 接口默认每 IP 每分钟最多调用 10 次。这只适合测试，任何真实流量都必须配置 API Key。
+可以运行，但官方部署的 `/settle` 接口每 IP 每分钟仅允许 1 次调用（部署未配置时，facilitator 服务内置默认为 10 次 / 分钟）。这只适合测试，任何真实流量都必须配置 API Key。
 
 **Q：API Key 会过期吗？**
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
index 15aa898..6a20fee 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
@@ -19,7 +19,7 @@ Facilitator 是一种中间件服务，主要负责：
 
 - **支付验证**：确认客户端提交的签名载荷严格符合服务端声明的支付要求。
 - **支付结算**：将验证通过的交易提交至区块链网络，并监控上链状态。
-- **费率管理**：支持配置服务费（可选），即对促成的支付收取费用。
+- **结算记录**：每笔结算持久化一条记录，以链上授权身份为键，并支持按卖家过滤的记录查询。
 - **结果反馈**：将验证与结算结果返回给服务端，作为服务端决定是否交付资源的依据。
 
 > **注意**：Facilitator **不持有资金**，也不充当托管方——它仅根据客户端签名的指令执行验证与链上操作。
@@ -43,12 +43,12 @@ Facilitator 是一种中间件服务，主要负责：
 
 | | 官方 Facilitator | 自托管 Facilitator |
 |---|---|---|
-| **适合人群** | 大多数卖家，特别是刚开始使用 x402 的用户 | 需要完全掌控费用策略、能量管理的高级用户 |
+| **适合人群** | 大多数卖家，特别是刚开始使用 x402 的用户 | 需要完全掌控结算钱包、RPC 节点以及注册哪些网络/方案的高级用户 |
 | **是否需要维护服务器** | 不需要 | 需要 |
-| **是否需要钱包私钥** | 不需要 | 需要（用于支付手续费）|
+| **是否需要结算钱包** | 不需要 | 需要——通过 `@bankofai/agent-wallet` 解析的有余额钱包（用于支付网络手续费）|
 | **上手难度** | 低（申请 API Key 即可）| 中（需部署和配置服务）|
-| **费用控制** | 固定策略 | 完全自定义 |
-| **推荐场景** | 测试、快速上线、中小规模应用 | 大规模生产、需要自定义费率 |
+| **网络与方案控制** | 固定集合 | 完全自定义 |
+| **推荐场景** | 测试、快速上线、中小规模应用 | 大规模生产、私有化或合规要求场景 |
 
 ---
 
@@ -71,13 +71,13 @@ Facilitator 是一种中间件服务，主要负责：
 
 ## 方案二：自托管 Facilitator
 
-如果您希望完全掌控费用策略、能量管理，或有特定的隐私/合规要求，可以选择自己部署 Facilitator 服务。
+如果您希望完全掌控结算钱包、RPC 节点、能量管理，或注册哪些网络与方案，又或有特定的隐私/合规要求，可以选择自己部署 Facilitator 服务。
 
 > ⚠️ **自托管安全提示：**
-> - 自托管 Facilitator 需要使用一个**专用钱包**的私钥来支付区块链手续费
+> - 自托管 Facilitator 需要一个**有余额的专用钱包**来支付区块链手续费。该钱包通过 `@bankofai/agent-wallet` 解析、在进程外解锁（例如 `AGENT_WALLET_PASSWORD`）——原始私钥不会进入服务进程
 > - **这个 Facilitator 钱包应与您的收款钱包分开**，请专门创建一个新钱包
 > - Facilitator 钱包只需存入少量代币（用于手续费），不要存入大量资金
-> - 私钥通过环境变量设置，**绝对不要提交到 Git 或分享给任何人**
+> - 不要把原始私钥写进 `.env`、配置文件或命令行，**更不要提交到 Git 或分享给任何人**
 
 快速使用示例可参考 [卖家快速入门](../getting-started/quickstart-for-sellers.md) 中示例。
 
@@ -99,7 +99,7 @@ Facilitator 是一种中间件服务，主要负责：
 | GET | `/metrics` | Prometheus 指标（运维用途；仅当监控与主端口共用时才在主端口暴露） |
 | ALL | `/mainnet/*` · `/nile/*` | GasFree Open API 透明代理（HMAC 签名）——由 TRON `exact_gasfree` 方案内部使用 |
 
-> **不存在** `/fee/quote` 端点。费用条款随支付要求的 `extra` 字段一起下发；支付记录以链上授权身份（`network` + `scheme` + `asset` + `payer` + `nonce`）为键，而非客户端提供的 payment ID。
+> **不存在** `/fee/quote` 端点，各方案也完全不收取 facilitator 费用。支付记录以链上授权身份（`network` + `scheme` + `asset` + `payer` + `nonce`）为键，而非客户端提供的 payment ID。
 
 ---
 
@@ -110,7 +110,7 @@ Facilitator 是一种中间件服务，主要负责：
 | 模式 | 限速 | 认证方式 |
 |------|------|----------|
 | **已认证** | 1000 次 / 分钟 | 请求头携带 `X-API-KEY: <your_key>` |
-| **匿名** | 10 次 / 分钟（默认值，可配置） | 不携带 API Key |
+| **匿名** | 官方部署为 1 次 / 分钟（可配置；未配置时代码默认 10 次 / 分钟） | 不携带 API Key |
 
 其他端点（`/verify`、`/supported`、`/payments/*`）不单独限速。
 
@@ -126,14 +126,14 @@ Facilitator 是一种中间件服务，主要负责：
 
 ---
 
-## 费用结构
+## 费用
 
-Facilitator 支持灵活配置服务费用：
+当前各方案**不收取 facilitator 费用**：没有 `base_fee` 配置，支付要求中没有费用对象，也没有 `/fee/quote` 端点——它们已在 SDK 1.0.1 中移除。一次结算向卖家转移的是签名中的金额——不会少于公布金额；使用官方 SDK/CLI 付款时即为公布金额本身。
 
-- **固定费用 (Base Fee)**：每笔交易按网络和资产收取固定的服务费（例如 `1 USDT`）。
-- **免费模式 (No Fee)**：支持零费率运营模式（例如 EVM `exact` 不收取 Facilitator 费用）。
+实际存在的成本只有：
 
-费用条款包含在服务端下发给客户端的支付要求（Payment Requirements）的 `extra` 字段中；不存在单独的 `/fee/quote` 端点。
+- **网络手续费**（TRON 的能量/带宽 TRX、BNB 或 ETH gas）由 Facilitator 的结算钱包承担。
+- **GasFree 中继费**：即中继方代付网络能量所收的服务费（每笔转账费，新 GasFree 账户首笔另加一次性激活费），TRON `exact_gasfree` 下由中继方自行定价，在付款金额之外从支付代币中扣除——客户端应显式设置上限。
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
index 2153db6..66d2cd8 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
@@ -61,12 +61,7 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
       "payTo": "<SELLER_TRON_ADDRESS>",
       "maxTimeoutSeconds": 3600,
       "extra": {
-        "assetTransferMethod": "permit2",
-        "fee": {
-          "feeTo": "<FACILITATOR_FEE_RECEIVER_ADDRESS>",
-          "feeAmount": "100",
-          "caller": "<FACILITATOR_CALLER_ADDRESS>"
-        }
+        "assetTransferMethod": "permit2"
       }
     }
   ]
@@ -128,12 +123,12 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
 | `resource`          | 关于请求资源的信息                                |
 | `accepts`           | 接受的支付选项数组                                |
 | `scheme`            | 支付方案（`exact`、`upto`、`batch-settlement`、`exact_gasfree`）  |
-| `network`           | 网络标识符（`tron:0xcd8690dc`, `tron:0x2b6653dc`, `eip155:56`, `eip155:97`） |
+| `network`           | 网络标识符（`tron:0xcd8690dc`, `tron:0x2b6653dc`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532`） |
 | `amount`            | 支付金额，以最小单位计（例如：100 = 0.0001 USDT） |
 | `asset`             | TRC-20/BEP-20 代币合约地址                               |
 | `payTo`             | 卖家的钱包地址                              |
 | `maxTimeoutSeconds` | 支付有效期的最大时长                              |
-| `extra.fee`         | Facilitator 费用信息（包含 `feeTo`、`feeAmount`、`caller`） |
+| `extra`             | 方案相关数据——`assetTransferMethod`（`eip3009` / `permit2`）、EIP-3009 资产的 `name`/`version`，以及声明了非默认付款流程时的 `paymentFlow`（`upfront` 或 `escrow`）——内置方案全部使用默认的 `authorization` 流程，该字段不会写入 `extra`。其中不含费用对象：各方案不收取 facilitator 费用。 |
 | `extensions`        | 支付方案的附加上下文（如 gas 赞助、payment-identifier） |
 
 ## 支付签名结构
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 d17ced2..370df5b 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
@@ -28,7 +28,7 @@ x402 采用 CAIP-2 网络标识符格式：`tron:<hex_chain_id>`。
 | **BSC Mainnet**        | `eip155:56` | BSC 主网 (生产环境) |
 | **BSC Testnet**         | `eip155:97`  | BSC 测试网   |
 
-> **注意**：在自托管 Facilitator 的 YAML 配置文件中，使用更易读的格式：`bsc:mainnet` 和 `bsc:testnet`。Facilitator 启动时会自动将其映射为协议层对应的 EIP-155 链 ID。
+> **注意**：自托管 Facilitator 的 YAML 配置**只接受规范的 CAIP-2 标识符**——`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`、`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`。`bsc:mainnet`、`tron:nile` 这类易读别名不会被解析，启动时会直接报错。
 
 
 ## Base 网络标识符
@@ -53,48 +53,50 @@ x402 专为区块链生态设计，实现了原生的链上支付验证与结算
 | :--------------- | :------------ | :------------------------------------- |
 | **TRON Mainnet** | **Mainnet**   | **生产网络**：用于处理真实价值资产。   |
 | **TRON Nile**    | **Testnet**   | **推荐测试网**：TRON 首选的开发与调试环境。 |
-| **TRON Shasta**  | **Testnet**   | **备用测试网**：长期稳定的测试环境。   |
+| **TRON Shasta**  | **Testnet**   | 备用测试网——仅 SDK/CLI 可用；官方 facilitator 不结算 Shasta，请用 Nile 或自建。   |
 | **BSC Mainnet**        | **Mainnet**   | **生产网络**：用于处理真实价值资产。   |
 | **BSC Testnet**         | **Testnet**   | **推荐测试网**：BSC 首选的开发与调试环境。 |
 | **Base Mainnet**       | **Mainnet**   | **生产网络**：使用官方 USDC。 |
 | **Base Sepolia**       | **Testnet**   | CLI/SDK 测试；不在 API Catalog 发布。 |
 
-### 支持的代币
+## 支持的代币 {#supported-tokens}
 
 x402 支持 **TRC-20、BEP-20 和 ERC-20** 代币。TRON/BSC 路由使用各自配置的稳定币；Base 使用官方 USDC。
 
-#### 支持的代币列表
+### 支持的代币列表
 
 | 代币符号 | 网络环境       | 合约地址 (Contract Address)          |
 | :------- | :------------- | :----------------------------------- |
 | **USDT** | `tron:0x2b6653dc` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
 | **USDT** | `tron:0xcd8690dc`    | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` |
+| **USDT** | `tron:0x94a9059e` | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` |
 | **USDD** | `tron:0x2b6653dc` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` |
 | **USDD** | `tron:0xcd8690dc`    | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` |
 | **USDT** | `eip155:56` | `0x55d398326f99059fF775485246999027B3197955` |
 | **USDC** | `eip155:56` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
-| **EPS** | `eip155:56` | `0xA7f552078dcC247C2684336020c03648500C6d9F` |
 | **USDT** | `eip155:97`    | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
 | **USDC** | `eip155:97`    | `0x64544969ed7EBf5f083679233325356EbE738930` |
 | **DHLU** | `eip155:97`    | `0x375cADdd2cB68cE82e3D9B075D551067a7b4B816` |
 | **USDC** | `eip155:8453`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 | **USDC** | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
+> **默认资产与需显式放行的资产（SDK 1.1.0 起）**：默认资产注册表在 TRON（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）与 BSC 主网（`eip155:56`）上解析 **USDT**，在 BSC 测试网（`eip155:97`）与 Base（`eip155:8453`、`eip155:84532`）上解析 **USDC**。上表中的其余代币——TRON USDD、BSC 主网 USDC、BSC 测试网 USDT、DHLU 以及任何自定义代币——都属于「仅由服务端公布」：1.1.0 的客户端消费管控默认开启，除非你通过 `spendControls.allowedAssets` 放行，否则客户端会拒绝支付；`x402-cli` 默认只支付其注册表内的代币——未注册资产需显式传 `--asset` 与 `--decimals`，且在 Base 上一律拒绝。
+
 > **扩展支持**：协议具有高度的可扩展性。通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）或 server 的 `EVM_TOKENS` 配置表，您可以轻松配置并支持任意自定义的 TRC-20/BEP-20 代币。
 
-> **关于 `exact` 方案的代币选择**：EIP-3009 代币（如 Base 官方 USDC、BSC 测试网 DHLU）通过 `transferWithAuthorization` 无 gas 结算。普通 ERC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算——客户端首次付款时自动广播一次性 `approve(Permit2)`。每种代币的结算方式由 server `accepts[].price.extra` 中的数据决定：EIP-3009 → `{ name, version }`；普通 ERC-20 → `{ assetTransferMethod: "permit2" }`。
+> **关于 `exact` 方案的代币选择**：EIP-3009 代币（如 Base 官方 USDC、BSC 测试网 DHLU）通过 `transferWithAuthorization` 无 gas 结算。普通 ERC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算——客户端首次付款时自动广播一次性 `approve(Permit2)`。每种代币的结算方式由你在 server 端 `accepts[].price.extra` 里配置，SDK 会在协议数据中以 `accepts[].extra` 下发：EIP-3009 → `{ name, version }`；普通 ERC-20 → `{ assetTransferMethod: "permit2" }`。
 
-#### 安全签名
+## 安全签名
 
 x402 采用类型化数据签名来处理所有支付相关的签名授权。
 
-该机制带来了以下核心优势：
+### 核心优势
 
 - **链下授权 (Off-chain Authorization)**：买家在本地（链下）对转账意图进行签名，无需预先锁定资金。
 - **最小化信任 (Trust-minimized)**：签名包含严格的限制条件，Facilitator 无法在客户端明确授权的范围（金额、接收方、有效期）之外转移任何资金。
 - **链上可验证 (On-chain Verifiability)**：所有的签名最终都可在智能合约层面进行加密学验证，确保交易的不可篡改性。
 
-### 代币配置参数
+## 代币配置参数
 
 在服务端配置 `HTTP 402` 支付要求时，您需要明确指定以下三个核心参数：
 
@@ -106,11 +108,11 @@ x402 采用类型化数据签名来处理所有支付相关的签名授权。
 > TRON 上 USDT 的精度 (Decimals) 为 **6**。
 > 若需收取 **1.0 USDT**，配置的数值应为 `1000000`。
 
-### 支付方案
+## 支付方案
 
 x402 支持四种支付方案。每种方案按链族实现为 client + server + facilitator 三件套。
 
-#### `exact` 方案
+### `exact` 方案 {#exact-scheme}
 
 `exact` 方案支付公布的准确金额，覆盖两种代币转账路径：
 
@@ -119,37 +121,37 @@ x402 支持四种支付方案。每种方案按链族实现为 client + server +
 
 `exact` 方案遵循 **x402 Foundation** 发布的 **v2 链路格式**：标准 v2 客户端可直接向本 SDK 的服务端发起付款请求，本 SDK 客户端也可直接访问任何 v2 兼容的服务端——无需项目特定的转换。转账授权数据位于 `payload.authorization` 中。
 
-#### `upto` 方案
+### `upto` 方案
 
 按量计费。客户端签署最高至最大金额的 Permit2 授权；服务端按每次请求决定**实际用量**并仅结算该部分（≤ max）。一次签名形状，每次请求不同收费——非常适合**按量计费**（LLM Token 消耗、计算时长、带宽）。EVM 和 TRON 均支持（均走 Permit2）。
 
-#### `batch-settlement` 方案
+### `batch-settlement` 方案
 
 面向高频微支付（如 AI 代理每 token 计费）的支付通道方案。客户端链上**一次性存入**，然后用链下**凭证**支付多次请求；facilitator **批量 claim** 并在一笔交易中结算到 `payTo`——因此 N 次请求约仅花费一次存入的 gas。含**退款**路径，可退回通道中未使用的余额。EVM 和 TRON 均支持。
 
-#### `exact_gasfree` 方案
+### `exact_gasfree` 方案
 
-TRON 专属。允许用户使用 USDT/USDD 付款而**无需持有 TRX 来支付 gas 费用**。客户端签署 TIP-712 GasFree 许可，由 relayer 通过官方 GasFree 代理支付链上 energy——付款方无需 TRX，也无需一次性 `approve`。资金来自付款方的 GasFree 托管钱包（非主钱包）。支持 `tron:0x2b6653dc` 和 `tron:0xcd8690dc`。
+TRON 专属。允许用户使用 USDT/USDD 付款而**无需持有 TRX 来支付 gas 费用**。客户端签署 TIP-712 GasFree 许可，由 relayer 通过官方 GasFree 代理支付链上 energy——付款方无需 TRX，也无需一次性 `approve`。资金来自付款方的 GasFree 托管钱包（非主钱包）。SDK 在 `tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e` 上注册了 GasFree，但官方 facilitator 只为 TRON 主网与 Nile 代理中继——内置的 Shasta 中继地址背后没有对应上游，因此 Shasta 上的 GasFree 需要自备中继。
 
-##### GasFree 账户管理（通过 x402-payment skill）
+中继方会在付款金额**之外**，从支付代币中收取自己的中继费，因此 GasFree 账户余额需同时覆盖两者。
 
-使用 `x402-payment` skill 时，可直接通过 CLI 管理 GasFree 账户：
+:::info 什么是中继费
+**中继费（relayer fee）是 GasFree 中继服务收取的服务费**：你不烧自己的 TRX，改由中继方代付链上能量/带宽，作为交换，它从你的 GasFree 账户里按支付代币（如 USDT）扣一笔费用。它的构成是：每笔固定的**转账费（transferFee）**；若 GasFree 账户尚未激活，首笔再加一次性的**激活费（activateFee）**。费率由中继服务的接口按代币报价，客户端付款前会先查询估算（若中继接口未报出该代币的费率，客户端会改签一个 1 枚整代币的默认上限）；签名的许可里带有 `maxFee` 上限，中继方实际扣费不能超过该值。它与付款金额（给卖家的钱）**分开计**——`--max-amount` 不覆盖它，需用 `--max-gasfree-fee` 单独限额。
+:::
 
-**查询 GasFree 钱包信息**（地址、激活状态、余额、nonce）：
-```bash
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --network nile
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --wallet <YOUR_WALLET_ADDRESS>
-```
+#### 用 CLI 走 GasFree 付款
 
-**激活 GasFree 账户**（首次使用前需要激活）：
 ```bash
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network mainnet
-npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --token USDT
+x402-cli pay <url> \
+  --scheme exact_gasfree \
+  --max-amount 0.01 \
+  --max-gasfree-fee 0.5 \
+  --json
 ```
 
-#### 工作原理
+CLI 取的是服务端 `accepts` 列表中第一条匹配你过滤条件的支付要求，并不会优先选 GasFree；只要端点同时也宣告了普通 `exact`，就请传 `--scheme exact_gasfree`。`--max-amount` 不包含中继费——请用 `--max-gasfree-fee`（或 `--max-gasfree-fee-raw`）单独限额。详见 [CLI 命令参考](../cli/command-reference.md#gasfree-payments-tron)。
+
+### 工作原理
 
 1.  **预授权 (Authorize)**：客户端签署类型化数据消息，授权付款（精确金额，或 `upto`/`batch-settlement` 的最大金额）。
 2.  **执行服务 (Execute)**：服务端执行请求任务，并（对于按量计费方案）计算**实际成本**。
@@ -163,17 +165,17 @@ npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile --toke
   }}
 />
 
-### 部署私有 Facilitator
+## 部署私有 Facilitator
 
 您可以选择部署私有的 Facilitator，以完全掌控区块链网络上的支付验证与结算流程。自托管示例（`examples/typescript/facilitator/basic`）是一个暴露 `/verify`、`/settle`、`/supported` 的 Express 服务——无需数据库。
 
-Facilitator 作为协议的中间件，承担以下核心职责：
+### 核心职责
 
 1.  **验证载荷 (Verify)**：校验类型化数据签名的加密有效性及参数完整性。
 2.  **提交交易 (Submit)**：构建并向区块链广播链上结算交易。
 3.  **监控确认 (Monitor)**：追踪交易在链上的确认状态，确保资金最终到账。
 
-**部署先决条件**
+### 部署先决条件
 
 - **节点访问权限**：稳定的 RPC 访问（例如 TronGrid，或 BSC/Base 的 EVM JSON-RPC 端点）。
 - **Gas 资源储备**：一个持有充足 **TRX/BNB/ETH** 的钱包，用于支付结算 gas 费用。
@@ -181,7 +183,7 @@ Facilitator 作为协议的中间件，承担以下核心职责：
 
 > **深入了解**：请查阅 [Facilitator](./facilitator.md) 文档以获取详细的配置指南与 API 参考，以及[卖家快速入门](../getting-started/quickstart-for-sellers.md)。
 
-### 快速参考
+## 快速参考
 
 | 核心组件     | TRON/BSC/Base 实现详情                              |
 | :----------- | :----------------------------------------- |
@@ -190,7 +192,7 @@ Facilitator 作为协议的中间件，承担以下核心职责：
 | **签名机制** | TIP-712 / EIP-712 类型化数据签名                     |
 | **支付方案** | `exact`、`upto`、`batch-settlement`、`exact_gasfree`（TRON） |
 
-### 添加自定义代币
+## 添加自定义代币
 
 在**客户端 / facilitator** 侧，通过 TRON 代币注册表（`@bankofai/x402-tron`）注册自定义 TRC-20 代币：
 
@@ -209,11 +211,11 @@ registerToken(TRON_NILE, {
 
 注册完成后，即可在 TRON 价格中使用自定义代币符号（例如 `"0.001 MYT"`）。
 
-### 总结
+## 总结
 
 x402 专为区块链架构深度定制，提供了原生的 TRC-20/BEP-20/ERC-20 代币集成与安全签名支持。
 
-**核心要点：**
+### 核心要点
 
 - **开发环境**：推荐优先使用 **测试网** 进行开发与调试。
 - **默认结算资产**：TRON/BSC 路由使用各自配置的稳定币；Base 使用官方 **USDC**。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
index 71aa671..61c12e2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
@@ -13,7 +13,7 @@
 - **资产托管**：安全存储 USDT 或其他 TRC-20/BEP-20 代币。
 - **签名授权**：使用私钥对支付载荷进行加密签名 (Sign)。
 - **程序化支付**：以代码形式授权链上资金转移（特别适用于自主 AI 代理）。
-- **额度管理**：管理对 Facilitator 合约的代币授权 (Allowance)。
+- **额度管理**：管理向 Permit2 合约授予的一次性 `approve(Permit2, max)` 额度——facilitator 随后通过 x402 的 Permit2 代理合约划转资金。
 
 > **无状态认证**：钱包机制使得买家无需注册账户、无需管理 API Key 或登录 Session 即可直接发起交易。
 
@@ -41,13 +41,13 @@ BSC 网络使用 Hexadecimal (十六进制) 编码格式的地址，且固定以
 
 x402 协议采用类型化数据签名来执行安全的支付授权。
 
-引入该标准带来了以下核心优势：
+### 核心优势
 
 - **所见即所签 (Human-readable)**：用户在签名时能够清晰地查看具体的授权详情，而非一串不可读的密文。
 - **域隔离 (Domain separation)**：签名被严格绑定至特定的合约与域，防止跨应用或跨网络混用。
 - **防重放机制 (Replay protection)**：签名数据中内嵌了随机数 (nonce) 和过期时间，有效防止恶意重复提交。
 
-**签名交互流程：**
+### 签名流程
 
 1. 客户端接收服务端返回的支付要求。
 2. 客户端构建符合规范的类型化数据结构 (TypedData)。
@@ -62,6 +62,8 @@ x402 客户端 SDK 会自动处理此操作。
 
 ## 网络节点端点
 
+### TRON RPC 端点
+
 各 TRON 网络环境的全节点 / API 访问端点如下：
 
 | 网络环境 (Network)  | RPC 端点 (Endpoint)              |
@@ -71,6 +73,8 @@ x402 客户端 SDK 会自动处理此操作。
 | **Shasta** (测试网) | `https://api.shasta.trongrid.io` |
 
 
+### BSC RPC 端点
+
 各 BSC 网络环境的全节点 / API 访问端点如下：
 
 | 网络环境 (Network)  | RPC 端点 (Endpoint)              |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
index 911affc..d444a1b 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
@@ -37,7 +37,7 @@ x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发
 
 #### 谁来运行 Facilitator ？
 
-通常情况下，您需要运行自己的 Facilitator 服务。x402 专为自托管而设计，代码仓库中内置的 Facilitator 程序已准备就绪，可直接运行。
+通常情况下，您需要运行自己的 Facilitator 服务。x402 专为自托管而设计：仓库在 `examples/typescript/facilitator/basic` 提供了可直接运行的参考实现，投产前请按自身需求加固。
 
 [官方托管的 Facilitator](https://github.com/BofAI/x402-facilitator) 服务也已上线，您无需自行部署基础设施即可使用 x402。
 
@@ -65,7 +65,7 @@ x402 支持四种支付方案：
 - **`exact`**：支付公布的准确金额。EIP-3009 代币（如 Base 官方 USDC、BSC 测试网 DHLU）通过 `transferWithAuthorization` 无 gas 结算；普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算，首次付款需一次性 `approve(Permit2)`。`exact` 的协议 payload 遵循 **x402 Foundation** 的 v2 规范。
 - **`upto`**：按量计费——客户端签署最高至最大金额的 Permit2 授权，服务端仅结算**实际用量**（≤ max）。非常适合**按量计费**、**LLM Token 消耗**等场景。
 - **`batch-settlement`**：面向高频微支付的支付通道——一次性链上存入，然后用链下凭证支付多次请求，一笔交易批量结算。含退款路径。
-- **`exact_gasfree`**（仅限 TRON）：允许买家使用 USDT/USDD 付款而无需持有 TRX 来支付 gas。由 relayer 通过 GasFree API 支付链上 energy——客户端无需配置 API 密钥。
+- **`exact_gasfree`**（仅限 TRON）：允许买家使用 USDT/USDD 付款而无需持有 TRX 来支付 gas。由 relayer 通过 GasFree API 支付链上 energy——客户端无需配置 API 密钥。relayer 会在付款金额之外，从支付代币中扣除自己的中继费。
 
 #### 本 SDK 是否可以与 x402 Foundation（原 Coinbase）的 v2 参考实现互通？
 
@@ -73,10 +73,10 @@ x402 支持四种支付方案：
 
 - 标准的 v2 客户端可以直接访问本 SDK 的 `exact` 受保护端点，无需任何项目特定的适配层。
 - 本 SDK 的客户端可以直接向 v2 兼容的服务端付款。
-- V2 结构中转账授权数据位于 `payload.authorization` 字段（结构化对象）；作为迁移过渡，客户端还会同时填充 `extensions.transferAuthorization`，以便仍在运行旧版本的服务端也能解析。
+- V2 结构中转账授权数据位于 `payload.authorization` 字段（结构化对象）。
 - BSC USDT/USDC 是普通 ERC-20（无 ERC-3009），在 `exact` 方案下通过 Permit2 路径结算——客户端首次付款时自动广播一次性 `approve(Permit2)`。ERC-3009 代币（如 BSC 测试网 DHLU）则无 gas 结算，无需 approve。
 - Base 主网官方 USDC 在 `exact` 下使用 EIP-3009：付款方签署 `transferWithAuthorization`，无需 Permit2 approve。
-- 仓库中的 `examples/bsc-testnet-smoke/` 目录提供了双向互通的烟雾测试示例（Coinbase 官方客户端 → BANK OF AI 服务端、BANK OF AI 客户端 → Coinbase 官方服务端），可作为调试与集成参考。
+- 仓库中的 `legacy/examples/bsc-testnet-smoke/` 目录（属于保留作参考的 `legacy/` 目录）提供了双向互通的烟雾测试示例（Coinbase 官方客户端 → BANK OF AI 服务端、BANK OF AI 客户端 → Coinbase 官方服务端），可作为调试与集成参考。
 
 ### 资产、网络及费用
 
@@ -91,13 +91,14 @@ x402 支持四种支付方案：
 | TRON Nile (`tron:0xcd8690dc`)       | USDD (TRC-20) | **Testnet** |
 | BSC 主网 (`eip155:56`) | USDT (BEP-20) | **Mainnet** |
 | BSC 主网 (`eip155:56`) | USDC (BEP-20) | **Mainnet** |
-| BSC 主网 (`eip155:56`) | EPS (BEP-20) | **Mainnet** |
 | BSC testnet (`eip155:97`)      | USDT (BEP-20) | **Testnet** |
 | BSC testnet (`eip155:97`)      | USDC (BEP-20) | **Testnet** |
 | BSC testnet (`eip155:97`)      | DHLU (BEP-20, 用于 `exact` 互通测试) | **Testnet** |
 | Base 主网 (`eip155:8453`) | 官方 USDC（ERC-20，EIP-3009） | **Mainnet** |
 | Base Sepolia (`eip155:84532`) | USDC（ERC-20，EIP-3009） | **Testnet** |
 
+其中只有一部分是**默认资产**（TRON 与 BSC 主网的 USDT、BSC 测试网与 Base 的 USDC）。SDK 1.1.0 起，客户端消费管控会拒绝其他资产——包括 TRON USDD、BSC 主网 USDC、BSC 测试网 USDT——除非通过 `spendControls.allowedAssets` 放行。
+
 此外，可通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）添加自定义 TRC-20 代币；自定义 BEP-20 代币则通过在 server 的 `EVM_TOKENS` 配置表中添加条目来公布。
 
 #### 涉及哪些费用？
@@ -106,7 +107,7 @@ x402 支持四种支付方案：
   - 在 TRON 链上用于支付能量 (Energy) 和带宽 (Bandwidth) 消耗的 TRX（由 Facilitator 承担）。
   - 在 BSC 链上用于支付 gas 消耗的 BNB（由 Facilitator 承担）。
   - 在 Base 链上用于支付 gas 的 ETH（由 Facilitator 承担）。
-- **Facilitator 服务费**：每个 Facilitator 可独立配置的服务费用（支持设置为零）。
+- **Facilitator 服务费**：无。当前各方案不带任何费用字段——`base_fee` 配置与 `/fee/quote` 端点已在 SDK 1.0.1 移除。TRON `exact_gasfree` 由 GasFree relayer 从支付代币中收取自己的中继费，请在客户端设置中继费上限。
 
 ### 安全性
 
@@ -116,7 +117,7 @@ x402 支持四种支付方案：
 
 1.  **买家（客户端/代理）**：在本地运行时环境（如浏览器、Serverless 函数、代理虚拟机）中完成签名。
 2.  **卖家**：无需接触买家私钥；仅负责验证签名的有效性。
-3.  **Facilitator**：仅使用其自有密钥将交易提交上链。
+3.  **Facilitator**：使用自己的结算钱包提交交易，钱包通过 `@bankofai/agent-wallet` 解析——原始私钥不会进入 facilitator 进程。
 
 #### 退款机制如何运作？
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md
index dd183d1..a3fa0e2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md
@@ -113,19 +113,19 @@ export EVM_RPC_URL="https://bsc-testnet-rpc.publicnode.com"
 运行以下命令一次性安装所有 BANK OF AI Skills（包括 x402-payment）：
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y
+npx skills add https://github.com/BofAI/skills -y -g
 ```
 
-`-y` 参数会跳过所有交互选择，默认安装所有 Skills。安装器会自动检测你电脑上的 AI 工具（Cursor、Claude Code、Cline、OpenCode 等），并将技能复制到对应的目录中。
+`-y` 参数会跳过所有交互选择，默认安装所有 Skills；`-g` 参数把技能装到全局（用户级目录 `~/.agents/skills/`），而不是只装进当前目录。安装器会自动检测你电脑上的 AI 工具（Cursor、Claude Code、Cline、OpenCode 等），并将技能复制到对应的目录中。
 
 > ✅ **成功标志：** 终端显示 `✓ x402-payment (copied)` 以及其他已安装的技能
 
 ### 交互式安装
 
-如果你想手动选择安装哪些 Skills 或选择安装范围：
+如果你想手动选择安装哪些 Skills、装到哪些 AI 工具：
 
 ```bash
-npx skills add https://github.com/BofAI/skills
+npx skills add https://github.com/BofAI/skills -g
 ```
 
 交互式安装的完整步骤说明，请参考 [Skills 快速开始](../../McpServer-Skills/SKILLS/QuickStart.md)。
@@ -194,7 +194,7 @@ pnpm dev:server               # http://localhost:4021
 </TabItem>
 </Tabs>
 
-> ✅ **成功标志：** 代理返回了 `{"data": "..."}` 格式的内容，且区块链浏览器上出现了对应的交易记录
+> ✅ **成功标志：** 代理返回了端点的 JSON 内容——仓库自带的 Express 示例返回 `{"report":{"weather":"sunny","temperature":70}}`——且区块链浏览器上出现了对应的交易记录
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
index 4df5a3e..6ab2b66 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
@@ -125,7 +125,7 @@ git --version     # 版本控制工具
 
 **测试网 vs. 主网：**
 
-- **测试网**：使用免费测试代币，不涉及真实资金，适合开发调试。网络标识：`tron:0xcd8690dc` / `eip155:97`
+- **测试网**：使用免费测试代币，不涉及真实资金，适合开发调试。网络标识：`tron:0xcd8690dc` / `eip155:97` / `eip155:84532`（Base Sepolia，USDC——上 Base 主网前先在这里测）
 - **主网**：涉及真实支付，上线时使用。网络标识：`tron:0x2b6653dc` / `eip155:56` / Base `eip155:8453`
 
 ---
@@ -208,7 +208,7 @@ express()
       credit: 1000000,
     })
   )
-  .listen(4021);
+  .listen(4021, () => console.log("Resource server on http://localhost:4021"));
 ```
 
 </TabItem>
@@ -255,7 +255,7 @@ express()
       credit: 1000000,
     })
   )
-  .listen(4021);
+  .listen(4021, () => console.log("Resource server on http://localhost:4021"));
 ```
 
 </TabItem>
@@ -290,7 +290,7 @@ Facilitator 是一个**自动结算服务**：当有人为您的 API 付款时
 | **是否需要维护** | 否——官方托管 | 是——您自行运行 |
 | **是否需要钱包私钥** | 否 | 是（用于链上结算） |
 | **难度** | 低（仅需申请 API Key） | 中（运行示例 facilitator） |
-| **适合** | 快速部署、大多数用户 | 需要完全控制费率策略 |
+| **适合** | 快速部署、大多数用户 | 需要完全掌控结算钱包、RPC 节点与注册的网络/方案 |
 
 <Tabs>
 <TabItem value="official" label="✅ 官方 Facilitator（推荐）">
@@ -336,7 +336,9 @@ FACILITATOR_API_KEY=paste_your_api_key_here
 </TabItem>
 <TabItem value="selfhost" label="自托管 Facilitator">
 
-自托管方式让您完全控制费率策略。它运行示例 facilitator（`examples/typescript/facilitator/basic`），通过 HTTP 暴露 `/verify`、`/settle`、`/supported`，并按付款的 `network` 字段分发。
+自托管方式让您完全掌控结算钱包、RPC 节点以及注册哪些网络与方案——SDK 与 facilitator 本身都不收取任何费用。它运行示例 facilitator（`examples/typescript/facilitator/basic`），通过 HTTP 暴露 `/verify`、`/settle`、`/supported`，并按付款的 `network` 字段分发。
+
+> **Base 卖家注意：** 仓库自带的示例 facilitator 只注册了 `eip155:97` 与 `eip155:56`（见 `facilitator/basic/src/chains/evm.ts` 的 `EVM_NETWORKS`）。要在 Base 上结算，请使用已启用 `eip155:8453` 与 `eip155:84532` 的官方 facilitator，或自行把这两个网络加进 `EVM_NETWORKS`。
 
 > ⚠️ **安全提醒——请先阅读：**
 > - 自托管 Facilitator 使用您的钱包提交链上结算交易——**此钱包应与您的收款钱包分开**
@@ -476,7 +478,7 @@ EVM_RPC_URL=https://bsc-rpc.publicnode.com
 
 ### 3.（自托管）将 Facilitator 切换到主网
 
-facilitator 的 `TRON_NETWORKS` 已包含 `TRON_MAINNET`（`tron:0x2b6653dc`），`EVM_NETWORKS` 已包含 `eip155:56`。向 Facilitator 钱包充入足够的真实 TRX/BNB 以支付结算 gas，然后重启：
+示例 facilitator 的 `TRON_NETWORKS` 已包含 `TRON_MAINNET`（`tron:0x2b6653dc`），`EVM_NETWORKS` 已包含 `eip155:97` 与 `eip155:56`——但不含 Base（`eip155:8453` / `eip155:84532`），若在 Base 结算需自行添加。向 Facilitator 钱包充入足够的真实 TRX/BNB 以支付结算 gas，然后重启：
 
 ```bash
 pnpm dev:facilitator
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 fa209cf..26a9d85 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
@@ -73,11 +73,12 @@ x402 支持广泛的应用场景，包括：
 x402 目前支持以下网络环境：
 
 - **TRON 主网** (`tron:0x2b6653dc`)
-- **TRON Shasta 测试网** (`tron:0x94a9059e`)
+- **TRON Shasta 测试网** (`tron:0x94a9059e`)——仅 SDK/CLI 可用，官方 facilitator 不结算
 - **TRON Nile 测试网** (`tron:0xcd8690dc`)
 - **BSC 主网** （`eip155:56`）
 - **BSC 测试网** （`eip155:97`)
 - **Base 主网**（`eip155:8453`）
+- **Base Sepolia 测试网**（`eip155:84532`）
 
 Base 主网使用官方 USDC，通过 `exact` 方案和 EIP-3009 授权完成支付。
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
index bb55776..3f9b8db 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
@@ -8,6 +8,8 @@ description: 'x402 TypeScript SDK 的功能支持矩阵，以颗粒化 @bankofai
 本页跟踪 x402 SDK 的功能支持情况。
 
 > **SDK（仅 TypeScript）**：x402 是一个**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` npm 包发布。源码由 pnpm/turbo monorepo 维护，但应用应依赖已发布的包。此前的 Python + TypeScript SDK 已移至 `legacy/` 仅供参考。
+>
+> **当前版本：1.1.0**（2026-08-25）。11 个 `@bankofai/x402-*` 包同步发布，内部依赖锁定 `~1.1.0`，请整体升级。SDK 要求 **Node.js 22+**。
 
 ---
 
@@ -58,7 +60,7 @@ description: 'x402 TypeScript SDK 的功能支持矩阵，以颗粒化 @bankofai
 | `eip155:8453`（Base 主网） | - | ✅ |
 | `eip155:84532`（Base Sepolia） | - | ✅（CLI/SDK 测试） |
 
-> 其他上游 EVM 链（MegaETH、Monad、Hyperliquid）也已接入 EVM 默认资产注册表。公开 API Catalog 只发布 Base 主网路由；Base Sepolia 保留用于 CLI/SDK 测试。
+> 另有约 20 条上游 EVM 链（MegaETH、Monad、Polygon、Arbitrum One/Sepolia、Celo、XDC、Flare、Mezo、Radius、Stable、ADI、HPP、Igra 等）也已接入 EVM 默认资产注册表。公开 API Catalog 只发布 Base 主网路由；Base Sepolia 保留用于 CLI/SDK 测试。
 
 ---
 
@@ -73,6 +75,20 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 | `batch-settlement` | ✅ | ✅ | 支付通道：链上一次性存入，然后用链下凭证支付多次请求；facilitator 批量 claim 并在一笔交易中结算。含退款路径。 |
 | `exact_gasfree` | ❌ | ✅ | 仅 TRON。用 USDT/USDD 付款**无需持有 TRX 支付 gas**——由 relayer 通过 GasFree API 支付链上 energy。 |
 
+### 付款流程（1.1.0 新增）
+
+scheme/network server 现在会按资产转账方式声明自己支持哪些付款流程。`upfront` 与 `escrow` 会通过 `extra.paymentFlow` 在协议中传递；`authorization` 是默认流程，不会写入 `extra`——字段缺失即代表它：
+
+| 流程 | 含义 |
+|------|------|
+| `authorization` | client 签署授权，facilitator 在结算时划走资金——即 `exact` / `upto` 的经典行为，也是默认流程。 |
+| `upfront` | client 在资源交付前先转出资金。 |
+| `escrow` | 资金先锁进托管，之后再捕获、作废或退款，而不是直接转给卖家。 |
+
+v1.0 的 `SchemeNetworkServer` 实现可以不声明付款流程，它们会继续沿用 authorization 流程。
+
+`upfront` 与 `escrow` 是给自定义方案用的编排钩子。截至 1.1.0，内置的四个 server 方案（`exact`、`upto`、`batch-settlement`、`exact_gasfree`）都只声明 `authorization`，因此使用内置方案时 `extra.paymentFlow` 不会出现在协议数据里。
+
 > **x402 Foundation v2 兼容性**：`exact` 方案（EVM 和 TRON）符合 **x402 Foundation** 发布的 v2 线格式。标准 v2 client 可与本 SDK 的 server 互通，反之亦然。详见[网络与代币支持 → `exact` 方案](./core-concepts/network-and-token-support.md#exact-scheme)。
 
 ---
@@ -88,6 +104,7 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 | `createFacilitatorTronSigner` | Facilitator（TRON） |
 | `createFacilitatorEvmSigner` | Facilitator（EVM） |
 | `createAuthorizerTronSigner` | Authorizer（TRON，batch-settlement） |
+| `createAuthorizerEvmSigner` | Authorizer（EVM，batch-settlement） |
 
 ---
 
@@ -103,6 +120,14 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 | 余额感知的付款选择（`filterAffordableRequirements`） | ✅ |
 | 最低价代币选择策略 | ✅ |
 | GasFree（零 gas TRON 付款） | ✅ |
+| 消费管控（默认资产白名单 + 单笔上限） | ✅ —— **1.1.0 起默认开启** |
+| 按资产的原子单位上限（`allowedAssets[].maxAmountPerPayment`） | ✅ |
+| 付款选择策略（`PaymentPolicy`） | ✅ |
+| 生命周期钩子（`onBeforePaymentCreation`、`onAfterPaymentCreation`、`onPaymentCreationFailure`、`onPaymentResponse`） | ✅ |
+
+:::caution 消费管控默认开启
+1.1.0 起，client 只会支付默认资产注册表中认识的资产，且每笔付款上限为 `DEFAULT_MAX_AMOUNT_PER_PAYMENT`（约合 `$1`）。要提高上限，用 `spendControls.maxAmountPerPayment`（`Money` 值，或 `false` 取消上限）。要支付自定义代币，把它列入 `spendControls.allowedAssets`（可单独设置 `maxAmountPerPayment`，但该值必须是最小单位的整数，而非美元金额），或设 `allowedAssets: true` 放行任意资产。`spendControls: false` 则整体关闭该防护。
+:::
 
 ---
 
@@ -115,7 +140,6 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 | gas 赞助扩展（Permit2 approve） | ✅ |
 | 付款验证（通过 facilitator） | ✅ |
 | 付款结算（通过 facilitator） | ✅ |
-| 费率支持 | ✅ |
 
 ---
 
@@ -129,8 +153,11 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 | 提交链上交易 | ✅ |
 | 确认交易（回执轮询） | ✅ |
 | 扩展钩子（`onBeforeSettle` / `onAfterSettle` / `onSettleFailure`） | ✅ |
+| EVM 智能账户——已部署账户、ERC-7702 委托、ERC-6492 反事实钱包 | ✅ —— 签名验证在 facilitator 侧；ERC-6492 需显式配置 `eip6492AllowedFactories` 白名单 |
 
-> 自托管示例 facilitator（`facilitator/basic`）暴露 `/verify`、`/settle`、`/supported`。官方托管 facilitator 额外提供 `/fee/quote` 和 `/payments/{id}` 查询端点——详见[官方 Facilitator](./core-concepts/OfficialFacilitator.md)。
+> 自托管示例 facilitator（`facilitator/basic`）暴露 `/verify`、`/settle`、`/supported`。官方托管 facilitator 额外提供结算记录查询 `GET /payments/tx/{tx_hash}` 与 `GET /payments`，以及 `/health`——详见[官方 Facilitator](./core-concepts/OfficialFacilitator.md)。Prometheus 指标在独立的监控端口上（发布配置中为 `9001`），不在对外 API 端口。没有 `/fee/quote` 端点：SDK 的各方案不收取 facilitator 费用。
+>
+> 1.1.0 起，`HTTPFacilitatorClient` 使用带类型的超时错误、限流重试，默认超时 90 秒。
 
 ---
 
@@ -138,15 +165,16 @@ x402 支持四种付款方案。每种方案按链族实现为 client + server +
 
 | 代币 | 网络 | 状态 |
 |--------|---------|--------|
-| USDT（TRC-20） | `tron:0x2b6653dc`、`tron:0xcd8690dc` | ✅ |
+| USDT（TRC-20） | `tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e` | ✅ |
 | USDD（TRC-20） | `tron:0x2b6653dc`、`tron:0xcd8690dc` | ✅ |
 | USDT（BEP-20） | `eip155:56`、`eip155:97` | ✅ |
 | USDC（BEP-20） | `eip155:56`、`eip155:97` | ✅ |
-| EPS（BEP-20） | `eip155:56` | ✅ |
 | DHLU（BSC 测试网，ERC-3009） | `eip155:97` | ✅ |
 | 官方 USDC（ERC-20，EIP-3009） | `eip155:8453`、`eip155:84532` | ✅ |
 | 自定义 TRC-20 / BEP-20 | 任意 | ✅（通过代币注册表 / `EVM_TOKENS` 配置） |
 
+> 其中只有一部分是**默认资产**：TRON 与 BSC 主网上的 USDT、BSC 测试网与 Base 上的 USDC。1.1.0 起，客户端消费管控会拒绝其余资产——USDD、BSC 主网 USDC、BSC 测试网 USDT、DHLU、自定义代币——除非通过 `spendControls.allowedAssets` 放行。详见[网络与代币支持](./core-concepts/network-and-token-support.md#supported-tokens)。
+
 ---
 
 ## 可观测性
diff --git a/package.json b/package.json
index 6e20581..09582ae 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@x402-tron/docs",
-  "version": "1.3.24",
+  "version": "1.3.25",
   "description": "x402-tron documentation",
   "license": "MIT",
   "resolutions": {