fix

Author: jizhen181-dot

docs/x402/api-catalog/get-started.md

@@ -1,24 +1,22 @@
 ---
 title: Get Started
 sidebar_label: Get Started
-description: Plug your Agent into the API Catalog in 3 minutes — install the Agent Wallet, then one MCP install to discover and call every service in the catalog.
+description: Plug your Agent into the API Catalog in 3 minutes — install the Agent Wallet, then install the x402 CLI to discover and call every service in the catalog.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # Get Started
 
-Two steps and under 3 minutes to plug your Agent into the whole catalog: install the wallet, then do one MCP install. After that, your Agent can discover and call any service in the catalog by name, paying per call on-chain.
+Two steps and under 3 minutes to plug your Agent into the whole catalog: install the wallet, then install the x402 CLI. After that, your Agent can discover and call any service in the catalog, paying per call on-chain.
 
-**Prerequisite**: an MCP-compatible Agent (Claude Code, OpenAI Codex, Cursor, Continue, etc.).
+**Prerequisite**: Node.js (for the wallet) and Python with `pip` (for the CLI).
 
 ## Step 1: Install the Agent Wallet
 
 Run the command below to install a local wallet that manages stablecoins on TRON & BNB Chain. Every paid call your Agent makes from now on is signed locally by this wallet.
 
 ```bash
 npm i @bankofai/agent-wallet
+agent-wallet --help
 ```
 
 :::tip No wallet yet?
@@ -29,54 +27,58 @@ Follow the [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md) to creat
 Keep only a small amount of stablecoins in the wallet for per-call payments. Never store your main assets in an Agent wallet.
 :::
 
-## Step 2: Connect the Catalog to your Agent
-
-One MCP install and your Agent immediately sees every service in the catalog and can call them by name — no accounts, no API keys to manage.
+## Step 2: Install the x402 CLI
 
-<Tabs>
-  <TabItem value="claude" label="Claude Code" default>
+One install connects your Agent to the catalog — it discovers and calls every service over x402, paying per call. No accounts, no API keys to manage.
 
 ```bash
-claude mcp add bankofai -s user -- npx @bankofai/mcp-catalog
+pip install bankofai-x402-cli
+x402-cli --version
 ```
 
-  </TabItem>
-  <TabItem value="other" label="Other MCP Agents">
-
-Also works with OpenAI Codex, Cursor, Continue, and any MCP-compatible Agent: add a server named `bankofai` to its MCP configuration, with the startup command:
+Once installed, your Agent can discover and call services through the CLI. Search by name or keyword to see what's in the catalog:
 
 ```bash
-npx @bankofai/mcp-catalog
+x402-cli catalog search <keyword> --catalog https://catalog.bankofai.io/api/catalog.json --json
 ```
 
-  </TabItem>
-</Tabs>
-
-Once installed, just tell your Agent what you want in plain language — for example, "find a weather API and look up the current weather in Shanghai." The Agent finds the service in the catalog, gets a quote, pays on-chain with the wallet, and brings back the result — discovery, payment, and the call all happen automatically.
-
-## Calling from the command line (optional)
-
-If you prefer the terminal, `x402-cli` offers the same capabilities: search, inspect, and make paid calls directly.
-
-Search by name or keyword to see what's in the catalog:
+Inspect a service's details and available endpoints:
 
 ```bash
-x402-cli catalog search weather --catalog https://catalog.bankofai.io/api/catalog.json --json
+x402-cli catalog show <fqn> --catalog https://catalog.bankofai.io/api/catalog.json --json
+x402-cli catalog endpoints <fqn> --catalog https://catalog.bankofai.io/api/catalog.json --json
 ```
 
-Inspect a service's details and available endpoints:
+Then make a paid call against the target endpoint — quote, payment, and result retrieval in one step. A simple GET endpoint needs nothing more than the URL:
 
 ```bash
-x402-cli catalog show acme-weather --catalog https://catalog.bankofai.io/api/catalog.json --json
-x402-cli catalog endpoints acme-weather --catalog https://catalog.bankofai.io/api/catalog.json --json
+x402-cli pay 'https://gateway.bankofai.io/providers/<fqn>/...'
 ```
 
-Then make a paid call against the target endpoint — quote, payment, and result retrieval in one step:
+For a POST endpoint, or to pin the payment chain, token, and scheme, pass them explicitly:
 
 ```bash
-x402-cli pay 'https://gateway.bankofai.io/providers/acme-weather/v1/current?city=Shanghai'
+x402-cli pay 'https://gateway.bankofai.io/providers/<fqn>/<path>' \
+  --method POST \
+  --network tron:mainnet \
+  --token USDT \
+  --scheme exact_gasfree \
+  --max-amount 0.001 \
+  --header 'Content-Type: application/json' \
+  --body '{ ... }'
 ```
 
+| Flag | Purpose |
+|---|---|
+| `--method` | HTTP method (defaults to `GET`) |
+| `--network` | CAIP-2 payment chain, e.g. `tron:mainnet`, `eip155:56` |
+| `--token` | Settlement token, e.g. `USDT` |
+| `--scheme` | Payment scheme — `exact_gasfree` (TRON) or `exact_permit` (EVM) |
+| `--max-amount` | Spend ceiling in USD; the call aborts if the quote exceeds it |
+| `--header` / `--body` | Request headers and body for the upstream call |
+
+A service that settles on multiple chains exposes one route per network (`x402Routes`); pick the route — and the matching `--network` / `--scheme` — for the chain you want to pay on.
+
 :::tip
 `--catalog` can point to the hosted URL above or to a locally built `dist/catalog.json` for offline debugging.
 :::

docs/x402/api-catalog/index.md

@@ -41,20 +41,22 @@ Three consumers share the same data:
 
 ## What's in the catalog
 
-The catalog spans AI models, data, compute, web tools, messaging, DeFi, and more. Typical live services:
-
-| Service | Category | What it does | Billing |
-|---|---|---|---|
-| LLM Aggregator | AI | OpenAI-compatible API across frontier models from Anthropic, OpenAI, Google, DeepSeek, and more | per token |
-| SunPump · Create Token | DeFi | Launch a Meme token on SunPump — name, symbol, description, image | per launch (stay tuned) |
-| SUN Swap | DeFi | Swap, liquidity, and farming on TRON via the SUN protocol | per call |
-| Wolfram\|Alpha | Compute | Computational engine for math, science, and factual queries | per call |
-| ScreenshotOne | Web Tools | Capture any webpage as a high-quality image | per shot |
-| Textbelt SMS | Messaging | Send SMS to any phone number, no A2P registration | per message |
-| 2Captcha | Web Tools | Solve image, reCAPTCHA, and hCaptcha challenges programmatically | per solve |
+The first live services cover token creation plus DeFi market data and on-chain security — all settling across TRON and BNB Chain, with more being added over time:
+
+| Service | What it does | Billing |
+|---|---|---|
+| SunPump Agent Token Launch | Pay with x402, then submit token-launch metadata (name, symbol, description, image) to SunPump — the gateway forwards your request after settlement | From $0.001 / call |
+| DefiLlama Token Price | Current and historical USD price for one or many tokens, price charts, and percent change | Free |
+| DefiLlama DeFi Data | Protocol TVL, fees/revenue, and stablecoin metrics for research and risk screening | Free |
+| DefiLlama Yields / APY | List and compare DeFi pool yields (APY/TVL), plus a pool's historical series | Free |
+| DexScreener DEX Data | Token DEX pairs, price and liquidity; token search; latest new-listing profiles | Free |
+| DIA Token Price | Real-time, multi-source aggregated USD price by symbol or by chain + contract address | Free |
+| GoPlus Token & Address Security | Honeypot/scam checks, malicious-address screening, and risky-approval detection | Free |
+
+All of the above are in the **Finance** category and available on both TRON and BNB Chain.
 
 :::note
-The live service list and statistics (service count, chain count, etc.) are **generated dynamically** from catalog data — treat `/api/catalog.json` as the source of truth; this page hard-codes no numbers.
+The live service list and statistics (service count, chain count, etc.) are **generated dynamically** from catalog data — treat `/api/catalog.json` as the source of truth; this page hard-codes no numbers, and the catalog grows as new services are listed.
 :::
 
 ## Next steps

docs/x402/api-catalog/list-your-service.md

@@ -147,9 +147,10 @@ CI enforces the following rules — go through them before submitting:
 - `version` must be `1`.
 - `fqn` is lowercase letters/digits/hyphens and must match the directory name.
 - `category` must be one of the allowed values (see [reference](./reference.md#allowed-categories)).
-- `chains` needs at least one entry, using CAIP-2 style chain IDs (e.g. `tron:mainnet`, `eip155:56`).
+- `chains` needs at least one entry, using CAIP-2 style chain IDs — mainnets or testnets (e.g. `tron:mainnet`, `tron:nile`, `eip155:56`, `eip155:97`).
 - `isFirstParty`, `isFeatured` (booleans) and `featuredTags` (string array, may be empty `[]`) are **required** — missing any of them fails validation.
 - For every endpoint: `method` must be uppercase, `path` must start with `/`, and `maxPriceUsd` must not be less than `minPriceUsd`.
+- _(Optional)_ An endpoint that settles across multiple chains can add `x402Routes` — one entry per network (`network`, `provider`, `scheme`, `url`). See the [reference](./reference.md#x402routes--multi-network-routing).
 - The service and every endpoint must provide `i18n.zh-CN` translations for `title`, `subtitle`, `description`, and `useCase`.
 - `pay.md` must be submitted together with `catalog.json`; both files are scanned for sensitive data.
 - No keys, private keys, or private network addresses anywhere.

docs/x402/api-catalog/reference.md

@@ -50,6 +50,35 @@ Each service is described in `providers/<fqn>/catalog.json`. Top-level fields:
 | `metered` | boolean | Yes | Metered billing or not |
 | `minPriceUsd` | number | Yes | Minimum price (USD) |
 | `maxPriceUsd` | number | Yes | Maximum price (USD), must not be less than `minPriceUsd` |
+| `x402Routes` | object[] | No | Per-network payment routes (see below) |
+
+### x402Routes — multi-network routing
+
+An endpoint may serve the same capability across several chains, each settling through its own gateway provider and payment scheme. List those alternatives in `x402Routes`; each route describes one network:
+
+| Field | Type | Description |
+|---|---|---|
+| `network` | string | CAIP-2 chain ID this route settles on (e.g. `tron:mainnet`, `eip155:56`) |
+| `provider` | string | The gateway provider `fqn` that handles this network |
+| `scheme` | string | Payment scheme — `exact_gasfree` (TRON) or `exact_permit` (EVM) |
+| `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.
+
+For example, a token-launch endpoint might expose four routes — TRON Nile, TRON Mainnet, BSC Testnet, BSC 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`:
+
+```bash
+x402-cli pay 'https://gateway.bankofai.io/providers/<provider>/<path>' \
+  --method POST \
+  --network tron:mainnet \
+  --token USDT \
+  --scheme exact_gasfree \
+  --max-amount 0.001 \
+  --header 'Content-Type: application/json' \
+  --body '{ ... }'
+```
+
+The other routes reuse the same request body, swapping only the route `url`, `--network`, and `--scheme` (TRON routes use `exact_gasfree`; EVM routes use `exact_permit`).
 
 ### status block
 
@@ -76,12 +105,17 @@ security   shopping    storage     translation
 
 ## Chain IDs
 
-`chains` uses CAIP-2 style chain identifiers:
+`chains` uses CAIP-2 style chain identifiers. Mainnets and testnets are both recognized:
 
 | Chain | ID |
 |---|---|
 | TRON mainnet | `tron:mainnet` |
+| TRON Nile testnet | `tron:nile` |
+| TRON Shasta testnet | `tron:shasta` |
 | BNB Chain (BSC) | `eip155:56` |
+| BNB Smart Chain testnet | `eip155:97` |
+
+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
 
@@ -120,10 +154,10 @@ Besides the `providers` array, the list endpoint carries dynamic stats — front
 | `chain_count` | Chains covered |
 | `generated_at` | Build time (UTC) |
 | `frontend.featured_fqns` | `fqn` list of featured services |
-| `frontend.categories` | Categories and counts |
-| `frontend.chains` | Chains and counts |
+| `frontend.categories` | Categories in use — each `{ id, label, label_zh, count }` |
+| `frontend.chains` | Chains in use — each `{ id, kind, label, label_zh, count }` |
 
-The `providers` array is pre-sorted at build time by **featured first → category → fqn**; frontends can render it as-is.
+The `providers` array is pre-sorted at build time by **featured first → category → fqn**; frontends can render it as-is. Use `frontend.categories` / `frontend.chains` to drive filter UIs — including their `label` / `label_zh` display names — rather than hard-coding category or chain lists.
 
 ### Derived fields
 
@@ -137,11 +171,26 @@ Build outputs add derived fields on top of the raw data and convert everything t
 | `min_price_usd` / `max_price_usd` | The service's price range across all endpoints |
 | `sha` | Content hash of `catalog.json` + `pay.md`, for change detection |
 
+### Frontend display fields
+
+To save the frontend from parsing raw IDs and picking translations, the build also emits ready-to-render fields on each provider summary and detail:
+
+| Field | Description |
+|---|---|
+| `title_zh` | Chinese service name (falls back to `title`) — usable directly as the first header line |
+| `main_title` | Primary title (equals `title`) — second header line |
+| `sub_title` | Subtitle — third header line |
+| `category_meta` | `{ id, label, label_zh }` for the category |
+| `chain_kinds` | De-duplicated friendly chain kinds, e.g. `["tron"]`, `["bnb"]` |
+| `chains_meta` | Per-chain `{ id, kind, label, label_zh }`, so the frontend never parses CAIP-2 |
+
+These are additive — the raw `title`, `subtitle`, `category`, `chains`, and `i18n.zh-CN` are still present. A separate frontend-facing contract (`API.md` in the catalog repo) documents the full response shapes and rendering guidance.
+
 ### Other output structures
 
-- **`/api/pay/<fqn>.json`**: payment summary for Agents / CLI. Top level: `version`, `fqn`, `title`, `subtitle`, `description`, `use_case`, `i18n`, `service_url`, `chains`, `sha`; `endpoints[]` keeps only call-relevant fields: `method`, `path`, `url`, `description`, `metered`, `min_price_usd`, `max_price_usd`.
-- **`/api/search-index.json`**: `{ version, generated_at, documents[] }`, each document being a service summary plus each endpoint's `method` / `path` / `title` / `description`.
-- **`/api/categories.json`**: array of categories in use, each `{ id, count }`.
+- **`/api/pay/<fqn>.json`**: payment summary for Agents / CLI. Top level includes `version`, `fqn`, `title`, `title_zh`, `main_title`, `sub_title`, `subtitle`, `description`, `use_case`, `i18n`, `service_url`, `chains`, `chain_kinds`, `chains_meta`, `sha`; `endpoints[]` keeps the call-relevant fields `method`, `path`, `url`, `description`, `metered`, `min_price_usd`, `max_price_usd`, plus `x402_routes` when the endpoint defines multi-network routes.
+- **`/api/search-index.json`**: `{ version, generated_at, documents[] }`, each document being a service summary (with `category_meta` / `chain_kinds` / `chains_meta`) plus each endpoint's `method` / `path` / `title` / `description` (and `x402_routes` when present).
+- **`/api/categories.json`**: array of categories in use, each `{ id, label, label_zh, count }` — a direct export of `frontend.categories`.
 - **`/api/status.json`**: `{ version, generated_at, provider_count, status }`; `status` of `ok` means the build is healthy.
 
 ## Local build and run