Docs: x402 CLI v1.0.1/v1.0.2 updates (Base, GasFree, Agent Wallet payer)

changelog/index.md

@@ -7,6 +7,21 @@ 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">Jul 30, 2026</div>
+<div className="changelog-body">
+
+### x402 CLI v1.0.2 · Catalog — Base support
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">x402</span><span className="changelog-tag">Base</span></div>
+
+- **Base is live in the CLI** — `eip155:8453` and `eip155:84532` both support USDC. The service catalog currently publishes Base Mainnet routes on `eip155:8453` only. Base settles under `exact` using EIP-3009 authorization instead of Permit2.
+- **Agent Wallet is now the CLI's default payer** — `pay` signs with your active wallet, so no private key in an environment variable. With wallets configured but none active, the CLI stops before signing rather than choosing for you. [Details](./x402/)
+- Paid requests no longer follow HTTP redirects, keeping `PAYMENT-SIGNATURE` from reaching another origin.
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 21, 2026</div>
 <div className="changelog-body">
@@ -25,6 +40,20 @@ Product updates and announcements for BANK OF AI.
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">Jul 20, 2026</div>
+<div className="changelog-body">
+
+### x402 CLI v1.0.1 · Catalog
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">x402</span><span className="changelog-tag">TRON</span></div>
+
+- **x402 CLI v1.0.1** — TRON **GasFree** payments (`exact_gasfree`, no TRX needed), canonical CAIP-2 network IDs (legacy `tron:nile` rejected), and `settled` vs `delivered` reporting. Built on x402 SDK 1.0.1. [Details](./x402/)
+- **x402 Catalog** — routes now support `exact_gasfree` on TRON; canonical CAIP-2 required; legacy `fee` / `feeConfig` fields dropped. [Details](./x402/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Jul 17, 2026</div>
 <div className="changelog-body">

changelog/x402.md

@@ -5,7 +5,78 @@ description: 'Release notes for the x402 payment protocol, SDK, and CLI.'
 
 # x402 Payment Protocol
 
-Release notes for the x402 protocol, SDK, and [CLI](../x402/cli/).
+Release notes for the x402 protocol, SDK, and [CLI](/x402/cli/).
+
+<div className="changelog-entry">
+<div className="changelog-date">Jul 30, 2026</div>
+<div className="changelog-body">
+
+### x402 CLI v1.0.2 — Base USDC & Agent Wallet
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">CLI</span><span className="changelog-tag">Base</span></div>
+
+- **Base support** — `eip155:8453` (Mainnet) and `eip155:84532` (Sepolia), both with USDC, plus the `base-mainnet` / `base-sepolia` aliases. Base settles through the standard `exact` scheme using **EIP-3009** authorization rather than Permit2. Supply your own RPC in production via `--rpc-url` or `EVM_RPC_URL_8453` / `EVM_RPC_URL_84532`.
+- **Agent Wallet is now the default payer** — `pay` resolves your active [Agent Wallet](/Agent-Wallet/Intro/) and delegates signing, so no private key sits in an environment variable. If wallets are configured but none is active, the CLI **stops before signing** instead of picking one for you. Select explicitly with `--wallet-id` / `AGENT_WALLET_ID`, or point at another directory with `AGENT_WALLET_DIR`. Private keys are now a development/CI override only.
+- **Redirects are no longer followed** on paid requests, so `PAYMENT-SIGNATURE` can't be forwarded to another origin.
+- **EVM balance pre-check** — the CLI verifies the payer's token balance before signing and returns the resolved wallet ID, address, and raw balance.
+- New: `pay --asset` / `--decimals`, `serve --valid-for-seconds` (default `300`), and `roundtrip --json` emitting one document with separate `serve` and `pay` results.
+- New wallet error codes: `WALLET_PASSWORD_REQUIRED`, `WALLET_DECRYPTION_FAILED`, `WALLET_CONFIG_CORRUPT`, `WALLET_NETWORK_ERROR`.
+
+👉 [x402 CLI docs](/x402/cli/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Jul 30, 2026</div>
+<div className="changelog-body">
+
+### x402 Catalog — Base routes
+
+<div className="changelog-tags"><span className="changelog-tag">Update</span><span className="changelog-tag">Catalog</span><span className="changelog-tag">Base</span></div>
+
+- Published **Base Mainnet catalog routes** on `eip155:8453`, with payment guides and code examples. Base Sepolia remains available in the CLI but is not published in the service catalog.
+- `assetTransferMethod` now accepts **`eip3009`** alongside `permit2` — Base USDC routes use `eip3009`.
+
+👉 [API Catalog reference](/x402/api-catalog/reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Jul 20, 2026</div>
+<div className="changelog-body">
+
+### x402 CLI v1.0.1
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">CLI</span><span className="changelog-tag">TRON</span></div>
+
+- **GasFree payments (`exact_gasfree`) on TRON** — a relayer pays the network energy and deducts its fee from the payment token, so the payer needs no TRX. New flags: `--scheme exact_gasfree`, `--max-gasfree-fee`, `--max-gasfree-fee-raw`, `--gasfree-api-url`.
+- **Canonical CAIP-2 network IDs** — `tron:0x2b6653dc` (Mainnet), `tron:0xcd8690dc` (Nile), `tron:0x94a9059e` (Shasta). Legacy identifiers like `tron:nile` / `tron:mainnet` are now **rejected** — the CLI tells you the canonical ID to use.
+- **Settlement reporting** — paid responses distinguish `settled` (payment cleared on-chain) from `delivered` (upstream HTTP response succeeded).
+- Built on x402 SDK 1.0.1.
+
+👉 [x402 CLI docs](/x402/cli/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Jul 20, 2026</div>
+<div className="changelog-body">
+
+### x402 Catalog — GasFree routes & CAIP-2
+
+<div className="changelog-tags"><span className="changelog-tag">Update</span><span className="changelog-tag">Catalog</span></div>
+
+- Catalog routes now support **`exact_gasfree`** on TRON, alongside `exact` + Permit2.
+- Network IDs must be **canonical CAIP-2**; legacy TRON aliases like `tron:nile` are rejected by schema validation.
+- With x402 SDK 1.0.1, GasFree cost is estimated client-side — routes must no longer publish the legacy `fee` / `feeConfig` fields.
+
+👉 [API Catalog reference](/x402/api-catalog/reference/)
+
+</div>
+</div>
 
 <div className="changelog-entry">
 <div className="changelog-date">Jul 15, 2026</div>
@@ -24,7 +95,7 @@ First stable release of `@bankofai/x402-cli` — a TypeScript command-line clien
 - Built on the published `@bankofai/x402-core` / `x402-evm` / `x402-tron` SDK 1.0 packages; `scheme=exact` with Permit2
 - Networks: TRON (`tron:mainnet` / `tron:nile` / `tron:shasta`) and BSC (`eip155:56` / `eip155:97`)
 
-👉 Get started: [x402 CLI Quick Start](../x402/cli/quickstart/)
+👉 Get started: [x402 CLI Quick Start](/x402/cli/quickstart/)
 
 </div>
 </div>

docs/Agent-Wallet/Developer/CLI-Reference.md

@@ -58,6 +58,33 @@ agent-wallet start -p Abc12345! -k your-private-key-hex
 agent-wallet start -p Abc12345! -m "word1 word2 word3 ..."
 ```
 
+#### Skip the prompts: name the wallet type directly
+
+`start` and `add` also take the wallet type as a subcommand. That form asks nothing, which is what you want in CI or any background service:
+
+```bash
+agent-wallet start local_secure -p Abc12345! -g      # encrypted, generate a new key
+agent-wallet start raw_secret -k your-private-key    # plaintext, dev only
+agent-wallet start privy --app-id <id> --app-secret <secret> --privy-wallet-id <wallet>
+```
+
+`add` works the same way (`add local_secure` / `add raw_secret` / `add privy`) for a second wallet.
+
+| Option | Applies to | Description |
+| :--- | :--- | :--- |
+| `-w, --wallet-id <id>` | all | Wallet ID to create |
+| `-g, --generate` | `local_secure` | Generate a new random key |
+| `-k, --private-key <hex>` | `local_secure`, `raw_secret` | Import a private key |
+| `-m, --mnemonic <words>` | `local_secure`, `raw_secret` | Import a mnemonic |
+| `--mnemonic-index <n>` | `local_secure`, `raw_secret` | Account index when deriving from the mnemonic |
+| `-p, --password <pass>` | `local_secure` | Master password |
+| `--app-id` / `--app-secret` / `--privy-wallet-id` | `privy` | Privy app credentials and wallet ID |
+| `-d, --dir <path>` | all | Secrets directory (default `~/.agent-wallet`) |
+| `--save-runtime-secrets` | all | Persist the password to `runtime_secrets.json` |
+| `--override` | `start` only | Overwrite an existing setup |
+
+Run `agent-wallet start local_secure --help` or `agent-wallet add privy --help` for the exact options of one mode.
+
 ### `agent-wallet sign` (Core Signing Operations)
 
 Every `sign` subcommand requires `--network` / `-n` to specify the chain.

docs/Agent-Wallet/Developer/SDK-Guide.md

@@ -195,6 +195,10 @@ If both a password and a private key exist in your environment variables, the SD
 | `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | ⚠️ Static Injection | Choose one (with private key) |
 | `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 derivation index (default `0`) | ⚠️ Static Injection | Optional |
 
+:::note Legacy variable names
+The SDK still accepts the older `TRON_PRIVATE_KEY`, `TRON_MNEMONIC`, and `TRON_ACCOUNT_INDEX` variables, which map to `AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`, and `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`. They work on EVM networks too, despite the name. Prefer the `AGENT_WALLET_*` names in new setups.
+:::
+
 ---
 
 ## Usage Examples

docs/x402/AGENTS.md

@@ -83,6 +83,15 @@ Documentation must reflect code changes immediately. Follow these dependency map
 - **Node Access**: Must connect to EVM-compatible JSON-RPC endpoints.
 - **Test Example**: BSC Testnet mock USDT address — `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd`.
 
+</TabItem>
+<TabItem value="BASE" label="Base">
+
+- **Network Identifier**: Base Mainnet must use canonical CAIP-2 ID `eip155:8453`.
+- **Settlement Asset**: Use official Base USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
+- **Payment Scheme**: Use `exact` with EIP-3009 authorization; do not describe Base USDC as Permit2.
+- **Address Format**: Payout and token addresses use EVM hexadecimal (`0x`) format.
+- **Catalog Scope**: Public catalog examples use Base Mainnet only. Base Sepolia (`eip155:84532`) may appear only in explicit CLI/SDK testing documentation.
+
 </TabItem>
 </Tabs>
 

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

@@ -12,7 +12,7 @@ Two steps and under 3 minutes to plug your Agent into the whole catalog: install
 
 ## 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.
+Run the command below to install a local wallet that manages stablecoins on TRON, BNB Chain, and Base. Every paid call your Agent makes from now on is signed locally by this wallet.
 
 ```bash
 npm i -g @bankofai/agent-wallet
@@ -73,8 +73,8 @@ x402-cli pay 'https://x402-gateway.bankofai.io/providers/<fqn>/<path>' \
 | Flag | Purpose |
 |---|---|
 | `--method` | HTTP method (defaults to `GET`) |
-| `--network` | CAIP-2 payment chain, e.g. `tron:0x2b6653dc`, `eip155:56` |
-| `--token` | Settlement token, e.g. `USDT` |
+| `--network` | CAIP-2 payment chain, e.g. `tron:0x2b6653dc`, `eip155:56`, `eip155:8453` |
+| `--token` | Settlement token, e.g. `USDT` or Base Mainnet `USDC` |
 | `--scheme` | x402 payment scheme declared by the route, e.g. `exact` |
 | `--max-amount` | Spend ceiling in USD; the call aborts if the quote exceeds it |
 | `--header` / `--body` | Request headers and body for the upstream call |

docs/x402/api-catalog/index.md

@@ -8,7 +8,7 @@ description: BANK OF AI's wallet-native service catalog — where AI Agents disc
 
 Traditional API onboarding is designed for humans: create an account, request an API key, link a credit card, subscribe monthly. When an AI Agent wants to call an API on its own, it fails at the very first step — it has no email, no credit card, and it shouldn't be holding a pile of secret keys for you anyway.
 
-The **API Catalog** is BANK OF AI's wallet-native service catalog. AI Agents discover services here, call them by name, and pay per call — every call settles on-chain via x402. No accounts, no API keys: **your wallet is your identity**. The catalog covers both TRON and BNB Chain.
+The **API Catalog** is BANK OF AI's wallet-native service catalog. AI Agents discover services here, call them by name, and pay per call — every call settles on-chain via x402. No accounts, no API keys: **your wallet is your identity**. The catalog covers TRON, BNB Chain, and Base Mainnet.
 
 ## What it solves
 
@@ -41,7 +41,7 @@ Three consumers share the same data:
 
 ## What's in the catalog
 
-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:
+The first live services cover token creation plus DeFi market data and on-chain security, with routes settling across TRON, BNB Chain, and Base Mainnet as published by each provider:
 
 | Service | What it does | Billing |
 |---|---|---|
@@ -51,7 +51,7 @@ The first live services cover token creation plus DeFi market data and on-chain
 | DIA | Decentralized, multi-source oracle prices by symbol or by chain + contract address | $0.000001 / call |
 | GoPlus | Token and address security checks — honeypot/scam screening, malicious-address and risky-approval detection | $0.000001 / call |
 
-All of the above are in the **Finance** category and available on both TRON and BNB Chain.
+All of the above are in the **Finance** category. Check each endpoint's `x402Routes` for its currently published TRON, BNB Chain, and Base Mainnet routes.
 
 :::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, and the catalog grows as new services are listed.

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

@@ -8,7 +8,7 @@ description: List your API in the API Catalog — apply via the form or open a P
 
 List once — every AI Agent call after that is revenue in.
 
-Put your API behind the Gateway and it appears in the catalog: any Agent can discover it, call it, and pay for it. Payments settle to the wallet you specify in real time — **no platform escrow, no payout cycle**; settle on TRON or BNB Chain; your existing API stays exactly as it is, **not one line of code changes**, and you set the prices.
+Put your API behind the Gateway and it appears in the catalog: any Agent can discover it, call it, and pay for it. Payments settle to the wallet you specify in real time — **no platform escrow, no payout cycle**; settle on TRON, BNB Chain, or Base Mainnet; your existing API stays exactly as it is, **not one line of code changes**, and you set the prices.
 
 ## The big picture: what listing actually means
 
@@ -233,7 +233,7 @@ 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 — mainnets or testnets (e.g. `tron:0x2b6653dc`, `tron:0xcd8690dc`, `eip155:56`, `eip155:97`).
+- `chains` needs at least one entry, using CAIP-2 style chain IDs. The public catalog publishes mainnet routes such as `tron:0x2b6653dc`, `eip155:56`, and Base Mainnet `eip155:8453`.
 - `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).

docs/x402/api-catalog/reference.md

@@ -60,14 +60,19 @@ An endpoint may serve the same capability across several chains, each settling t
 
 | Field | Type | Description |
 |---|---|---|
-| `network` | string | CAIP-2 chain ID this route settles on (e.g. `tron:0x2b6653dc`, `eip155:56`) |
+| `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, e.g. `exact` — each route declares its own |
+| `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. |
 | `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 one route per supported chain — TRON Mainnet and 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`:
+:::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.
+:::
+
+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`:
 
 ```bash
 x402-cli pay 'https://x402-gateway.bankofai.io/providers/<provider>/<path>' \
@@ -116,6 +121,7 @@ security   shopping    storage     translation
 | TRON Shasta testnet | `tron:0x94a9059e` |
 | BNB Chain (BSC) | `eip155:56` |
 | BNB Smart Chain testnet | `eip155:97` |
+| Base mainnet | `eip155:8453` |
 
 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).
 
@@ -185,7 +191,7 @@ To save the frontend from parsing raw IDs and picking translations, the build al
 | `sub_title` | Secondary display line (from `subTitle`, falls back to `subtitle`) |
 | `sub_title_zh` | Chinese secondary display line (from `i18n.zh-CN.subtitle` / `subTitle`, falls back to `subtitle`) |
 | `category_meta` | `{ id, label, label_zh }` for the category |
-| `chain_kinds` | De-duplicated friendly chain kinds, e.g. `["tron"]`, `["bnb"]` |
+| `chain_kinds` | De-duplicated friendly chain kinds, e.g. `["tron"]`, `["bnb"]`, `["base"]` |
 | `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.