BofAI · boboliu-1010 · May 28, 2026 · May 28, 2026 · May 29, 2026 · Jun 4, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,10 +1,11 @@
-name: Test
+name: cli-ci
 
 on:
   push:
-    branches: [main, develop]
+    branches: [main, develop, feature/0.6.1-gateway-align]
   pull_request:
     branches: [main, develop]
+  workflow_dispatch:
 
 jobs:
   test:
@@ -17,7 +18,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -28,20 +29,24 @@ jobs:
           pip install -e ".[dev]"
 
       - name: Lint with ruff
-        run: |
-          ruff check src tests
+        run: ruff check src tests
 
       - name: Type check with mypy
-        run: |
-          mypy src/bankofai/x402_cli
+        run: mypy src/bankofai/x402_cli
 
       - name: Run tests with pytest
+        run: pytest tests/ -v --cov=src/bankofai/x402_cli --cov-report=xml
+
+      - name: CLI command smoke tests
         run: |
-          pytest tests/ -v --cov=src/bankofai/x402_cli --cov-report=xml
+          x402-cli --help
+          x402-cli catalog --help
+          x402-cli gateway --help
 
-      - name: Run smoke tests
+      - name: Build package
         run: |
-          bash .claude/smoke-test.sh
+          python -m pip install build
+          python -m build
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,34 @@ All notable changes to `bankofai-x402-cli` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] — 2026-06-24
+
+### Changed
+
+- Point the default hosted catalog URL at `https://x402-catelog.bankofai.io/api/catalog.json`.
+- Refresh CLI README and community examples to use production `x402-gateway.bankofai.io` mainnet routes.
+- Align catalog command fixtures with the merged production provider catalog: SunPump TRON/BSC mainnet `exact_permit` routes.
+
+## [0.6.1b6] — 2026-06-12
+
+### Changed
+
+- Classify token `TRANSFER_FROM_FAILED` settlement reverts as `TOKEN_TRANSFER_FAILED` with a payer balance/token mismatch hint.
+
+## [0.6.1b5] — 2026-06-12
+
+### Changed
+
+- Re-publish the CLI beta after PyPI accepted `0.6.1b2` through `0.6.1b4` files without exposing them in the simple package index.
+
+## [0.6.1b4] — 2026-06-11
+
+### Changed
+
+- Point the default hosted catalog URL at the Bank of AI hosted catalog.
+- Refresh Bank of AI gateway examples to the hosted gateway domain.
+- Cache provider detail and pay JSON files during `x402-cli catalog update`, with remote fallback from catalog `base_url` when local detail files are missing.
+
 ## [0.1.0] — 2026-05-08
 
 First stable release. Consolidates everything from `0.1.0-beta.5` through `0.1.0-beta.17`. The package is `pip install bankofai-x402-cli` (no `--pre` needed) and the binary is `x402-cli`.

diff --git a/README.md b/README.md
@@ -2,26 +2,29 @@
 
 The BankofAI command-line client for the x402 protocol — pay any x402-protected URL, run your own paywall, or test the full handshake locally. **No code required.**
 
+`x402-cli` is the single user-facing entrypoint. It includes payment commands, public catalog discovery, and provider gateway operations under one command tree. The gateway runtime is packaged underneath the CLI, so most users only install and remember `x402-cli`.
+
+Community copy-paste examples live in [`examples/README.md`](examples/README.md).
+
 ## 1. Install
 
 ```bash
-pip install --pre bankofai-x402-cli
+pip install bankofai-x402-cli==0.6.1
 x402-cli --version
 ```
 
 ## 2. Set up a wallet (one-time)
 
-`x402-cli` delegates all signing to [`bankofai-agent-wallet`](https://github.com/BofAI/agent-wallet). Fastest path — import a 32-byte hex private key:
+`x402-cli` delegates all signing to [`bankofai-agent-wallet`](https://github.com/BofAI/agent-wallet). Configure any supported wallet backend before paying.
 
 ```bash
-agent-wallet start raw_secret \
-  --wallet-id payer \
-  --private-key 0x<your-32-byte-hex-private-key>
+agent-wallet list
+agent-wallet resolve-address payer
 ```
 
 > A single key derives both an EVM address and a TRON address. **You don't need a separate wallet per chain.**
 >
-> Other setup paths (encrypted local store, mnemonic, Privy-managed): see [agent-wallet — Getting Started](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md).
+> Setup paths (encrypted local store, mnemonic, raw secret, Privy-managed): see [agent-wallet — Getting Started](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). Keep wallet secrets outside this repository.
 
 ## 3. What each command does
 
@@ -30,6 +33,73 @@ agent-wallet start raw_secret \
 | **`x402-cli pay <url>`** | The payer | Hits a URL, and if the server returns `402 Payment Required`, the cli signs + submits the payment + retrieves the response. |
 | **`x402-cli serve`** | The recipient | Starts a local `402` paywall endpoint that only returns content after a valid payment is settled. |
 | **`x402-cli roundtrip`** | Self-test / one-shot transfer | Spins up a `serve` in the background, runs `pay` against it, and tears it down. **The fastest way to make a payment from the command line** — and the easiest way to verify your install end-to-end. |
+| **`x402-cli catalog search <query>`** | API consumer / agent runtime | Searches the public x402 catalog to find a matching paid capability before calling it. |
+| **`x402-cli gateway start ...`** | API provider | Starts a self-hosted provider gateway from local `provider.yml` files. |
+| **`x402-cli catalog export-gateway <url> --provider <fqn>`** | API provider | Exports public `catalog.json` and `pay.md` files from a self-hosted gateway for PR submission. |
+
+Catalog search can read the hosted catalog, a local `dist/catalog.json`, or a gateway-exported catalog URL. This is the discovery step for agents and local tooling: the user asks for a capability, the catalog search finds matching paid APIs, then the normal x402 payment client can call the selected gateway URL.
+
+```bash
+export X402_CATALOG=https://x402-catelog.bankofai.io/api/catalog.json
+x402-cli catalog update
+x402-cli catalog search "token launch"
+x402-cli catalog show sunpump-token-launch
+x402-cli catalog endpoints sunpump-token-launch
+x402-cli catalog pay-json sunpump-token-launch
+```
+
+For local gateway development:
+
+```bash
+x402-cli gateway scaffold sunpump-token-launch-tron \
+  --output-dir providers/sunpump-token-launch-tron \
+  --forward-url https://api.example.com
+
+x402-cli gateway check providers/sunpump-token-launch-tron/provider.yml
+x402-cli gateway start --providers-dir providers --host 0.0.0.0 --port 4020
+```
+
+Expected flow with the gateway:
+
+```text
+Natural-language intent
+  -> x402-cli catalog search
+  -> x402-cli catalog show/endpoints/pay-json
+  -> provider endpoint from the catalog
+  -> x402-cli pay <gateway endpoint>
+  -> x402 SDK handles the 402 challenge and payment retry
+  -> upstream API result
+```
+
+Provider onboarding flow:
+
+```bash
+x402-cli gateway check providers/sunpump-token-launch-tron/provider.yml
+x402-cli gateway start --providers-dir providers --host 0.0.0.0 --port 4020
+
+x402-cli catalog export-gateway https://x402-gateway.bankofai.io \
+  --provider sunpump-token-launch-tron \
+  --output-dir providers/sunpump-token-launch-tron
+```
+
+The command writes public PR files only:
+
+```text
+providers/sunpump-token-launch/catalog.json
+providers/sunpump-token-launch/pay.md
+```
+
+Do not submit `provider.yml`, `.env`, upstream API keys, bearer tokens, or passwords.
+
+Provider catalog build commands are also under `x402-cli`:
+
+```bash
+x402-cli gateway catalog generate providers/sunpump-token-launch-tron/provider.yml
+x402-cli gateway catalog pay-assets providers/sunpump-token-launch-tron/provider.yml
+x402-cli gateway catalog check providers
+x402-cli gateway catalog build providers --dist-dir dist
+x402-cli gateway catalog search providers sunpump
+```
 
 ## 4. Copy-paste: a USDT transfer on TRON mainnet
 
@@ -63,16 +133,14 @@ Verify on chain at `https://tronscan.org/#/transaction/<tx-hash>`.
 >
 > *First-time only*: if this is your wallet's first payment for this token, the cli will ask you to sign and broadcast a one-time `approve` transaction (~6 TRX on mainnet) so the PaymentPermit contract can move tokens on your behalf later. After that, every payment is gas-free from your side.
 >
-> **Don't have any TRX at all?** Add `--scheme exact_gasfree` to skip even that one-time approve — it routes everything through a GasFree relayer that fronts gas in exchange for a per-settlement fee deducted from a derived custodial address. Setup: [docs/manual-test-guide.md → Walkthrough A](docs/manual-test-guide.md#4-walkthrough-a--tron-nile--exact_gasfree).
+> **Don't have any TRX at all?** Add `--scheme exact_gasfree` to skip even that one-time approve — it routes everything through a GasFree relayer that fronts gas in exchange for a per-settlement fee deducted from a derived custodial address.
 
 ### Templates for other networks
 
 | Network | Replace `--network` with | Notes |
 |---|---|---|
 | TRON mainnet (default permit) | `tron:mainnet` | Facilitator pays per-payment gas. One-time ~6 TRX approve when you first use a token from a fresh wallet. Add `--scheme exact_gasfree` to skip that too. |
 | BSC mainnet (USDT permit) | `eip155:56` | Same model — facilitator pays per-payment gas; one-time approve fee in BNB on first use. |
-| TRON Nile (testnet) | `tron:nile` | [Faucet](https://nileex.io/join/getJoinPage) |
-| BSC Testnet | `eip155:97` | [Faucet](https://testnet.bnbchain.org/faucet-smart) |
 
 To force a specific settlement scheme (instead of the auto-pick), add `--scheme exact_gasfree | exact_permit | exact`.
 

diff --git a/docs/manual-test-guide.md b/docs/manual-test-guide.md
@@ -37,7 +37,7 @@ Each walkthrough ends with a real on-chain transaction you can inspect on Tronsc
 ## 1. Install
 
 ```bash
-pip install --pre bankofai-x402-cli
+pip install bankofai-x402-cli==0.6.1
 x402-cli --version
 agent-wallet --help | head -3      # confirm agent-wallet ships with the CLI
 ```
@@ -328,6 +328,7 @@ Verify on BscScan: `https://testnet.bscscan.com/tx/<tx-hash>`.
 | `resolve_wallet could not find a wallet source` | No wallet config and no env var | Run step 2; fallback option is 2.D |
 | `Insufficient GasFree balance` (walkthrough A) | gasFreeAddress balance < amount + transferFee + (activateFee if first time) | Top up gasFreeAddress (4.2) and re-check (4.1) |
 | `GasFree account not activated` | First-time use of a gasFreeAddress | Make sure balance covers `activateFee`; first settlement auto-activates |
+| `TRANSFER_FROM_FAILED` / `TOKEN_TRANSFER_FAILED` | Settlement reached token `transferFrom()`, but the payer cannot transfer the requested token amount | Check payer token balance, provider pay JSON `asset/network/scheme`, token contract, and try a smaller `--max-amount` |
 | `too many pending transfers` | GasFree relayer rate limit | Wait 30–60s, retry |
 | `429 Too Many Requests` from facilitator | Settlement endpoint rate limit | Wait 30–60s, retry |
 | Settlement reverts with `permit`-related error (walkthrough B/C) | Token contract's `permit` domain doesn't match SDK's | Use `exact_gasfree` on TRON, or `exact` on EVM if the token supports ERC-3009 |
@@ -341,7 +342,7 @@ Verify on BscScan: `https://testnet.bscscan.com/tx/<tx-hash>`.
 
 ```
 # install
-pip install --pre bankofai-x402-cli
+pip install bankofai-x402-cli==0.6.1
 
 # wallet (one-time, plaintext for testing)
 export AGENT_WALLET_DIR=/tmp/x402-test-wallet

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,117 @@
+# x402-cli Community Examples
+
+This directory shows the common ways a community user should use `x402-cli`.
+The CLI is the only user-facing entrypoint: payment, catalog discovery, and
+gateway operations all live under `x402-cli`.
+
+## 1. Install
+
+```bash
+pip install bankofai-x402-cli==0.6.1
+x402-cli --version
+```
+
+Expected:
+
+```text
+x402-cli, version 0.6.1
+```
+
+## 2. Find a Paid API
+
+Search the public catalog:
+
+```bash
+x402-cli catalog update
+x402-cli catalog search "defillama"
+x402-cli catalog show defillama
+x402-cli catalog endpoints defillama
+x402-cli catalog pay-json defillama
+```
+
+Use a local catalog during development:
+
+```bash
+x402-cli catalog search "defillama" \
+  --catalog ../x402-catelog/dist/catalog.json \
+  --json
+```
+
+## 3. Call a Paid API
+
+After choosing an endpoint from the catalog:
+
+```bash
+x402-cli pay 'https://x402-gateway.bankofai.io/providers/defillama-tvl-tron/protocols' \
+  --method GET \
+  --network tron:mainnet \
+  --scheme exact_permit \
+  --token USDT \
+  --max-amount 0.001
+```
+
+For a dry run that reads the payment requirement without signing:
+
+```bash
+x402-cli pay \
+  'https://x402-gateway.bankofai.io/providers/defillama-tvl-tron/protocols' \
+  --dry-run \
+  --json
+```
+
+## 4. Start a Provider Gateway
+
+Create a local provider configuration:
+
+```bash
+x402-cli gateway scaffold acme-weather \
+  --output-dir providers/acme-weather \
+  --forward-url https://api.example.com \
+  --network tron:shasta
+```
+
+Validate and start it:
+
+```bash
+x402-cli gateway check providers/acme-weather/provider.yml
+x402-cli gateway start --providers-dir providers --host 0.0.0.0 --port 4020
+```
+
+`provider.yml` is private. Do not submit it to the public catalog repository.
+
+## 5. Export Public Catalog PR Files
+
+After the gateway is reachable:
+
+```bash
+x402-cli catalog export-gateway https://gateway.example.com \
+  --provider acme-weather \
+  --output-dir providers/acme-weather
+```
+
+This writes:
+
+```text
+providers/acme-weather/catalog.json
+providers/acme-weather/pay.md
+```
+
+Submit only these public files to `BofAI/x402-catelog`.
+
+## 6. Agent/Codex Usage
+
+Agents should use the catalog first, then call the selected endpoint:
+
+```bash
+x402-cli catalog search "defillama tvl" --json
+x402-cli catalog pay-json defillama
+x402-cli pay 'https://x402-gateway.bankofai.io/providers/defillama-tvl-tron/protocols' \
+  --method GET \
+  --network tron:mainnet \
+  --scheme exact_permit \
+  --token USDT \
+  --max-amount 0.001
+```
+
+The catalog response gives the provider FQN, endpoint URL, price range, chains,
+and human/agent-readable usage text.
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bankofai-x402-cli"
-version = "0.1.0"
+version = "0.6.1"
 description = "x402-cli — one-shot BankofAI x402 CLI: serve a 402 payment endpoint, or pay one as a client."
 readme = "README.md"
 license = { text = "MIT" }
@@ -23,8 +23,9 @@ dependencies = [
   # TokenRegistry → AssetRegistry rename on the SDK's dev/v2 branch).
   # web3 / tronpy are pulled in via the SDK's [evm,tron] extras so the SDK
   # owns those version ranges (cli code never imports them directly).
-  "bankofai-x402[evm,tron]>=0.5.9,<0.6",
+  "bankofai-x402[evm,tron]>=0.6.0,<0.7",
   "bankofai-agent-wallet>=2.4,<3",
+  "bankofai-x402-gateway>=0.6.1b0,<0.7",
   # CLI's own runtime stack — only libs that cli source directly imports.
   # Bound major version to defend against breaking bumps.
   "click>=8.1.0,<10",