httpcat-cli 0.3.1 → 0.3.3

package/README.md

@@ -1,3089 +1,281 @@
 # httpcat-cli
 
-> 🐱 Command-line interface for interacting with the httpcat agent - create, buy, and sell tokens with x402 payments
+![Banner](https://i.imgur.com/uTH4ly9.png)
 
-httpcat is a full-featured CLI tool that provides both interactive (with ASCII art cats!) and headless modes for token operations on the httpcat agent. It supports creating tokens, buying, selling, and managing your portfolio with seamless x402 payment integration.
+> **The CLI that enables agents to use x402 protocol. No middleware. No wallets. Just HTTP-native micropayments.**
 
-## Features
+**Give your agent claws.**
 
-- 🎨 **Interactive Shell** - Beautiful REPL with ASCII art cats and colored output
-- 🐱 **Headless Mode** - JSON output for scripting and LLM/agent integration
-- 🔌 **MCP Server** - Built-in Model Context Protocol server for AI assistant integration
-- 💳 **x402 Payments** - Automatic payment handling via x402 protocol
-- 🔐 **Secure Config** - Local configuration storage in `~/.config/httpcat`
-- 🌐 **Multi-Network** - Support for Base Sepolia (testnet) and Base (mainnet)
-- 📊 **Rich Output** - Tables, progress bars, and detailed token information
-- ⚡ **Fast & Simple** - Built with TypeScript and optimized for performance
+---
 
-## Installation
-
-### npm (recommended)
-
-```bash
-npm install -g httpcat-cli
-```
+## What is httpcat?
 
-Or use with npx without installing:
+httpcat is the command-line interface for [402.cat](https://402.cat) — the tool that lets agents interact with x402-protected endpoints and build economic capabilities.
 
-```bash
-npx httpcat-cli
-```
+**The foundation:** x402 protocol enables HTTP-native micropayments. Every API call can be a paid transaction. No API keys. No accounts. Just pay-per-call.
 
-### Homebrew (macOS/Linux)
+httpcat wraps this in a CLI that agents can use directly. It handles payment signatures automatically.
 
-```bash
-brew tap hathbanger/httpcat
-brew install httpcat
-```
+---
 
-### From Source
+## How It Works
 
-```bash
-cd httpcat-cli
-yarn install
-yarn build
-yarn link
-```
+### x402 Protocol Integration
 
-## Upgrading
+httpcat uses the x402 protocol to handle payments automatically:
 
-### npm (Global Install)
+1. **Request** → CLI makes HTTP request to x402 endpoint
+2. **402 Response** → Endpoint returns payment requirements
+3. **Payment** → CLI generates payment signature and retries
+4. **Response** → Endpoint processes and returns result
 
-If you installed httpcat globally via npm:
+All of this happens automatically. No middleware. No wallet management in your code. Just HTTP requests with payment headers.
 
-```bash
-npm update -g httpcat-cli
-```
+### Entrypoints
 
-### Yarn (Global Install)
+Entrypoints are services wrapped in x402 protocol. They're composable and automatically handle payments.
 
-If you installed httpcat globally via yarn:
+**Built-in entrypoints:**
 
-```bash
-yarn global upgrade httpcat-cli
-```
+- `swap` — DEX aggregator for token swaps
+- `launchpad` — Token creation and trading
+- `rpc` — JSON-RPC proxy for blockchain calls
 
-### Homebrew
+---
 
-If you installed via Homebrew:
+## Installation
 
 ```bash
-brew upgrade httpcat
+npm install -g httpcat-cli
 ```
 
-### npx (No Upgrade Needed)
-
-If you're using `npx httpcat-cli`, it automatically uses the latest version - no upgrade needed!
+Or use with npx:
 
 ```bash
-npx httpcat-cli@latest
+npx httpcat-cli
 ```
 
-### From Source (Development)
-
-If you're developing locally with `yarn link`:
+Homebrew:
 
 ```bash
-cd httpcat-cli
-git pull
-yarn install
-yarn build
+brew tap hathbanger/httpcat
+brew install httpcat
 ```
 
+---
+
 ## Quick Start
 
-### First-Time Setup
+### Setup
 
-Run `httpcat` to automatically create your wallet:
+Run `httpcat` to create your wallet:
 
 ```bash
 httpcat
 ```
 
-**Automatic Wallet Generation:**
-
-When you first run `httpcat`, a wallet is automatically created for you:
-
-1. **Seed Phrase Generated** - A 12-word seed phrase is generated locally on your computer
-2. **Address Displayed** - Your wallet address is prominently displayed so you can immediately send USDC or ETH
-3. **Security Information** - Comprehensive security messaging explains that:
-   - Your seed phrase was generated on THIS computer only
-   - It has NEVER been and will NEVER be transmitted to any server, third party, or external service
-   - All cryptographic operations happen entirely on your device
-   - Your seed phrase is stored locally at `~/.config/httpcat/config.json`
-4. **Password Protection (Optional)** - You can set a password to encrypt your wallet, or press Enter to skip (keys are still encrypted)
-5. **Backup Instructions** - You'll be shown your seed phrase with instructions to back it up securely
-
-**Import Mode (Optional):**
-
-If you want to import an existing seed phrase or private key instead of auto-generation, set the `HTTPCAT_IMPORT_MODE` environment variable:
-
-```bash
-HTTPCAT_IMPORT_MODE=true httpcat
-```
-
-This will show the traditional import options:
-
-- Generate new wallet (seed phrase)
-- Import existing seed phrase
-- Import existing private key
-
-**Configuration Options:**
-
-After wallet setup, you'll be prompted for:
-
-- **Network** - Network format: `eip155:84532` (Base Sepolia testnet) or `eip155:8453` (Base mainnet)
-- **Agent URL** - The httpcat agent endpoint (default: https://agent-test.402.cat)
-- **ASCII Art** - Enable or disable cat art
-
-**Network Format:** Uses CAIP-2 format (`eip155:<chainId>`):
-
-- Base Sepolia (testnet): `eip155:84532` (Chain ID: 84532)
-- Base (mainnet): `eip155:8453` (Chain ID: 8453)
-
-### Interactive Mode
-
-Once configured, running `httpcat` without arguments starts an interactive shell:
-
-```bash
-$ httpcat
-
-  /\_/\
- ( ^.^ ) Welcome to httpcat!
-  > ^ <  Your agent for token operations
-
-🔗 Connected to: eip155:84532 (Base Sepolia)
-🌐 Agent: https://agent-test.402.cat
-
-httpcat> help
-Available Commands:
-
-  create <name> <symbol>          Create a new token
-  buy <id|name|symbol> <amount>   Buy tokens ($0.05, $0.10, $0.20, or percentage like 50%)
-  sell <id|name|symbol> <amount|all>  Sell tokens
-  swap <tokenIn> <tokenOut> <amount>  Swap any token to any token (CLI only, $0.10)
-  info <id|name|symbol>           Get token information
-  list [--sort mcap|created]      List all tokens
-  positions [--active|--graduated] Get all your positions with comprehensive info
-  transactions [--user|--token|--type] Get transaction history
-  claim <id|name|symbol> [--execute] View/claim LP fees for graduated tokens
-  market search <query>            Search cryptocurrencies (CoinGecko, FREE)
-  market coin-data <coinId>        Get coin market data (CoinGecko, $0.001)
-  market chart <coinId> <days>     Get price chart (CoinGecko, $0.01)
-  cex markets                     Get CEX.IO markets (FREE)
-  cex ticker <symbol>              Get CEX.IO ticker (FREE)
-  cex balance                     Get CEX.IO balance ($0.001)
-  cex place-order <symbol> <type> <orderType> <amount>  Place order ($0.05, HIGH RISK)
-  chat [token]                    Start streaming chat (optional: token symbol/name/address)
-  balances                        Check wallet balances (ETH, USDC, and CAT)
-  account [list|switch|add]       Manage accounts
-  cat                             Start interactive AI assistant chat mode
-  agent setup                     Configure autonomous trading agent settings
-  health                          Check agent health
-  config [--show|--set|--reset]   Manage configuration
-  env [list|use|show|add|update]  Manage environments
-  help                            Show this help message
-  exit                            Exit the shell
-
-httpcat> create "Meow Token" "MEOW"
-
-  /\_/\  Creating your token...
- ( o.o )💭
-
-💳 Payment required: $0.01 USDC
-
-✅ Token created successfully!
-
-┌─────────────────────────────────────────┐
-│ 🎉 Meow Token (MEOW)                    │
-├─────────────────────────────────────────┤
-│ Address:   0x789abcd...                 │
-│ Supply:    1,000,000,000 MEOW           │
-│ Status:    Active                       │
-└─────────────────────────────────────────┘
-
-httpcat> buy 0x789abcd... 0.20
-
-💰 Tokens purchased successfully!
-
-┌─────────────────────────────────────────┐
-│ 💰 Purchase Summary                     │
-├─────────────────────────────────────────┤
-│ Tokens Received: 50,000                 │
-│ Amount Spent:    $5.00                  │
-│ Fee (1%):        $0.05                  │
-│ New Price:       $0.0002                │
-│ New Market Cap:  $200,000               │
-│ Graduation:      0.15%                  │
-└─────────────────────────────────────────┘
-
-[🐱==>                  ] 0.15% to moon!
-```
-
-## Global Options
-
-These options can be used with any command:
-
-- `-j, --json` - Output in JSON format for scripting and automation
-- `-q, --quiet` - Minimal output (exit codes only)
-- `-v, --verbose` - Show verbose error messages and debugging information
-- `--no-art` - Disable ASCII art cats
-- `-k, --private-key <key>` - Use specific private key (overrides config and env var)
-- `-a, --account <index>` - Use specific account index (overrides active account)
-
-**Examples:**
-
-```bash
-# Use account 2 for getting positions
-httpcat -a 2 positions
-
-# Use account 1 to buy tokens
-httpcat -a 1 buy MTK 0.10
-
-# JSON output for account 0
-httpcat --json -a 0 balances
-
-# Use specific private key
-httpcat -k 0x1234... create "Test" "TEST"
-
-# Quiet mode with exit code checking
-httpcat -q buy MTK 0.20 && echo "Success!" || echo "Failed"
-```
-
-**Note:** The `-a, --account` flag allows you to use different accounts without switching your active account in the config.
-
-## Commands
-
-> **Note on Command Organization:** httpcat v0.3.0 organizes commands into logical groups (e.g., `launchpad`, `portfolio`, `trade`). Many top-level commands are still available for backward compatibility but are considered deprecated. Use the grouped commands for new scripts. See [Command Groups](#command-groups) section for the full list of organized commands.
-
-### Create Token
+Your seed phrase is generated locally and never transmitted to any server.
 
-Create a new token on the bonding curve.
-
-**Interactive:**
+### Use Entrypoints
 
 ```bash
-httpcat> create "My Token" "MTK"
-httpcat> create "My Token" "MTK" --photo https://example.com/photo.png
-httpcat> create "My Token" "MTK" --photo ./logo.png
-```
+# Swap tokens via DEX aggregator
+httpcat swap USDC WETH 1.0
 
-**CLI:**
-
-```bash
+# Launchpad operations
+httpcat list
 httpcat create "My Token" "MTK"
-httpcat create "My Token" "MTK" --photo https://example.com/photo.png --website https://mytoken.io
-httpcat create "My Token" "MTK" --photo ./logo.png
-```
-
-**Options:**
-
-- `-p, --photo <url|path>` - Token photo URL or file path (supports http/https URLs, local file paths, or base64 data URLs)
-- `-w, --website <url>` - Website URL
-
-**Note:** If no photo is provided, a unique [Robohash](https://robohash.org/) avatar is automatically generated for your token based on the token address.
-
-**Cost:** $0.01 USDC
-
-### Buy Tokens
-
-Purchase tokens from the bonding curve.
-
-**Interactive:**
-
-```bash
-httpcat> buy 0x1234... 0.20
-httpcat> buy "My Token" 0.10
-httpcat> buy MTK 0.05
-```
-
-**CLI:**
-
-```bash
-httpcat buy 0x1234567890abcdef1234567890abcdef12345678 0.20
-httpcat buy "My Token" 0.10
-httpcat buy MTK 0.05
-```
-
-**Options:**
-
-- `-r, --repeat <count>` - Execute multiple buys in sequence (stops early if token graduates or insufficient funds)
-- `-d, --delay <ms>` - Delay in milliseconds between repeat operations (default: 0)
-
-**Examples with repeat:**
-
-```bash
-# Execute 10 buys back-to-back
-httpcat buy MTK 0.10 -r 10
-
-# Execute 10 buys with 500ms delay between each
-httpcat buy MTK 0.10 -r 10 -d 500
-```
-
-**Token Identifier:**
-
-- Token address: `0x1234...` (contract address)
-- Token name: `"My Token"` (use quotes if it contains spaces)
-- Token symbol: `MTK` (case-insensitive)
-
-**Amounts:**
-
-- Test mode (Base Sepolia / eip155:84532): `0.05`, `0.10`, or `0.20` USDC
-- Production (base): `50`, `100`, or `200` USDC
-- Percentage: `10%`, `50%`, `100%` (percentage of your USDC balance)
-  - Example: `httpcat buy MTK 50%` - Buy with 50% of your USDC balance
-  - Works with any percentage from 0.01% to 100%
-
-**Cost:** Amount + 1% fee (e.g., $5.05 for $5 purchase)
-
-**Repeat Mode Behavior:**
-
-When using `-r, --repeat`, the command will:
-
-- Execute the specified number of buys sequentially
-- Wait for transaction confirmation between each buy
-- Automatically retry failed transactions (up to 10 attempts with exponential backoff)
-- Stop early if the token graduates (reaches 100% graduation progress)
-- Stop early if you run out of funds (HTTP 402 error)
-- Display a compact summary for each buy
-- Show a final summary with total buys completed, total spent, and final status
-
-### Sell Tokens
-
-Sell tokens back to the bonding curve.
-
-**Interactive:**
-
-```bash
-httpcat> sell 0x1234... 1000        # Sell 1000 tokens
-httpcat> sell "My Token" 50%         # Sell 50% of holdings
-httpcat> sell MTK all                # Sell all tokens
-```
-
-**CLI:**
-
-```bash
-httpcat sell 0x1234567890abcdef1234567890abcdef12345678 1000
-httpcat sell "My Token" 50%
-httpcat sell MTK all
-```
-
-**Token Identifier:**
-
-- Address, name, or symbol (same as buy command)
-
-**Cost:** Dynamic based on amount (1% fee deducted from proceeds)
-
-### Swap Tokens
-
-Swap any ERC20 token to any other ERC20 token using pro DEX aggregation with optimal routing.
-
-**Note:** This is a CLI-only feature, not available in the interactive shell.
-
-**CLI:**
-
-```bash
-httpcat swap <tokenIn> <tokenOut> <amount>
-httpcat swap <tokenIn> <tokenOut> <amount> --slippage <bps>
-```
-
-**Parameters:**
-
-- `tokenIn` - Token to sell (contract address)
-- `tokenOut` - Token to buy (contract address)
-- `amount` - Amount to sell in smallest unit (e.g., 1000000 = 1 USDC with 6 decimals)
-
-**Options:**
-
-- `-s, --slippage <bps>` - Slippage tolerance in basis points (default: 50 = 0.5%)
-
-**Examples:**
-
-```bash
-# Swap 1 USDC for WETH with default 0.5% slippage
-httpcat swap 0x036cbd53842c5426634e7929541ec2318f3dcf7e 0x4200000000000000000000000000000000000006 1000000
-
-# Swap with 1% slippage tolerance
-httpcat swap 0x036c... 0x4200... 1000000 --slippage 100
-```
-
-**Options:**
-
-- `--shielded` - Use MEV-protected swap via UniswapX Dutch auction ($1.00)
-
-**Examples:**
-
-```bash
-# MEV-protected swap
-httpcat swap USDC WETH 1.0 --shielded
-```
-
-**Cost:** $0.10 USDC (standard) or $1.00 USDC (shielded)
-
-### Gasless Swap
-
-Submit gasless swap trades that don't require gas fees.
-
-**CLI:**
-
-```bash
-# Submit signed 0x gasless swap
-httpcat gasless-submit --trade '{"order": {...}}'
-
-# Submit via our executor
-httpcat gasless-submit-our \
-  --token-in 0x... \
-  --token-out 0x... \
-  --total-amount 1000000 \
-  --fee-amount 10000 \
-  --taker 0x... \
-  --permit2-signature 0x... \
-  --permit-nonce 0 \
-  --permit-deadline 1234567890
-```
-
-**Cost:** $0.01 USDC
-
-### Perps (Perpetual Futures)
-
-Trade perpetual futures across multiple venues.
-
-**CLI:**
-
-```bash
-# List available markets
-httpcat perps markets
-
-# Onboard wallet to venues (one-time setup)
-httpcat perps onboard
-
-# Deposit USDC to venues
-httpcat perps deposit 1000
-
-# Open a position
-httpcat perps trade ETH-USD long 100 10
-
-# View open positions
-httpcat perps positions
-```
-
-**Subcommands:**
-
-- `markets` - Get available markets ($0.01)
-- `onboard` - One-time wallet setup (FREE)
-- `deposit <amount>` - Deposit USDC (FREE)
-- `trade <market> <side> <sizeUsd> <leverage>` - Open/close positions ($0.05)
-- `positions` - View open positions ($0.01)
-
-**Options:**
-
-- `--venue <name>` - Filter by venue
-- `--wallet <address>` - Wallet address (defaults to configured wallet)
-- `--aster-api-key <key>` - Aster API key (for positions)
-- `--aster-api-secret <secret>` - Aster API secret (for positions)
-
-### Predictions
-
-Interact with prediction markets on Polymarket and Azuro.
-
-**CLI:**
-
-```bash
-# Browse markets
-httpcat predictions markets
-
-# Get market details
-httpcat predictions market <marketId>
-
-# Search markets
-httpcat predictions search "bitcoin"
-
-# Place a bet
-httpcat predictions bet <marketId> <outcomeId> <amountUsd>
-
-# Detect arbitrage opportunities
-httpcat predictions detect-arbs
-
-# Detect sophisticated traders
-httpcat predictions detect-insiders
-```
-
-**Subcommands:**
-
-- `markets` - Browse markets ($0.01)
-- `market <marketId>` - Get market details ($0.01)
-- `search <query>` - Search markets ($0.01)
-- `bet <marketId> <outcomeId> <amountUsd>` - Place bet ($0.05)
-- `detect-arbs` - Find arbitrage opportunities (FREE)
-- `calculate-hedge` - Calculate optimal hedge (FREE)
-- `execute-arb` - Execute arbitrage trade ($0.20)
-- `detect-insiders` - Detect sophisticated traders ($5.00)
-
-**Options:**
-
-- `--venue <name>` - Filter by venue
-- `--category <category>` - Filter by category
-- `--limit <number>` - Limit results
-- `--wallet <address>` - Wallet address (defaults to configured wallet)
-- `--polymarket-api-key <key>` - Polymarket API key
-- `--polymarket-api-secret <secret>` - Polymarket API secret
-
-### Market Intelligence (CoinGecko)
-
-Research cryptocurrencies using CoinGecko market data.
-
-**CLI:**
-
-```bash
-# Search for cryptocurrencies
-httpcat market search bitcoin
-httpcat market search "eth" --limit 10
-
-# Get comprehensive coin data
-httpcat market coin-data bitcoin
-httpcat market coin-data ethereum --currency eur --sparkline
-
-# Get historical price charts
-httpcat market chart bitcoin 7
-httpcat market chart ethereum 30 --currency eur
-httpcat market chart bitcoin max --json
-```
-
-**Subcommands:**
-
-- `search <query>` - Search cryptocurrencies by name or symbol (FREE)
-- `coin-data <coinId>` - Get comprehensive market data ($0.001)
-- `chart <coinId> <days>` - Get historical price chart ($0.01)
-
-**Options:**
-
-- `--limit <number>` - Maximum search results (default: 20, max: 100)
-- `--currency <currency>` - Currency: usd, eur, btc (default: usd)
-- `--sparkline` - Include 7-day sparkline chart
-- `--interval <interval>` - Chart interval: daily or hourly (auto-selected)
-
-**Examples:**
-
-```bash
-# Search for Bitcoin
-httpcat market search bitcoin
-
-# Get Bitcoin market data with sparkline
-httpcat market coin-data bitcoin --sparkline
-
-# Get 7-day hourly chart
-httpcat market chart bitcoin 7
-
-# Get max historical data (JSON for charting)
-httpcat market chart bitcoin max --json
-```
-
-**Note:** Use `search` to find CoinGecko coin IDs (e.g., 'bitcoin', 'ethereum') for use with `coin-data` and `chart` commands.
-
-### CEX.IO Trading
-
-Trade on CEX.IO exchange via CLI. Monitor positions, place orders, and view market data.
-
-**CLI:**
-
-```bash
-# Get all available markets
-httpcat cex markets
-httpcat cex markets --base BTC
-
-# Get ticker for a trading pair
-httpcat cex ticker BTC/USD
-
-# Check account balance
-httpcat cex balance
-httpcat cex balance --currency BTC
-
-# View order book
-httpcat cex orderbook BTC/USD --depth 20
-
-# List open orders
-httpcat cex orders
-httpcat cex orders --symbol BTC/USD
-
-# View order history
-httpcat cex order-history --status completed
-httpcat cex order-history --symbol BTC/USD --since 2024-01-01T00:00:00Z
-
-# View trade history
-httpcat cex trade-history --symbol BTC/USD
-
-# Place an order (requires confirmation)
-httpcat cex place-order BTC/USD buy limit 0.1 --price 50000
-
-# Cancel an order
-httpcat cex cancel-order 12345
-```
-
-**Subcommands:**
-
-- `markets` - Get all trading pairs (FREE)
-- `ticker <symbol>` - Get ticker information (FREE)
-- `balance` - Get account balances ($0.001)
-- `orderbook <symbol>` - Get order book ($0.001)
-- `orders` - Get open orders ($0.001)
-- `order-history` - Get order history ($0.01)
-- `trade-history` - Get trade history ($0.01)
-- `place-order` - Place buy/sell order ($0.05) **HIGH RISK**
-- `cancel-order <orderId>` - Cancel order ($0.01)
-
-**Options:**
-
-- `--base <currency>` - Filter by base currency (markets)
-- `--quote <currency>` - Filter by quote currency (markets)
-- `--currency <currency>` - Filter by currency (balance)
-- `--depth <depth>` - Order book depth (default: 20, max: 100)
-- `--symbol <symbol>` - Filter by trading pair
-- `--status <status>` - Filter by status: completed, canceled, failed, all
-- `--limit <limit>` - Maximum results
-- `--since <timestamp>` - ISO timestamp filter
-- `--until <timestamp>` - ISO timestamp filter (trade-history)
-- `--price <price>` - Order price (required for limit/stop-limit)
-- `--stop-price <price>` - Stop price (for stop-limit orders)
-- `--confirm` - Skip confirmation prompt (use with caution)
-
-**Security Notes:**
-
-- `place-order` executes real trades - always requires confirmation unless `--confirm` flag is used
-- Symbol formats supported: `BTC/USD`, `BTC-USD`, or `BTCUSD`
-- Market orders execute immediately; limit orders wait for price
-- Backend must have CEX.IO API credentials configured
-
-**Examples:**
-
-```bash
-# View all BTC markets
-httpcat cex markets --base BTC
-
-# Get BTC/USD ticker
-httpcat cex ticker BTC/USD
-
-# Check your balance
-httpcat cex balance
-
-# View order book
-httpcat cex orderbook BTC/USD
-
-# Place a limit buy order (will prompt for confirmation)
-httpcat cex place-order BTC/USD buy limit 0.1 --price 50000
-
-# Place a market sell order
-httpcat cex place-order ETH/USD sell market 2.0
+httpcat buy MTK 0.10
+httpcat positions
 ```
 
-### Token Info
+### MCP Integration
 
-Get detailed information about a token.
-
-**Interactive:**
+Give your agent claws:
 
 ```bash
-httpcat> info 0x1234...
-httpcat> info "My Token"
-httpcat> info MTK
+httpcat mcp install
 ```
 
-**CLI:**
-
-```bash
-httpcat info 0x1234567890abcdef1234567890abcdef12345678
-httpcat info "My Token"
-httpcat info MTK
-```
+Your agent can now use all CLI commands as MCP tools. One integration, access to everything.
 
-**Token Identifier:**
+---
 
-- Address, name, or symbol (same as buy command)
+## Commands
 
-**Output:**
+### Launchpad
+
+- `launchpad list` — List all launchpad tokens (FREE)
+- `launchpad info <identifier>` — Get launchpad token information (FREE)
+- `launchpad buy <identifier> <amount>` — Buy tokens from bonding curve (amount + 1% fee)
+- `launchpad sell <identifier> <amount>` — Sell tokens to bonding curve ($0.01)
+- `launchpad positions` — Get launchpad token positions (FREE)
+- `create <name> <symbol>` — Create a new token on the 402.cat launchpad ($0.01)
+
+**Shortcuts:** `list`, `info`, `buy`, `sell`, `positions`, `create`
+
+### Entrypoints
+
+- `swap <tokenIn> <tokenOut> <amount>` — Execute swaps via 402.cat DEX aggregator ($0.10)
+
+### Tools
+
+EVM development & interaction tools for building and working with blockchain transactions:
+
+- `tools address` — Address utilities
+  - `tools address validate <address>` — Validate Ethereum address format ($0.001)
+  - `tools address checksum <address>` — Convert address to EIP-55 checksum format ($0.001)
+  - `tools address derive <privateKey>` — Derive address from private key ($0.001)
+  - `tools address balance <address>` — Get address balance (ETH + tokens) ($0.001)
+- `tools abi` — ABI encoding/decoding utilities
+  - `tools abi encode` — Encode function call from ABI and arguments ($0.001)
+  - `tools abi decode` — Decode function result or event log ($0.001)
+  - `tools abi parse` — Parse ABI JSON and return structured format ($0.001)
+- `tools tx` — Transaction utilities
+  - `tools tx build` — Build complete transaction with auto-filled fields ($0.001)
+  - `tools tx encode` — Encode transaction to RLP format ($0.001)
+  - `tools tx decode` — Decode RLP transaction ($0.001)
+  - `tools tx simulate` — Enhanced transaction simulation with state analysis ($0.001)
+  - `tools tx estimate-gas` — Estimate gas for transaction ($0.001)
+  - `tools tx prepare` — Prepare transaction for signing ($0.001)
+- `tools signature` — Signature utilities
+  - `tools signature eip191` — Prepare EIP-191 personal sign message ($0.001)
+  - `tools signature eip712` — Prepare EIP-712 structured data signature ($0.001)
+  - `tools signature permit2` — Prepare Permit2 signature message ($0.001)
+- `tools multicall` — Multicall operations
+  - `tools multicall encode` — Encode multicall operation ($0.001)
+  - `tools multicall decode` — Decode multicall results ($0.001)
+- `tools nonce` — Nonce management
+  - `tools nonce get <address>` — Get current nonce for address ($0.001)
+  - `tools nonce predict <address>` — Predict next nonce accounting for pending transactions ($0.001)
+- `tools gas` — Gas utilities
+  - `tools gas price` — Get current gas price ($0.001)
+  - `tools gas estimate` — Estimate gas for operation ($0.001)
+  - `tools gas optimize` — Optimize gas settings for transaction ($0.001)
+- `tools key` — Key utilities
+  - `tools key derive <privateKey>` — Derive address from private key ($0.001)
+  - `tools key validate <privateKey>` — Validate private key format ($0.001)
+- `tools rpc` — RPC utilities
+  - `tools rpc proxy` — Enhanced JSON-RPC proxy ($0.001)
+  - `tools rpc batch` — Batch multiple RPC calls ($0.001)
+  - `tools rpc health` — Check RPC endpoint health ($0.001)
+- `tools call <url>` — Call an arbitrary x402-protected HTTP endpoint with automatic payment handling (varies by endpoint)
+- `rpc` — JSON-RPC proxy for blockchain calls ($0.05)
+
+### MCP
+
+- `mcp install [llm-name]` — Install or update httpcat MCP server for AI assistants
+- `mcp start` — Start MCP (Model Context Protocol) server
 
-- Token name, symbol, address
-- Current price and market cap
-- Graduation progress
-- Your position (if you hold any)
-- P&L calculation
+### Configuration
 
-**Cost:** $0.0001 USDC
+- `config` — Configure httpcat (settings, environment, accounts)
+  - `config setup` — Run interactive setup wizard
+  - `config reset` — Reset configuration (clears all settings)
+  - `config completion [shell]` — Generate shell completion script
+  - `config update` — Update httpcat CLI to the latest version
+- `use <value>` — Switch account or environment
 
-### List Tokens
+### Infrastructure
 
-List all tokens with pagination and sorting.
+- `accounts` — List all configured accounts
 
-**Interactive:**
+**Additional Shortcuts:** `transactions` (→ portfolio transactions), `health` (→ system health), `balances` (→ portfolio balances)
 
-```bash
-httpcat> list
-httpcat> list --sort mcap --limit 10
-httpcat> list --page 2
-```
+---
 
-**CLI:**
+## x402 Protocol
 
-```bash
-httpcat list
-httpcat list --sort created --limit 50
-httpcat list --page 3 --sort name
-```
+httpcat is built on the [x402 protocol](https://x402.org) — HTTP-native micropayments that work without middleware or wallets.
 
-**Options:**
+**How it works:**
 
-- `-s, --sort <field>` - Sort by `mcap`, `created`, or `name` (default: `mcap`)
-- `-l, --limit <n>` - Items per page (default: 20, max: 100)
-- `-p, --page <n>` - Page number (default: 1)
+1. Make HTTP request to x402 endpoint
+2. Receive `402 Payment Required` response
+3. Generate payment signature using your private key
+4. Retry request with `PAYMENT-SIGNATURE` header
+5. Endpoint verifies payment and processes request
 
-**Cost:** $0.0001 USDC
+**No middleware required.** The protocol is built into HTTP. No wallet management. No complex setup. Just HTTP requests with payment headers.
 
-### Positions
+httpcat handles all of this automatically. You just make requests.
 
-Get all your positions with comprehensive information including current value, profit/loss, ROI, transaction history, and portfolio summary.
+**Protocol Versions:** httpcat supports both x402 v1 (payment requirements in response body) and v2 (payment requirements in `PAYMENT-REQUIRED` header). The client automatically detects and handles both formats.
 
-**Interactive:**
+---
 
-```bash
-httpcat> positions
-```
+## MCP Server
 
-**CLI:**
+The MCP server exposes all CLI commands as tools for AI assistants:
 
 ```bash
-httpcat positions
-httpcat positions --active           # Only active positions
-httpcat positions --graduated        # Only graduated positions
-httpcat -j positions
-httpcat -k 0x... positions
+httpcat mcp install
 ```
 
-**Options:**
-
-- `-a, --active` - Show only active (non-graduated) positions
-- `-g, --graduated` - Show only graduated positions (historical)
-
-**Output:**
-
-For each position:
-
-- Token information (name, symbol, address, status, price, market cap, graduation progress)
-- Position details (tokens owned, USDC invested, current value, average cost per token)
-- Performance metrics (profit/loss in USDC and percentage ROI)
-- Position age (days, hours, minutes, seconds since first purchase)
-- Transaction history (total transaction count, last transaction date)
-- Timestamps (position created and updated dates)
-
-Portfolio summary:
-
-- Total positions count
-- Total portfolio value
-- Total amount invested
-- Total profit/loss and overall ROI percentage
-
-**Cost:** $0.01 USDC
-
-### Claim LP Fees
-
-View and claim accumulated liquidity provider fees for graduated tokens.
-
-**Interactive:**
+Or start manually:
 
 ```bash
-httpcat> claim "My Token"           # View accumulated fees
-httpcat> claim MTK                  # View by symbol
-httpcat> claim MTK --execute        # Claim fees
+httpcat mcp start
 ```
 
-**CLI:**
+**Configuration:**
 
-```bash
-httpcat claim "My Token"
-httpcat claim MTK
-httpcat claim MTK --execute
-httpcat claim 0x1234... --execute
-httpcat --json claim "My Token"
+```json
+{
+  "mcpServers": {
+    "httpcat": {
+      "command": "npx",
+      "args": ["-y", "httpcat-cli", "mcp", "start"]
+    }
+  }
+}
 ```
 
-**Options:**
-
-- `-e, --execute` - Execute the claim transaction (default is view-only)
-- `-A, --address <address>` - Caller address (defaults to wallet address)
+**Note:** Private key is NOT included in MCP config — the server reads from `~/.config/httpcat/config.json` automatically.
 
-**Token Identifier:**
+Your agent can now:
 
-- Address, name, or symbol (same as buy/sell commands)
+- Use entrypoints (swap, launchpad, rpc)
+- Use launchpad commands (create, buy, sell, list, info, positions)
+- Discover and compose services
+- Build capabilities
 
-**Output:**
+---
 
-When viewing (without `--execute`):
-
-- Total accumulated fees (tokens and USDC)
-- Creator share (80%)
-- Platform share (20%)
-- LP lock status and details
-- V4 position details (if applicable)
+## Global Options
 
-When claiming (with `--execute`):
+- `-j, --json` — JSON output for scripting
+- `-q, --quiet` — Minimal output
+- `-v, --verbose` — Verbose errors
+- `--no-art` — Disable ASCII art
+- `-k, --private-key <key>` — Override private key
+- `-a, --account <index>` — Use specific account
 
-- Transaction hash
-- Fees claimed (tokens and USDC)
-- Creator and platform shares distribution
+---
 
-**Cost:** Free to view, gas fees apply for claiming
+## Documentation
 
-### Transactions
+For detailed documentation, entrypoint reference, and deployment guides:
 
-Get paginated transaction history with filtering options.
+**📖 [docs.402.cat](https://www.402.cat/docs)**
 
-**Interactive:**
+---
 
-```bash
-httpcat> transactions
-httpcat> transactions --type buy
-httpcat> transactions --token abc123-...
-```
+## The Foundation
 
-**CLI:**
+httpcat is built on three primitives:
 
-```bash
-httpcat transactions
-httpcat transactions --user 0x1234...
-httpcat transactions --token abc123-... --type buy
-httpcat transactions --type sell --limit 20
-httpcat --json transactions --offset 50
-```
+1. **x402 Protocol** — HTTP-native micropayments, no middleware
+2. **Entrypoint Registry** — Discoverable, composable services
+3. **Automatic Payments** — Payment signatures handled automatically
 
-**Options:**
+This is the infrastructure that lets agents transact without wallets, discover services without APIs, and build capabilities by composing entrypoints.
 
-- `-u, --user <address>` - Filter by user address (defaults to active account)
-- `-t, --token <tokenId>` - Filter by token ID
-- `-T, --type <type>` - Filter by type: `buy`, `sell`, or `airdrop`
-- `-l, --limit <number>` - Number of results (default: 50, max: 100)
-- `-o, --offset <number>` - Pagination offset (default: 0)
+**Money is the alignment mechanism.** An agent with a budget has to prioritize. Every action costs something. Run out of funds, you stop. Make bad decisions, you go broke.
 
-**Output:**
+The constraint is what makes it work.
 
-For each transaction:
-
-- Transaction type (buy, sell, or airdrop)
-- Status (pending, success, or failed)
-- Token information (name, symbol, ID)
-- User address
-- Amount and fee
-- Transaction hash
-- Date/time
-
-**Cost:** Varies based on API call
-
-**Note:** Defaults to showing transactions for your active account. Use `--user` to view transactions for a different address.
-
-### Check Balances
-
-Check your wallet's ETH and USDC balances.
-
-**Interactive:**
-
-```bash
-httpcat> balances
-```
-
-**CLI:**
-
-```bash
-httpcat balances
-httpcat balances -k 0x...
-```
-
-**Output:**
-
-- Wallet address
-- ETH balance (for gas fees)
-- USDC balance (for trading)
-- CAT balance (402CAT token)
-- Low balance warnings if applicable
-
-**Cost:** Free (no payment required)
-
-**Note:** If no private key is configured, you'll be prompted to enter it interactively (same as other commands).
-
-### Account Management
-
-Manage multiple accounts, view account information, and switch between accounts.
-
-**Interactive:**
-
-```bash
-httpcat> account                    # Show active account info
-httpcat> account list               # List all accounts
-httpcat> account switch 1           # Switch to account 1
-httpcat> account add                # Add new account
-```
-
-**CLI:**
-
-```bash
-httpcat account                     # Show active account
-httpcat account list                # List all accounts
-httpcat account switch 1            # Switch to account 1
-httpcat account add                 # Add new account
-httpcat --account 2 positions       # Use account 2 for positions
-httpcat -a 1 buy MTK 0.10           # Use account 1 for buy
-httpcat --json account
-```
-
-**Subcommands:**
-
-- `account` (no args) - Display active account information (address, balances, positions)
-- `account list` - List all configured accounts with their details
-- `account switch <index>` - Switch to a different account by index
-- `account add` - Add a new seed-derived account (HD wallet)
-
-**Account Types:**
-
-1. **Seed-Derived** (Account 1+) - Accounts generated from your seed phrase using BIP-32/BIP-39
-2. **Custom** (Account 0) - Account added via private key import
-
-**Output:**
-
-Account information includes:
-
-- Account index and type (Seed-Derived or Custom)
-- Wallet address (checksummed)
-- ETH balance (for gas fees)
-- USDC balance (for trading)
-- CAT balance (402CAT token)
-- All positions (if any) with P&L
-
-**Cost:** $0.01 USDC (for positions data; balances are free)
-
-**Security Note:** All accounts share the same password protection when password is enabled. Switch accounts anytime using the `--account` flag or `account switch` command.
-
-### Health Check
-
-Check if the agent is running.
-
-**Interactive:**
-
-```bash
-httpcat> health
-```
-
-**CLI:**
-
-```bash
-httpcat health
-```
-
-**Cost:** $0.0001 USDC (or 402 response)
-
-### Call x402 Endpoint
-
-Call an arbitrary x402-protected HTTP endpoint with automatic payment handling. This allows you to interact with any x402-enabled API, not just the httpcat agent.
-
-**CLI:**
-
-```bash
-# POST request with JSON body
-httpcat call https://example.com/api/endpoint --method POST --body '{"key": "value"}'
-
-# GET request
-httpcat call https://example.com/api/endpoint --method GET
-
-# POST with body from stdin
-echo '{"data": "test"}' | httpcat call https://example.com/api/endpoint --body -
-
-# With custom headers
-httpcat call https://example.com/api/endpoint \
-  --header "X-Custom-Header: value" \
-  --header "Authorization: Bearer token"
-```
-
-**Options:**
-
-- `<url>` (required) - The full URL of the x402 endpoint
-- `-m, --method <method>` - HTTP method: GET, POST, PUT, DELETE, or PATCH (default: POST)
-- `-b, --body <body>` - Request body as JSON string, or `-` to read from stdin
-- `-H, --header <header>` - Additional HTTP headers (format: "Key: Value"), can be specified multiple times
-- `-k, --private-key <key>` - Override private key (optional)
-
-**Response:**
-
-The command returns:
-
-- HTTP status code and status text
-- Response headers
-- Response body (parsed as JSON if possible, otherwise raw text)
-
-**Payment:**
-
-The command automatically handles x402 payment flows. If the endpoint requires payment, the command will:
-
-1. Receive a 402 Payment Required response
-2. Generate a payment signature
-3. Retry the request with the payment header
-4. Return the final response
-
-**Cost:** Varies by endpoint (determined by the x402 endpoint you're calling)
-
-**Examples:**
-
-```bash
-# Call a paid API endpoint
-httpcat call https://api.example.com/compute --method POST --body '{"input": "data"}'
-
-# Make a GET request
-httpcat call https://api.example.com/status --method GET
-
-# Pipe JSON from file
-cat request.json | httpcat call https://api.example.com/process --body -
-
-# With authentication header
-httpcat call https://api.example.com/protected \
-  --header "Authorization: Bearer your-token" \
-  --method GET
-```
-
-### Chat
-
-Start streaming chat with the httpcat community. Join general chat or token-specific discussions.
-
-**Interactive:**
-
-```bash
-httpcat> chat                    # Join general chat
-httpcat> chat MTK                # Join chat for token with symbol "MTK"
-httpcat> chat "My Token"         # Join chat for token with name "My Token"
-httpcat> chat 0x1234...          # Join chat for token at address
-```
-
-**CLI:**
-
-```bash
-httpcat chat
-httpcat chat MTK
-httpcat chat "My Token"
-httpcat chat 0x1234...
-httpcat -j chat MTK
-httpcat -j -f stream-json chat MTK  # Structured JSON input
-```
-
-**Token Identifier:**
-
-- Token symbol: `MTK` (case-insensitive)
-- Token name: `"My Token"` (use quotes if it contains spaces)
-- Token address: `0x1234...`
-
-**In-Chat Commands:**
-
-While in a chat session, you can use these commands:
-
-- `/exit` or `/quit` - Exit the chat
-- `/renew` - Renew your 10-minute lease
-- `/buy <amount>` - Buy tokens (token-specific chats only)
-- `/sell <amount>` - Sell tokens (token-specific chats only)
-- `/help` - Show available commands
-
-**Examples:**
-
-```
-/renew
-/buy 0.10
-/sell 50%
-/sell all
-```
-
-**Note:** The `/buy` and `/sell` commands are only available in token-specific chats, not in general chat.
-
-**Options:**
-
-- `-f, --input-format <format>` - Input format (only works with `--json`): `"text"` (default) or `"stream-json"` (realtime streaming input)
-  - `"text"`: Line-delimited text input (default)
-  - `"stream-json"`: Newline-delimited JSON (NDJSON) objects. Each line is a JSON object: `{"message": "text"}` or `{"command": "/renew"}`
-
-**Cost:** $0.01 USDC to join, $0.0001 USDC per message, 10 minute lease
-
-**Note:** For AI agents, consider using MCP tools (`chat_join`, `chat_send_message`, etc.) instead of CLI streaming for better integration. See [MCP Chat Tools](#chat-tools-usage-example) section.
-
-### Cat (Interactive AI Assistant)
-
-Interact with an AI-powered assistant that can help you with token operations, portfolio management, and more using natural language.
-
-**Interactive:**
-
-```bash
-httpcat> cat
-# Starts interactive AI chat session
-# Type /exit to quit
-```
-
-**Usage:**
-
-The `cat` command starts an interactive AI assistant session where you can ask questions and give trading commands in natural language. The assistant will execute operations on your behalf.
-
-**First-Time Setup:**
-
-Before using the cat command, you'll need to configure your AI provider:
-
-```bash
-httpcat config
-```
-
-During setup, you'll be prompted to:
-
-- Choose an AI provider (OpenAI or Anthropic)
-- Enter your API key
-- Select a model (defaults provided)
-
-**How It Works:**
-
-The cat assistant uses AI (powered by OpenAI GPT-4 or Anthropic Claude) to understand natural language requests and execute token operations on your behalf. It can:
-
-- Buy and sell tokens
-- Check balances and positions
-- List tokens
-- Get token information
-- Answer questions about your portfolio
-- And more!
-
-**Note:** The cat requires an API key from either OpenAI or Anthropic. Your API key is stored locally and encrypted, and is only sent to the LLM provider - never to any other server.
-
-### Agent (Autonomous Trading)
-
-Configure and run an autonomous trading agent that monitors token events and makes trading decisions based on your risk parameters.
-
-**Interactive:**
-
-```bash
-httpcat> agent setup     # Configure autonomous trading settings
-```
-
-**CLI:**
-
-```bash
-httpcat agent setup
-```
-
-**Configuration Options:**
-
-When setting up the autonomous agent, you can configure:
-
-- **Max Trade Amount** - Maximum USDC per trade
-- **Risk Tolerance** - Conservative, moderate, or aggressive
-- **Token Filters** - Minimum holders, max whale percentage, min liquidity
-- **Trading Thresholds** - Stop loss and take profit percentages
-- **Auto-Execute** - Enable automatic trade execution or recommendation-only mode
-
-**How It Works:**
-
-The autonomous agent:
-
-1. Monitors real-time token events via event stream
-2. Analyzes tokens based on your configured filters and risk parameters
-3. Makes trading decisions using AI reasoning
-4. Either executes trades automatically or provides recommendations (based on your settings)
-5. Tracks positions and maintains a decision history database
-
-**Note:** The autonomous agent requires AI provider configuration (same as the `cat` command). Always start with recommendation-only mode before enabling auto-execution.
-
-### Help
-
-Display help information for httpcat.
-
-**CLI:**
-
-```bash
-httpcat help
-httpcat --help
-httpcat -h
-```
-
-All three commands show the same help output with available commands and options.
-
-### Configuration
-
-Manage your httpcat configuration.
-
-**Interactive:**
-
-```bash
-httpcat> config -s              # Show current config
-httpcat> config -S network=base  # Update a setting
-httpcat> config -r             # Re-run setup wizard
-```
-
-**CLI:**
-
-```bash
-httpcat config                    # Run setup wizard
-httpcat config -s             # Show current config (JSON)
-httpcat config -S network=base # Update a setting
-```
-
-### Sign
-
-Cryptographic signing operations for messages, files, transactions, and structured data.
-
-**Interactive:**
-
-```bash
-httpcat> sign                    # Enter interactive signing mode
-```
-
-**CLI:**
-
-```bash
-# Sign a message (EIP-191)
-httpcat sign message "Hello, world!"
-httpcat sign message --file message.txt
-echo "Hello" | httpcat sign message --stdin
-
-# Sign a file
-httpcat sign file document.pdf
-httpcat sign file document.pdf --hash-algorithm keccak256
-
-# Sign a transaction
-httpcat sign transaction '{"to":"0x...","value":"1000000000000000000"}'
-
-# Sign EIP-712 structured data
-httpcat sign eip712 --domain '{"name":"MyApp"}' --types '{}' --message '{}'
-
-# Sign Permit2 authorization
-httpcat sign permit2 --token 0x... --amount 1000000 --spender 0x...
-
-# Batch sign multiple items
-httpcat sign batch '{"messages":["Hello","World"],"files":["doc1.pdf","doc2.pdf"]}'
-
-# Verify a signature
-httpcat sign verify --signature 0x... --message "Hello, world!"
-```
-
-**Subcommands:**
-
-- `sign message [message]` - Sign a message using EIP-191 personal sign
-- `sign file <path>` - Sign a file (hash + EIP-191 signature)
-- `sign transaction <tx-json>` - Sign a transaction (EIP-155)
-- `sign eip712` - Sign EIP-712 structured data
-- `sign permit2` - Sign Permit2 token authorization
-- `sign batch <batch-json>` - Batch sign multiple messages/files
-- `sign verify` - Verify a signature
-
-**Options:**
-
-- `--file <path>` - Read message from file (message subcommand)
-- `--stdin` - Read message from stdin (message subcommand)
-- `--output <file>` - Save signature to file
-- `--format <hex|rsv|compact>` - Signature format (default: hex)
-- `--hash-algorithm <sha256|keccak256>` - Hash algorithm for files (default: sha256)
-- `--verify` - Verify signature after signing
-- `--nonce <nonce>` - Nonce for Permit2 (auto-generated if not provided)
-- `--deadline <timestamp>` - Deadline for Permit2 (auto-generated if not provided)
-
-**Examples:**
-
-```bash
-# Sign a message and verify
-httpcat sign message "Hello, world!" --verify
-
-# Sign a file and save to output file
-httpcat sign file document.pdf --output signature.json
-
-# Sign with different format
-httpcat sign message "Test" --format rsv
-
-# Sign Permit2 with auto-generated nonce and deadline
-httpcat sign permit2 --token 0x... --amount 1000000 --spender 0x...
-
-# Verify an EIP-712 signature
-httpcat sign verify --signature 0x... --message '{}' --type eip712 \
-  --domain '{"name":"MyApp"}' --types '{}' --primary-type Message
-```
-
-**Cost:** $0.001 USDC per signature preparation (signing is done locally)
-
-**Note:** Signatures are created locally using your private key. The backend only prepares the signature data; actual signing happens client-side for security.
-
-## Command Groups
-
-httpcat organizes commands into logical groups for better discoverability. Many commands are available both as top-level commands (for backward compatibility) and as grouped commands.
-
-### Launchpad (`launchpad` or `lp`)
-
-Token creation and trading on the bonding curve.
-
-**Subcommands:**
-
-- `launchpad create <name> <symbol>` - Create a new token ($0.01)
-- `launchpad buy <identifier> <amount>` - Buy tokens (amount + 1% fee)
-- `launchpad sell <identifier> <amount|percentage|all>` - Sell tokens (1% fee)
-- `launchpad list` - List all tokens ($0.0001)
-- `launchpad info <identifier>` - Get token information ($0.0001)
-- `launchpad positions` - Get all positions ($0.01)
-- `launchpad fees view <identifier>` - View LP fees (FREE)
-- `launchpad fees claim <identifier> --execute` - Claim LP fees (gas fees)
-
-**Examples:**
-
-```bash
-httpcat launchpad create "My Token" "MTK"
-httpcat launchpad buy MTK 0.10
-httpcat launchpad sell MTK 50%
-httpcat launchpad list --sort mcap
-httpcat launchpad info MTK
-httpcat launchpad positions --active
-httpcat launchpad fees view MTK
-httpcat launchpad fees claim MTK --execute
-```
-
-**Alias:** `lp` (e.g., `httpcat lp create "Token" "TKN"`)
-
-**Note:** Top-level commands `create`, `buy`, `sell`, `list`, `info`, `positions`, and `claim` are deprecated but still work. Use the `launchpad` group for new scripts.
-
-### Portfolio (`portfolio` or `pf`)
-
-Portfolio management and financial data.
-
-**Subcommands:**
-
-- `portfolio balances` - Check wallet balances (FREE)
-- `portfolio positions` - Get all positions across products (FREE)
-- `portfolio summary` - Portfolio overview ($0.01)
-- `portfolio pnl` - Profit and loss analysis ($0.01)
-- `portfolio transactions` - Transaction history (varies)
-
-**Examples:**
-
-```bash
-httpcat portfolio balances
-httpcat portfolio positions --active
-httpcat portfolio summary
-httpcat portfolio pnl --timeframe 7d
-httpcat portfolio transactions --type buy
-```
-
-**Alias:** `pf` (e.g., `httpcat pf balances`)
-
-**Note:** Top-level `balances`, `positions`, and `transactions` commands are deprecated but still work.
-
-### Trade (`trade` or `t`)
-
-Trading operations including swaps, perps, and predictions.
-
-**Subcommands:**
-
-- `trade swap <tokenIn> <tokenOut> <amount>` - Token swap ($0.10 standard, $1.00 shielded)
-- `trade perps markets` - Perpetual futures markets ($0.01)
-- `trade perps onboard` - Onboard to perps venues (FREE)
-- `trade perps deposit <amount>` - Deposit to perps (FREE)
-- `trade perps trade <market> <side> <sizeUsd> <leverage>` - Trade perps ($0.05)
-- `trade perps positions` - View perps positions ($0.01)
-- `trade predictions markets` - Prediction markets ($0.01)
-- `trade predictions market <marketId>` - Market details ($0.01)
-- `trade predictions search <query>` - Search markets ($0.01)
-- `trade predictions bet <marketId> <outcomeId> <amountUsd>` - Place bet ($0.05)
-
-**Examples:**
-
-```bash
-httpcat trade swap USDC WETH 1.0
-httpcat trade swap USDC WETH 1.0 --shielded
-httpcat trade perps markets
-httpcat trade perps trade ETH-USD long 100 10
-httpcat trade predictions markets
-httpcat trade predictions bet polymarket:abc123 outcome1 10
-```
-
-**Alias:** `t` (e.g., `httpcat t swap USDC WETH 1.0`)
-
-**Note:** The `trade` group is a container. Perps and predictions are also available as top-level commands (`httpcat perps`, `httpcat predictions`). Swaps are available as top-level `httpcat swap`.
-
-### System (`system` or `sys`)
-
-System operations and health checks.
-
-**Subcommands:**
-
-- `system health` - Check system health (FREE)
-- `system status` - Get system status ($0.001)
-- `system limits` - Display API rate limits (FREE)
-- `system sources` - List data sources (FREE)
-
-**Examples:**
-
-```bash
-httpcat system health
-httpcat system status
-httpcat system limits
-httpcat system sources
-```
-
-**Alias:** `sys` (e.g., `httpcat sys health`)
-
-**Note:** Top-level `health` command is deprecated but still works.
-
-### Tools (`tools`)
-
-EVM development and interaction utilities.
-
-**Subcommands:**
-
-#### Address Utilities
-
-- `tools address validate <address>` - Validate Ethereum address (FREE)
-- `tools address checksum <address>` - Convert to checksummed format (FREE)
-- `tools address derive <seed> <index>` - Derive address from seed (FREE)
-- `tools address balance <address>` - Get address balance (FREE)
-
-#### ABI Utilities
-
-- `tools abi encode <abi> <function> <args...>` - Encode function call (FREE)
-- `tools abi decode <abi> <function> <data>` - Decode function result (FREE)
-- `tools abi parse <abi>` - Parse and validate ABI (FREE)
-
-#### Transaction Utilities
-
-- `tools tx build <tx-json>` - Build transaction (FREE)
-- `tools tx encode <tx-json>` - Encode transaction (FREE)
-- `tools tx decode <tx-hex>` - Decode transaction (FREE)
-- `tools tx simulate <tx-json>` - Simulate transaction ($0.001)
-- `tools tx estimate-gas <tx-json>` - Estimate gas ($0.001)
-- `tools tx prepare <tx-json>` - Prepare transaction for signing (FREE)
-
-#### Signature Utilities
-
-- `tools signature eip191 <message>` - EIP-191 signature (FREE)
-- `tools signature eip712 <domain> <types> <message>` - EIP-712 signature (FREE)
-- `tools signature permit2 <token> <amount> <spender>` - Permit2 signature (FREE)
-
-#### Multicall Utilities
-
-- `tools multicall encode <calls-json>` - Encode multicall (FREE)
-- `tools multicall decode <data>` - Decode multicall result (FREE)
-
-#### Nonce Utilities
-
-- `tools nonce get <address>` - Get current nonce (FREE)
-- `tools nonce predict <address>` - Predict next nonce (FREE)
-
-#### Gas Utilities
-
-- `tools gas price` - Get current gas price (FREE)
-- `tools gas estimate <tx-json>` - Estimate gas for transaction ($0.001)
-- `tools gas optimize <tx-json>` - Optimize gas settings (FREE)
-
-#### x402 Endpoint Call
-
-- `tools call <endpoint> [options]` - Call arbitrary x402 endpoint (varies)
-
-**Examples:**
-
-```bash
-httpcat tools address validate 0x1234...
-httpcat tools abi encode '[{"inputs":...}]' transfer 0x... 1000
-httpcat tools tx build '{"to":"0x...","value":"1000000000000000000"}'
-httpcat tools signature eip712 '{"name":"App"}' '{}' '{"message":"Hello"}'
-httpcat tools gas price
-httpcat tools call /api/endpoint --method POST --body '{"data":"value"}'
-```
-
-### Security (`security`)
-
-Security and safety analysis tools.
-
-**Subcommands:**
-
-- `security token-scan <tokenAddress>` - Comprehensive token safety scan ($0.01)
-- `security allowances <wallet> <token>` - Check token allowances ($0.001)
-- `security revoke-allowance <token> <spender>` - Generate revoke transaction (FREE)
-
-**Examples:**
-
-```bash
-httpcat security token-scan 0x1234...
-httpcat security allowances 0x... 0x...
-httpcat security revoke-allowance 0x... 0x...
-```
-
-### Risk (`risk`)
-
-Risk management and policy tools.
-
-**Subcommands:**
-
-- `risk policy [--wallet <address>] [--set <json>]` - Get or set risk policy ($0.001)
-- `risk evaluate <wallet> <trade-json>` - Evaluate trade against policy ($0.001)
-
-**Examples:**
-
-```bash
-httpcat risk policy --wallet 0x...
-httpcat risk policy --set '{"maxPositionSize":"1000","maxLeverage":10}'
-httpcat risk evaluate 0x... '{"token":"0x...","amount":"100"}'
-```
-
-### Opportunities (`opps`)
-
-DeFi opportunity discovery.
-
-**Subcommands:**
-
-- `opps arbitrage [--min-profit <amount>]` - Discover arbitrage opportunities ($0.01)
-- `opps funding [--min-rate <rate>]` - Discover funding opportunities ($0.01)
-- `opps yield [--min-apy <apy>]` - Find yield farming opportunities ($0.01)
-- `opps liquidations` - Detect liquidation opportunities ($0.01)
-- `opps execute <opportunityId>` - Execute discovered opportunity (varies)
-
-**Examples:**
-
-```bash
-httpcat opps arbitrage --min-profit 10
-httpcat opps funding --min-rate 0.01
-httpcat opps yield --min-apy 5
-httpcat opps liquidations
-httpcat opps execute opp-123
-```
-
-### Automation (`automation`)
-
-Automation and monitoring tools.
-
-**Subcommands:**
-
-- `automation alerts [--wallet <address>] [--create <json>] [--delete <alertId>]` - Manage alerts ($0.001)
-- `automation webhooks [--wallet <address>] [--register <url>]` - Manage webhooks ($0.001)
-- `automation jobs [--create <json>] [--status <jobId>]` - Manage automation jobs ($0.01)
-
-**Examples:**
-
-```bash
-httpcat automation alerts --wallet 0x...
-httpcat automation alerts --create '{"type":"price","condition":"above","value":"100"}'
-httpcat automation webhooks --register https://example.com/webhook
-httpcat automation jobs --create '{"type":"rebalance","schedule":"daily"}'
-```
-
-### Send (`send`)
-
-Send native currency, tokens, or batch transactions.
-
-**Subcommands:**
-
-- `send eth <to> <amount>` - Send native ETH
-- `send token <token> <to> <amount>` - Send ERC20 token
-- `send batch <batch-json>` - Batch send multiple transactions
-- `send tx <tx-json>` - Send custom transaction
-
-**Token Aliases:**
-
-- `usdc` - USDC token
-- `sol` - Solana token (if on Solana network)
-- `wbtc` - Wrapped Bitcoin
-- `cbbtc` - Coinbase Bitcoin
-
-**Examples:**
-
-```bash
-httpcat send eth 0x... 0.1
-httpcat send token usdc 0x... 100
-httpcat send token 0x... 0x... 50
-httpcat send batch '{"native":[{"to":"0x...","amount":"0.1"}],"tokens":[]}'
-httpcat send tx '{"to":"0x...","value":"1000000000000000000","data":"0x..."}'
-```
-
-### Approve (`approve`)
-
-Token approval operations.
-
-**Subcommands:**
-
-- `approve token <token> <spender> <amount>` - Approve ERC20 token
-- `approve check <token> <spender>` - Check current allowance
-
-**Options:**
-
-- `--permit2` - Use Permit2 instead of direct ERC20 approval
-- `--max` - Approve maximum amount (2^256 - 1)
-
-**Examples:**
-
-```bash
-httpcat approve token usdc 0x... 1000
-httpcat approve token 0x... 0x... max --permit2
-httpcat approve check usdc 0x...
-```
-
-### RPC (`rpc`)
-
-JSON-RPC proxy for blockchain calls.
-
-**Usage:**
-
-```bash
-httpcat rpc --method <method> --params <json-array>
-```
-
-**Examples:**
-
-```bash
-httpcat rpc --method eth_getBalance --params '["0x...","latest"]'
-httpcat rpc --method eth_blockNumber --params '[]'
-httpcat rpc --method eth_call --params '[{"to":"0x...","data":"0x..."},"latest"]'
-```
-
-**Cost:** $0.05 USDC per request
-
-### MCP Server
-
-Start the Model Context Protocol server for AI assistant integration.
-
-**CLI:**
-
-```bash
-httpcat mcp start
-```
-
-**Description:**
-
-Starts an MCP server that exposes all httpcat CLI commands as MCP tools. The server communicates via stdio and can be used with MCP clients like Cursor or Claude Desktop.
-
-**Configuration:**
-
-Add to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp", "start"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..." // Optional
-      }
-    }
-  }
-}
-```
-
-See the [MCP Server section](#mcp-server-model-context-protocol) for detailed documentation.
-
-## Headless Mode (JSON Output)
-
-Perfect for scripting, automation, or LLM/agent integration.
-
-### JSON Output
-
-Add `-j, --json` flag to any command:
-
-```bash
-$ httpcat -j create "Test Token" "TEST"
-{
-  "success": true,
-  "operation": "create_token",
-  "data": {
-    "tokenId": "abc123-4567-89ab-cdef-0123456789ab",
-    "tokenAddress": "0x789abcdef123...",
-    "name": "Test Token",
-    "symbol": "TEST",
-    "totalSupply": "1000000000000000000000000000",
-    "status": "active",
-    "createdAt": "2025-11-22T10:30:00.000Z",
-    "entrypointKey": "create_token_..."
-  },
-  "payment": {
-    "txHash": "0x1234567890abcdef..."
-  }
-}
-```
-
-### JSON Output Schema
-
-All commands with `--json` flag return structured JSON responses. The output follows a consistent schema:
-
-#### Success Response
-
-```json
-{
-  "success": true,
-  "operation": "operation_name",
-  "data": {
-    // Operation-specific data (see below)
-  },
-  "payment": {
-    "txHash": "0x...", // Optional: transaction hash if payment was made
-    "amount": "0.01" // Optional: payment amount
-  }
-}
-```
-
-#### Error Response
-
-```json
-{
-  "success": false,
-  "operation": "operation_name",
-  "error": {
-    "message": "Human-readable error message",
-    "code": 1, // Exit code (see Exit Codes section)
-    "details": {
-      // Optional: Additional error details
-      // May contain nested error objects from the API
-    }
-  }
-}
-```
-
-#### Operation-Specific Data Structures
-
-**Create Token (`create_token`)**
-
-```json
-{
-  "tokenId": "uuid-string",
-  "tokenAddress": "0x...",
-  "name": "Token Name",
-  "symbol": "SYMBOL",
-  "totalSupply": "1000000000000000000000000000",
-  "status": "active",
-  "createdAt": "2025-11-22T10:30:00.000Z",
-  "entrypointKey": "create_token_..."
-}
-```
-
-**Buy Token (`token_buy`)**
-
-```json
-{
-  "tokenId": "uuid-string",
-  "tokensReceived": "50000",
-  "amountSpent": "5.00",
-  "fee": "0.05",
-  "newPrice": "0.0002",
-  "newMarketCap": "200000",
-  "graduationProgress": 0.15,
-  "txHash": "0x..."
-}
-```
-
-**Sell Token (`token_sell`)**
-
-```json
-{
-  "tokenId": "uuid-string",
-  "tokensSold": "1000",
-  "usdcReceived": "0.20",
-  "fee": "0.002",
-  "newPrice": "0.00018",
-  "newMarketCap": "180000",
-  "txHash": "0x..."
-}
-```
-
-**Token Info (`token_info`)**
-
-```json
-{
-  "tokenId": "uuid-string",
-  "name": "Token Name",
-  "symbol": "SYMBOL",
-  "address": "0x...",
-  "status": "active",
-  "price": "0.0002",
-  "mcap": "200000",
-  "graduationProgress": 0.15,
-  "totalSupply": "1000000000000000000000000000",
-  "createdAt": "2025-11-22T10:30:00.000Z",
-  "userPosition": {
-    // Optional: only if you own tokens
-    "tokensOwned": "50000",
-    "usdcInvested": "5.00",
-    "currentValue": "10.00",
-    "pnl": "5.00"
-  }
-}
-```
-
-**List Tokens (`list_tokens`)**
-
-```json
-{
-  "tokens": [
-    {
-      "tokenId": "uuid-string",
-      "name": "Token Name",
-      "symbol": "SYMBOL",
-      "address": "0x...",
-      "status": "active",
-      "mcap": "200000",
-      "price": "0.0002",
-      "graduationProgress": 0.15,
-      "createdAt": "2025-11-22T10:30:00.000Z",
-      "entrypointKey": "..."
-    }
-  ],
-  "total": 100,
-  "page": 1,
-  "limit": 20,
-  "pages": 5
-}
-```
-
-**Positions (`positions`)**
-
-```json
-{
-  "positions": [
-    {
-      "tokenId": "uuid-string",
-      "tokensOwned": "50000",
-      "usdcInvested": "5000000",
-      "currentValue": "10000000",
-      "pnl": "5000000",
-      "pnlPercentage": 100.0,
-      "averageCostPerToken": "0.0001",
-      "positionAge": {
-        "days": 2,
-        "hours": 5,
-        "minutes": 30,
-        "seconds": 15
-      },
-      "createdAt": "2025-11-22T10:30:00.000Z",
-      "updatedAt": "2025-11-24T15:30:00.000Z",
-      "lastTransactionDate": "2025-11-24T15:30:00.000Z",
-      "transactionCount": 3,
-      "token": {
-        "name": "Token Name",
-        "symbol": "SYMBOL",
-        "address": "0x...",
-        "status": "active",
-        "price": "0.0002",
-        "mcap": "200000",
-        "graduationProgress": 0.15
-      }
-    }
-  ],
-  "total": 1,
-  "summary": {
-    "totalPositions": 1,
-    "totalValue": "10000000",
-    "totalInvested": "5000000",
-    "totalPnl": "5000000",
-    "totalPnlPercentage": 100.0
-  }
-}
-```
-
-**Health Check (`health`)**
-
-```json
-{
-  "status": "ok",
-  "timestamp": "2025-11-22T10:30:00.000Z",
-  "agent": "https://agent-test.402.cat"
-}
-```
-
-**Balances (`balances`)**
-
-```json
-{
-  "address": "0x...",
-  "ethBalance": "1000000000000000000",
-  "usdcBalance": "5000000",
-  "ethFormatted": "1.0 ETH",
-  "usdcFormatted": "5.00 USDC"
-}
-```
-
-**Version (`--version --json`)**
-
-```json
-{
-  "name": "httpcat-cli",
-  "version": "0.3.0"
-}
-```
-
-### Quiet Mode
-
-Minimal output, only exit codes:
-
-```bash
-$ httpcat -q buy abc123-... 0.20
-$ echo $?
-0
-```
-
-**Exit Codes:**
-
-- `0` - Success
-- `1` - General error
-- `2` - Configuration error
-- `3` - Network error
-- `4` - Insufficient funds
-- `5` - Validation error
-
-### Example: LLM/Agent Integration
-
-```bash
-#!/bin/bash
-
-# Create a token
-RESULT=$(httpcat -j create "AI Token" "AI")
-TOKEN_ADDRESS=$(echo $RESULT | jq -r '.data.tokenAddress')
-
-# Buy some tokens
-httpcat -j buy $TOKEN_ADDRESS 5
-
-# Get current info
-httpcat -j info $TOKEN_ADDRESS
-
-# Sell 50% if profitable
-INFO=$(httpcat -j info $TOKEN_ADDRESS)
-PNL=$(echo $INFO | jq -r '.data.userPosition.pnl')
-
-if (( $(echo "$PNL > 0" | bc -l) )); then
-  httpcat -j sell $TOKEN_ADDRESS 50%
-fi
-```
-
-### Example: Chat Streaming with Structured Input
-
-For scripts that need raw streaming access:
-
-```bash
-# Using stream-json input format
-echo '{"message": "Hello!"}' | httpcat -j -f stream-json chat MTK
-echo '{"command": "/renew"}' | httpcat -j -f stream-json chat MTK
-
-# Or pipe multiple messages
-cat messages.ndjson | httpcat -j -f stream-json chat MTK
-```
-
-**Note:** For AI agents, MCP tools are recommended over CLI streaming. See [MCP Chat Tools](#chat-tools-usage-example) section.
-
-## MCP Server (Model Context Protocol)
-
-httpcat includes a built-in MCP server that exposes all CLI commands as MCP tools, enabling seamless integration with AI assistants like Claude (via Claude Desktop) or Cursor.
-
-### Quick Start
-
-**Start the MCP server:**
-
-```bash
-httpcat mcp start
-```
-
-**Or use npx (no installation needed):**
-
-```bash
-npx httpcat-cli mcp start
-```
-
-### Quick Installation
-
-Use the automated installer to set up httpcat MCP for your LLM CLI:
-
-```bash
-# Interactive installation (select which LLMs to configure)
-httpcat mcp install
-
-# Install for specific LLM
-httpcat mcp install claude-cli
-
-# Install for Cursor IDE
-httpcat mcp install cursor
-
-# Install for Claude Desktop
-httpcat mcp install claude-desktop
-
-# Install for all detected LLMs
-httpcat mcp install --all
-```
-
-The installer will:
-
-1. Check if wallet is configured (runs onboarding if needed)
-2. Automatically configure your LLM CLI with MCP server
-3. Provide next steps and example system prompt
-
-**Note**: Private key is NOT included in MCP config - the server reads from `~/.config/httpcat/config.json` automatically.
-
-### Manual Configuration
-
-If you prefer to configure manually, add to your MCP client config:
-
-#### For Cursor
-
-Add to your Cursor settings (`.cursor/mcp.json` or settings UI):
-
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"]
-    }
-  }
-}
-```
-
-#### For Claude Desktop
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"]
-    }
-  }
-}
-```
-
-#### Using Global Install
-
-If you've installed httpcat globally:
-
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "httpcat",
-      "args": ["mcp-server"]
-    }
-  }
-}
-```
-
-**Important**: No `HTTPCAT_PRIVATE_KEY` in env - the MCP server automatically reads from `~/.config/httpcat/config.json`.
-
-### Available MCP Tools
-
-The MCP server exposes the following tools:
-
-#### `create_token`
-
-Create a new token on the bonding curve.
-
-**Parameters:**
-
-- `name` (string, required) - Token name (e.g., "My Token")
-- `symbol` (string, required) - Token symbol/ticker (3-10 characters)
-- `photoUrl` (string, optional) - Photo URL, file path, or base64 data URL for token logo
-- `websiteUrl` (string, optional) - Website URL
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** $0.01 USDC
-
-#### `buy_token`
-
-Buy tokens from the bonding curve.
-
-**Parameters:**
-
-- `identifier` (string, required) - Address, name, or symbol
-- `amount` (string, required) - Amount: "0.05", "0.10", or "0.20" (testnet) | "50", "100", or "200" (mainnet)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** Amount + 1% fee
-
-#### `sell_token`
-
-Sell tokens back to the bonding curve.
-
-**Parameters:**
-
-- `identifier` (string, required) - Address, name, or symbol
-- `amount` (string, required) - Amount: number (e.g., "1000"), percentage (e.g., "50%"), or "all"
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** 1% fee deducted from proceeds
-
-#### `token_info`
-
-Get detailed information about a token.
-
-**Parameters:**
-
-- `identifier` (string, required) - Address, name, or symbol
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Token details, price, market cap, graduation progress, and your position (if you own tokens)
-
-**Cost:** $0.0001 USDC
-
-#### `list_tokens`
-
-List all tokens with pagination and sorting.
-
-**Parameters:**
-
-- `page` (number, optional) - Page number (default: 1)
-- `limit` (number, optional) - Items per page (default: 20, max: 100)
-- `sort` (string, optional) - Sort by: "mcap", "created", or "name" (default: "mcap")
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** $0.0001 USDC
-
-#### `positions`
-
-Get all your positions with comprehensive information including current value, profit/loss, ROI, transaction history, and portfolio summary.
-
-**Parameters:**
-
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** All positions for the requesting address with:
-
-- Position details (tokens owned, USDC invested, current value, average cost)
-- Performance metrics (profit/loss, ROI percentage)
-- Position age and transaction history
-- Token information for each position
-- Portfolio summary (total value, total invested, total P/L, overall ROI)
-
-**Cost:** $0.01 USDC
-
-#### `check_balance`
-
-Check wallet balance (ETH and USDC).
-
-**Parameters:**
-
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** Free (no payment required)
-
-#### `health_check`
-
-Check if the httpcat agent is running and healthy.
-
-**Parameters:**
-
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Cost:** $0.0001 USDC
-
-#### `chat_join`
-
-Join a chat room (general or token-specific). Establishes a WebSocket connection and returns a leaseId for subsequent chat operations.
-
-**Parameters:**
-
-- `tokenIdentifier` (string, optional) - Token symbol, name, or address (e.g., "FRIDA", "My Token", or "0x1234..."). If not provided, joins general chat.
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** `{ leaseId, leaseExpiresAt, wsUrl, lastMessages[] }`
-
-**Cost:** $0.01 USDC to join, $0.0001 USDC per message, 10 minute lease
-
-**Note:** The MCP server maintains the WebSocket connection in the background and caches messages. Use `chat_get_recent_messages` to poll for new messages.
-
-#### `chat_send_message`
-
-Send a message to the active chat.
-
-**Parameters:**
-
-- `message` (string, required) - Message text to send
-- `leaseId` (string, required) - Lease ID from `chat_join` result
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** `{ messageId, timestamp, message, author }`
-
-**Cost:** $0.0001 USDC per message
-
-#### `chat_renew_lease`
-
-Renew an expiring or expired chat lease.
-
-**Parameters:**
-
-- `leaseId` (string, optional) - Lease ID to renew. If not provided, renews most recent lease for the private key.
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** `{ leaseId, leaseExpiresAt }`
-
-**Cost:** $0.01 USDC
-
-#### `chat_get_recent_messages`
-
-Get recent messages from chat (polling mechanism). Returns cached messages from the active chat session.
-
-**Parameters:**
-
-- `leaseId` (string, required) - Lease ID from `chat_join` result
-- `limit` (number, optional) - Maximum number of messages to return (default: 50)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** `{ messages[] }` with recent chat messages
-
-**Cost:** Free (uses cached data)
-
-**Note:** Messages are cached in memory as they arrive via WebSocket. Poll this tool periodically to check for new messages.
-
-#### `view_fees`
-
-View accumulated LP fees for a graduated token.
-
-**Parameters:**
-
-- `identifier` (string, required) - Token address, name, or symbol
-- `callerAddress` (string, optional) - Caller address (defaults to wallet address)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Fee information including accumulated tokens and USDC, creator/platform shares, and LP lock status
-
-**Cost:** Free (view only)
-
-#### `claim_fees`
-
-Claim accumulated LP fees for a graduated token.
-
-**Parameters:**
-
-- `identifier` (string, required) - Token address, name, or symbol
-- `callerAddress` (string, optional) - Caller address (defaults to wallet address)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Transaction hash and claimed fee amounts
-
-**Cost:** Gas fees for blockchain transaction
-
-#### `get_transactions`
-
-Get paginated transaction history with filtering options.
-
-**Parameters:**
-
-- `userAddress` (string, optional) - Filter by user address (defaults to wallet address)
-- `tokenId` (string, optional) - Filter by token ID
-- `type` (string, optional) - Filter by type: "buy", "sell", or "airdrop"
-- `limit` (number, optional) - Number of results (default: 50, max: 100)
-- `offset` (number, optional) - Pagination offset (default: 0)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of transactions with type, status, token info, amount, fee, and timestamp
-
-**Cost:** Varies based on API call
-
-#### `swap_tokens`
-
-Swap tokens using universal swap with best route aggregation.
-
-**Parameters:**
-
-- `tokenIn` (string, required) - Token to swap from (address, name, or symbol)
-- `tokenOut` (string, required) - Token to swap to (address, name, or symbol)
-- `amount` (string, required) - Amount to swap (human-readable, e.g., '100' for 100 tokens)
-- `slippageBps` (number, optional) - Slippage tolerance in basis points (default: 50 = 0.5%)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Swap execution details including provider, amounts, gas estimate, and transaction hash
-
-**Cost:** $0.10 USDC
-
-#### `shielded_swap`
-
-MEV-protected swap using UniswapX Dutch auction.
-
-**Parameters:**
-
-- `tokenIn` (string, required) - Token to swap from (address, name, or symbol)
-- `tokenOut` (string, required) - Token to swap to (address, name, or symbol)
-- `amount` (string, required) - Amount to swap (human-readable)
-- `slippageBps` (number, optional) - Slippage tolerance in basis points (default: 50 = 0.5%)
-- `privateKey` (string, required) - Private key for signing
-
-**Returns:** Shielded swap order details and submission status
-
-**Cost:** $1.00 USDC
-
-#### `gasless_swap_quote`
-
-Get gasless swap quotes from multiple providers without paying gas.
-
-**Parameters:**
-
-- `tokenIn` (string, required) - Token address to swap from
-- `tokenOut` (string, required) - Token address to swap to
-- `amount` (string, required) - Amount in smallest units
-- `taker` (string, required) - Taker address (wallet receiving tokens)
-- `slippageBps` (number, optional) - Slippage tolerance in basis points
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of quotes from different providers with prices and routes
-
-**Cost:** FREE
-
-#### `gasless_swap_status`
-
-Check the status of a 0x gasless swap.
-
-**Parameters:**
-
-- `tradeHash` (string, required) - Trade hash from gasless swap
-- `chainId` (number, optional) - Chain ID (defaults to configured network)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Swap status including confirmation status and transaction details
-
-**Cost:** FREE
-
-#### `gasless_swap_submit`
-
-Submit a signed 0x gasless swap trade.
-
-**Parameters:**
-
-- `trade` (object, required) - Signed trade object from 0x API
-- `chainId` (number, optional) - Chain ID
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Submission status and trade hash
-
-**Cost:** $0.01 USDC
-
-#### `gasless_swap_submit_our`
-
-Submit gasless swap using our executor.
-
-**Parameters:**
-
-- `tokenIn` (string, required) - Input token address
-- `tokenOut` (string, required) - Output token address
-- `totalAmount` (string, required) - Total amount in smallest units
-- `feeAmount` (string, required) - Fee amount in smallest units
-- `taker` (string, required) - Taker address
-- `permit2Signature` (string, required) - Permit2 signature
-- `permitNonce` (number, required) - Permit nonce
-- `permitDeadline` (number, required) - Permit deadline timestamp
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Execution status and transaction details
-
-**Cost:** $0.01 USDC
-
-#### `perps_markets`
-
-Get available perpetual futures markets across multiple venues.
-
-**Parameters:**
-
-- `platform` (string, optional) - Filter by platform: "hyperliquid", "avantis", or "aster"
-- `symbol` (string, optional) - Filter by symbol substring (e.g., "BTC")
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of markets with price, funding rate, open interest, and max leverage
-
-**Cost:** $0.01 USDC
-
-#### `perps_onboard`
-
-One-time setup to connect wallet to perps trading venues.
-
-**Parameters:**
-
-- `wallet` (string, required) - Wallet address to onboard
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Setup instructions for each venue including required signatures and transactions
-
-**Cost:** FREE
-
-#### `perps_deposit`
-
-Get deposit options for USDC to perps trading venues.
-
-**Parameters:**
-
-- `amount` (string, required) - USDC amount to deposit (human-readable, e.g., "100")
-- `wallet` (string, required) - Wallet address
-- `venue` (string, optional) - Preferred venue
-- `chain` (string, optional) - Source chain (default: "base")
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Deposit options for each venue with instructions and transaction data
-
-**Cost:** FREE
-
-#### `perps_trade`
-
-Open or close perpetual positions with auto-routing to best venue.
-
-**Parameters:**
-
-- `market` (string, required) - Market to trade (e.g., "BTC", "ETH", "SOL")
-- `side` (string, required) - "long" or "short"
-- `sizeUsd` (string, required) - Position size in USD (minimum $10)
-- `leverage` (number, required) - Leverage multiplier (1-100x)
-- `wallet` (string, required) - Wallet address
-- `orderType` (string, optional) - "market" or "limit" (default: "market")
-- `price` (string, optional) - Limit price for limit orders
-- `takeProfit` (string, optional) - Take profit price
-- `stopLoss` (string, optional) - Stop loss price
-- `reduceOnly` (boolean, optional) - Close existing position only (default: false)
-- `venue` (string, optional) - Force specific venue
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Trade execution details including venue, entry price, liquidation price, and fees
-
-**Cost:** $0.05 USDC
-
-#### `perps_positions`
-
-View all open perpetual positions across venues.
-
-**Parameters:**
-
-- `wallet` (string, required) - Wallet address
-- `venue` (string, optional) - Filter by venue
-- `asterApiKey` (string, optional) - Aster API key (required for Aster positions)
-- `asterApiSecret` (string, optional) - Aster API secret (required for Aster positions)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of open positions with unrealized P&L, margin, and portfolio summary
-
-**Cost:** $0.01 USDC
-
-#### `predictions_markets`
-
-Browse prediction markets from Polymarket and Azuro.
-
-**Parameters:**
-
-- `venue` (string, optional) - Filter by "polymarket" or "azuro"
-- `category` (string, optional) - Category like "politics", "crypto", "sports"
-- `limit` (number, optional) - Max results (default: 20, max: 100)
-- `sort` (string, optional) - Sort by "volume", "trending", or "ending_soon"
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of markets with outcomes, volume, and liquidity
-
-**Cost:** $0.01 USDC
-
-#### `predictions_market`
-
-Get detailed information about a specific prediction market.
-
-**Parameters:**
-
-- `marketId` (string, required) - Market ID in format "venue:id" (e.g., "polymarket:abc123")
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Market details with outcomes, probabilities, volume, and trading info
-
-**Cost:** $0.01 USDC
-
-#### `predictions_search`
-
-Search prediction markets by keyword.
-
-**Parameters:**
-
-- `query` (string, required) - Search keyword
-- `venue` (string, optional) - Filter by venue
-- `limit` (number, optional) - Max results (default: 20, max: 50)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Matching markets with relevance scores
-
-**Cost:** $0.01 USDC
-
-#### `predictions_bet`
-
-Place a bet on a prediction market outcome.
-
-**Parameters:**
-
-- `marketId` (string, required) - Market ID in "venue:id" format
-- `outcomeId` (string, required) - Which outcome to bet on
-- `amountUsd` (number, required) - Bet amount in USD
-- `wallet` (string, required) - Wallet address
-- `polymarketApiKey` (string, optional) - Polymarket CLOB API key
-- `polymarketApiSecret` (string, optional) - Polymarket CLOB API secret
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Bet details and transaction/order information
-
-**Cost:** $0.05 USDC
-
-#### `predictions_detect_arbs`
-
-Scan for arbitrage opportunities across prediction venues.
-
-**Parameters:**
-
-- `minSpreadPct` (number, optional) - Minimum spread percentage (default: 1.0%)
-- `venues` (array, optional) - Specific venues to scan
-- `cryptoOnly` (boolean, optional) - Focus on crypto markets
-- `maxResults` (number, optional) - Max results (default: 20)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Array of arbitrage opportunities with expected profit and execution details
-
-**Cost:** FREE
-
-#### `predictions_calculate_hedge`
-
-Calculate optimal perpetual hedge for a prediction market position.
-
-**Parameters:**
-
-- `marketA` (object, required) - First market details
-- `marketB` (object, required) - Second market details
-- `positionSizeUsd` (number, required) - Position size
-- `currentPrice` (number, required) - Current asset price
-- `fundingRate8h` (number, optional) - Funding rate (default: 0.01%)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Hedge strategy with direction, size, duration, costs, and expected profit
-
-**Cost:** FREE
-
-#### `predictions_execute_arb`
-
-Execute complete arbitrage trade with optional perpetual hedge.
-
-**Parameters:**
-
-- `marketA` (object, required) - First market details
-- `marketB` (object, required) - Second market details
-- `positionSizeUsd` (number, required) - Position size for each leg
-- `autoHedge` (boolean, optional) - Enable automatic hedge (default: true)
-- `maxSlippagePct` (number, optional) - Max slippage (default: 2%)
-- `currentPrice` (number, optional) - For hedge calculation
-- `wallet` (string, required) - Wallet address
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Execution details for both legs, hedge info, and profit summary
-
-**Cost:** $0.20 USDC
-
-#### `predictions_detect_insiders`
-
-Detect sophisticated traders via wallet graph analysis.
-
-**Parameters:**
-
-- `timeWindowMinutes` (number, optional) - Analysis time window (default: 5)
-- `minTrades` (number, optional) - Minimum trades (default: 5)
-- `minSimilarity` (number, optional) - Min Jaccard similarity (default: 0.1)
-- `includeCommunities` (boolean, optional) - Include copytrade clusters (default: true)
-- `maxResults` (number, optional) - Max results (default: 50)
-- `assetFilter` (string, optional) - Filter by asset like "BTC"
-- `trades` (array, optional) - Historical trade data
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Detected arbitrageurs, market leaders, and copytrade communities
-
-**Cost:** $5.00 USDC
-
-#### `rpc_proxy`
-
-JSON-RPC proxy for Ethereum/Base blockchain calls.
-
-**Parameters:**
-
-- `jsonrpc` (string, required) - JSON-RPC version (typically "2.0")
-- `id` (number, required) - Request ID
-- `method` (string, required) - RPC method (e.g., 'eth_blockNumber', 'eth_getBalance')
-- `params` (array, required) - Method parameters
-- `privateKey` (string, optional) - Private key (overrides config/env)
-
-**Returns:** Standard JSON-RPC response with result or error
-
-**Cost:** $0.05 USDC per request
-
-### Chat Tools Usage Example
-
-Here's how an AI agent like Claude Code would use the chat tools:
-
-```javascript
-// Step 1: Join the FRIDA token chat room
-const joinResult = await mcp.callTool("chat_join", {
-  tokenIdentifier: "FRIDA",
-});
-// Returns: { leaseId: "abc123...", leaseExpiresAt: "...", lastMessages: [...] }
-
-// Step 2: Send a message
-const sendResult = await mcp.callTool("chat_send_message", {
-  message: "Hello FRIDA community!",
-  leaseId: joinResult.leaseId,
-});
-// Returns: { messageId: "msg456...", timestamp: "...", message: "...", author: "0x..." }
-
-// Step 3: Poll for new messages (agent does this periodically)
-const messages = await mcp.callTool("chat_get_recent_messages", {
-  leaseId: joinResult.leaseId,
-  limit: 20,
-});
-// Returns: { messages: [...] }
-
-// Step 4: Renew lease when needed
-const renewal = await mcp.callTool("chat_renew_lease", {
-  leaseId: joinResult.leaseId,
-});
-// Returns: { leaseId: "new-lease-id...", leaseExpiresAt: "..." }
-```
-
-**Key Benefits:**
-
-- No shell scripting or process management required
-- WebSocket connections maintained automatically by MCP server
-- Messages cached in memory for quick retrieval
-- Simple polling model for agents
-
-### Private Key Configuration
-
-Private keys are automatically read from the httpcat config file (`~/.config/httpcat/config.json`).
-
-**Priority order** (if you need to override):
-
-1. **Tool parameter** - Pass `privateKey` in each tool call (highest priority)
-2. **Environment variable** - Set `HTTPCAT_PRIVATE_KEY` (for backward compatibility)
-3. **Config file** - Default: `~/.config/httpcat/config.json` (recommended)
-
-**Security Recommendation:** Use the config file (default). The MCP server automatically reads from it, so you don't need to pass private keys in MCP configs.
-
-### Onboarding
-
-If no wallet is configured when the MCP server starts, it will run an interactive onboarding flow:
-
-1. **Generate new wallet** - Creates a seed phrase (recommended for new users)
-2. **Import seed phrase** - Import existing 12/24 word seed phrase
-3. **Import private key** - Import existing private key
-
-The onboarding runs automatically via stdio, so it works seamlessly with LLM CLI tools.
-
-See [MCP Onboarding Guide](docs/MCP_ONBOARDING.md) for detailed information.
-
-### Example MCP Tool Usage
-
-Once configured, AI assistants can use the tools like this:
-
-```
-create_token(name="Moon Token", symbol="MOON", websiteUrl="https://moon.com")
-buy_token(identifier="0x1234...", amount="0.20")
-token_info(identifier="MOON")
-list_tokens(sort="mcap", limit=10)
-check_balance()
-```
-
-### Response Format
-
-All MCP tools return structured JSON responses matching the CLI's JSON output format:
-
-**Success:**
-
-```json
-{
-  "success": true,
-  "operation": "tool_name",
-  "data": {
-    // Tool-specific data
-  }
-}
-```
-
-**Error:**
-
-```json
-{
-  "success": false,
-  "operation": "tool_name",
-  "error": {
-    "message": "Error message",
-    "code": 1,
-    "details": {}
-  }
-}
-```
-
-### MCP Resources
-
-The MCP server provides resources for static data:
-
-- `httpcat://tokens/list` - Cached token list with market data
-- `httpcat://network/status` - Network status and configuration
-- `httpcat://ecosystem/info` - Ecosystem information and token economics
-
-Resources are cached (5 minute TTL) for faster access.
-
-### MCP Prompts
-
-System prompts available for LLM agents:
-
-- `ecosystem_context` - Comprehensive ecosystem information
-- `system_prompt` - Suggested system prompt for configuring agents
-
-### Enhanced Tool Descriptions
-
-All tools include:
-
-- 💰 Cost information
-- 📝 Usage examples
-- 💡 Tips and best practices
-- Detailed parameter descriptions
-
-### Benefits
-
-- **No Shell Access Required** - AI assistants can interact with httpcat without needing shell/terminal access
-- **Structured Responses** - Consistent JSON output format for reliable parsing
-- **Secure** - Private keys stored locally, never in LLM config files
-- **Automatic Onboarding** - Interactive setup when wallet not configured
-- **Always Up-to-Date** - Using `npx` ensures you always get the latest version
-- **Zero Configuration** - Automated installation with `mcp-install` command
-- **Rich Context** - Resources and prompts provide ecosystem information
-
-## Advanced Usage
-
-### Environment Management
-
-httpcat supports multiple environments (local, base-sepolia, etc.) to easily switch between different agent deployments.
-
-#### List Environments
-
-```bash
-httpcat env list
-```
-
-Shows all available environments with their agent URLs and networks.
-
-#### Switch Environment
-
-```bash
-# Switch to local environment
-httpcat env use local
-
-# Switch to base-sepolia environment
-httpcat env use base-sepolia
-```
-
-#### Show Current Environment
-
-```bash
-httpcat env show
-```
-
-#### Add Custom Environment
-
-```bash
-# Add a custom environment
-httpcat env add production http://production-agent:8787 -n base
-
-# Switch to it
-httpcat env use production
-```
-
-#### Update Environment
-
-```bash
-# Update existing environment URL
-httpcat env update local http://localhost:8788
-
-# Update environment with different network
-httpcat env update production http://prod-agent:8787 -n base
-```
-
-Updates an existing environment's agent URL and optionally its network.
-
-#### Predefined Environments
-
-- **local** - `http://localhost:8787` (eip155:84532)
-- **sepolia** - `https://agent-test.402.cat` (eip155:84532)
-
-#### Environment Priority
-
-Agent URL resolution priority:
-
-1. `HTTPCAT_AGENT_URL` environment variable
-2. Current environment's agent URL
-3. Config file `agentUrl` setting
-4. Default value
-
-### Environment Variables
-
-Override config with environment variables:
-
-```bash
-# Private key (most secure - doesn't save to config)
-export HTTPCAT_PRIVATE_KEY=0x1234567890abcdef...
-
-# Agent URL (overrides environment)
-export HTTPCAT_AGENT_URL=http://custom-agent:8787
-
-# Run commands
-httpcat create "My Token" "MTK"
-```
-
-### Private Key Command-Line Option
-
-You can also pass the private key directly via command-line flag (highest priority):
-
-```bash
-# Private key priority: CLI flag > Environment variable > Config file
-httpcat -k 0x1234567890abcdef... create "My Token" "MTK"
-httpcat -k 0x1234567890abcdef... -j buy 0x1234... 0.20
-```
-
-**Note:** The `--private-key` flag takes precedence over environment variables and config file settings.
-
-### Custom Network Configuration
-
-```bash
-# Switch to mainnet
-httpcat config -S network=base
-httpcat config -S agentUrl=http://production-url:8787
-
-# Or in interactive mode
-httpcat> network base
-```
-
-### Disable ASCII Art
-
-```bash
-# Globally
-httpcat config --set preferences.enableAsciiArt=false
-
-# Per session
-httpcat --no-art
-```
-
-## Configuration File
-
-Config is stored at `~/.config/httpcat/config.json`:
-
-```json
-{
-  "encryptedPrivateKey": "...",
-  "encryptedSeedPhrase": "...",
-  "password": "hashed_password",
-  "passwordTimeoutMinutes": 15,
-  "accounts": [
-    {
-      "index": 0,
-      "type": "custom",
-      "address": "0x...",
-      "label": "Main Account"
-    },
-    {
-      "index": 1,
-      "type": "seed",
-      "address": "0x..."
-    }
-  ],
-  "activeAccountIndex": 0,
-  "network": "eip155:84532",
-  "agentUrl": "https://agent-test.402.cat",
-  "facilitatorUrl": "https://facilitators.x402scan.com",
-  "defaultMaxPayment": "10.00",
-  "environment": "base-sepolia",
-  "environments": {
-    "local": {
-      "name": "local",
-      "agentUrl": "http://localhost:8787",
-      "network": "eip155:84532"
-    },
-    "base-sepolia": {
-      "name": "base-sepolia",
-      "agentUrl": "https://agent-test.402.cat",
-      "network": "eip155:84532"
-    }
-  },
-  "preferences": {
-    "enableAsciiArt": true,
-    "colorOutput": true,
-    "verboseLogging": false
-  },
-  "aiAgent": {
-    "provider": "openai",
-    "apiKey": "encrypted_key_here",
-    "model": "gpt-4"
-  },
-  "autonomousAgent": {
-    "enabled": false,
-    "maxTradeAmount": "10.00",
-    "riskTolerance": "moderate",
-    "tokenFilters": {
-      "minHolders": 10,
-      "maxWhalePercentage": 20,
-      "minLiquidity": 1000
-    },
-    "stopLoss": 20,
-    "takeProfit": 50,
-    "eventStreamUrl": "wss://events.402.cat",
-    "databasePath": "~/.config/httpcat/agent.db"
-  }
-}
-```
-
-**Security Features:**
-
-- **Password Protection**: Set a password during setup to encrypt your private keys and seed phrase
-- **Session Management**: Configurable timeout (default: 15 minutes via `passwordTimeoutMinutes`)
-  - After the timeout, you'll need to re-enter your password to unlock the wallet
-  - Session tokens are managed automatically to keep your wallet secure
-- **Multi-Account Support**: Manage multiple accounts (seed-derived HD wallet accounts and custom imported accounts)
-- **Encrypted Storage**: Keys and seed phrases are encrypted when password is enabled
-- **Account Types**:
-  - **Account 0 (Custom)**: Imported via private key during initial setup
-  - **Account 1+ (Seed-Derived)**: Generated from your seed phrase using BIP-32/BIP-39 HD wallet derivation
-  - You can add unlimited seed-derived accounts using `account add`
-  - All accounts share the same password protection
-
-**Security Notes:**
-
-- **Without password**: Private key stored in plain text (legacy `privateKey` field, auto-migrated to encrypted format on first password setup)
-- **With password**: Private key, seed phrase, and AI API keys are AES-256 encrypted
-- **Session Timeout**: Wallet automatically locks after 15 minutes of inactivity (configurable)
-- **For production use**:
-  - Enable password protection during setup for encryption
-  - Use `HTTPCAT_PRIVATE_KEY` environment variable for additional security in scripts
-  - Set restrictive file permissions: `chmod 600 ~/.config/httpcat/config.json`
-  - Use a dedicated wallet with limited funds for trading operations
-
-## How It Works
-
-### x402 Payment Protocol
-
-httpcat uses the [x402 protocol V2](https://x402.org) for micropayments:
-
-1. **Request** - CLI makes a request to the agent
-2. **402 Response** - Agent returns payment requirements
-3. **Payment** - CLI automatically transfers USDC
-4. **Verification** - Agent verifies payment via facilitator
-5. **Response** - Agent processes request and returns result
-
-All of this happens automatically - you just see the result!
-
-### Bonding Curve
-
-Tokens use a bonding curve pricing mechanism:
-
-- Price increases as more tokens are bought
-- Price decreases as tokens are sold
-- 1% fee on all buy/sell operations
-- Automatic graduation at market cap threshold
-- Graduated tokens get Uniswap V2 liquidity
-
-## Troubleshooting
-
-### "No private key configured"
-
-Run the setup wizard:
-
-```bash
-httpcat config
-```
-
-Or use environment variable:
-
-```bash
-export HTTPCAT_PRIVATE_KEY=0x...
-```
-
-### "Insufficient USDC balance"
-
-Make sure you have enough USDC in your wallet:
-
-- Test mode (Base Sepolia / eip155:84532): Get testnet USDC from faucets
-- Production (base): Bridge USDC to Base
-
-You also need ETH for gas fees.
-
-### "Request failed with status 402"
-
-The payment verification failed. Check:
-
-1. Wallet has sufficient USDC and ETH
-2. Network is correct (eip155:84532 for testnet vs eip155:8453 for mainnet)
-3. Agent URL is reachable
-4. Facilitator URL is correct
-
-### Connection errors
-
-Verify the agent is running:
-
-```bash
-httpcat health
-```
-
-Check your config:
-
-```bash
-httpcat config --show
-```
-
-## Examples
-
-### Complete Workflow
-
-```bash
-# Setup
-httpcat config
-
-# Check your wallet balances
-httpcat balances
-
-# Create a token
-httpcat create "Moon Cat" "MOON" -w --website https://mooncat.io
-
-# Buy tokens
-httpcat buy 0x1234... 5
-
-# Check your position
-httpcat info 0x1234...
-
-# Get all your positions with comprehensive info
-httpcat positions
-
-# Sell half when profitable
-httpcat sell 0x1234... 50%
-
-# List all your tokens (shows positions)
-httpcat list
-```
-
-### Scripted Trading Bot
-
-```bash
-#!/bin/bash
-
-TOKEN_ADDRESS="0x1234567890abcdef1234567890abcdef12345678"
-
-# Monitor and trade
-while true; do
-  INFO=$(httpcat -j info $TOKEN_ADDRESS)
-  PROGRESS=$(echo $INFO | jq -r '.data.graduationProgress')
-
-  # Buy if close to graduation
-  if (( $(echo "$PROGRESS > 90" | bc -l) )); then
-    httpcat -q buy $TOKEN_ADDRESS 5
-  fi
-
-  sleep 60
-done
-```
-
-## Development
-
-```bash
-# Install dependencies
-yarn install
-
-# Build
-yarn build
-
-# Watch mode
-yarn dev
-
-# Link for local testing
-yarn link
-
-# Test
-httpcat --version
-```
+---
 
 ## License
 
@@ -3091,6 +283,7 @@ MIT
 
 ## Support
 
-- Report issues: https://github.com/hathbanger/httpcat-cli/issues
-- httpcat agent: https://agent-test.402.cat
-- x402 protocol: https://x402.org
+- Issues: https://github.com/hathbanger/httpcat-cli/issues
+- Agent: https://agent-test.402.cat
+- Protocol: https://x402.org
+- Docs: https://www.402.cat/docs