httpcat-cli 0.3.0 → 0.3.1

package/README.md

@@ -94,19 +94,53 @@ yarn build
 
 ### First-Time Setup
 
-Run `httpcat` to start the configuration wizard:
+Run `httpcat` to automatically create your wallet:
 
 ```bash
 httpcat
 ```
 
-You'll be prompted to enter:
+**Automatic Wallet Generation:**
 
-- **Private Key** - Your wallet's private key (starts with 0x)
-- **Network** - `eip155:84532` (Base Sepolia testnet) or `eip155:8453` (Base mainnet)
-- **Agent URL** - The httpcat agent endpoint
+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:
@@ -119,7 +153,7 @@ $ httpcat
   > ^ <  Your agent for token operations
 
 🔗 Connected to: eip155:84532 (Base Sepolia)
-🌐 Agent: https://agent.402.cat
+🌐 Agent: https://agent-test.402.cat
 
 httpcat> help
 Available Commands:
@@ -127,20 +161,26 @@ 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
-  agent <query> | cat <query>     Ask the cat to do something (agent and cat are synonyms)
-  agent --chat | cat --chat       Enter interactive chat mode
-  agent --setup | cat --setup     Configure API key/provider
+  cat                             Start interactive AI assistant chat mode
+  agent setup                     Configure autonomous trading agent settings
   health                          Check agent health
   config [--show|--set|--reset]   Manage configuration
-  network                          Show current network
   env [list|use|show|add|update]  Manage environments
   help                            Show this help message
   exit                            Exit the shell
@@ -214,6 +254,8 @@ httpcat -q buy MTK 0.20 && echo "Success!" || echo "Failed"
 
 ## 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
 
 Create a new token on the bonding curve.
@@ -239,6 +281,8 @@ httpcat create "My Token" "MTK" --photo ./logo.png
 - `-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
@@ -297,6 +341,8 @@ httpcat buy MTK 0.10 -r 10 -d 500
 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
@@ -328,6 +374,307 @@ httpcat sell MTK all
 
 **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
+```
+
 ### Token Info
 
 Get detailed information about a token.
@@ -469,6 +816,7 @@ httpcat --json claim "My Token"
 **Output:**
 
 When viewing (without `--execute`):
+
 - Total accumulated fees (tokens and USDC)
 - Creator share (80%)
 - Platform share (20%)
@@ -476,6 +824,7 @@ When viewing (without `--execute`):
 - V4 position details (if applicable)
 
 When claiming (with `--execute`):
+
 - Transaction hash
 - Fees claimed (tokens and USDC)
 - Creator and platform shares distribution
@@ -515,6 +864,7 @@ httpcat --json transactions --offset 50
 **Output:**
 
 For each transaction:
+
 - Transaction type (buy, sell, or airdrop)
 - Status (pending, success, or failed)
 - Token information (name, symbol, ID)
@@ -596,6 +946,7 @@ httpcat --json account
 **Output:**
 
 Account information includes:
+
 - Account index and type (Seed-Derived or Custom)
 - Wallet address (checksummed)
 - ETH balance (for gas fees)
@@ -603,7 +954,7 @@ Account information includes:
 - CAT balance (402CAT token)
 - All positions (if any) with P&L
 
-**Cost:** Free
+**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.
 
@@ -625,6 +976,73 @@ 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.
@@ -686,98 +1104,533 @@ While in a chat session, you can use these commands:
 
 **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 / Agent
+### Cat (Interactive AI Assistant)
 
-Interact with an AI-powered cat assistant that can help you with token operations, portfolio management, and more. **`agent` and `cat` are synonyms** - you can use either command name.
+Interact with an AI-powered assistant that can help you with token operations, portfolio management, and more using natural language.
 
 **Interactive:**
 
 ```bash
-httpcat> agent "Buy 100 WOW tokens"     # Ask the cat to do something
-httpcat> cat "What tokens do I own?"     # Same thing, different name
-httpcat> agent --chat                    # Enter interactive chat mode
-httpcat> cat --chat                      # Same thing
-httpcat> agent --setup                   # Configure API key/provider
-httpcat> cat --setup                     # Same thing
-```
-
-**CLI:**
-
-```bash
-httpcat agent "Buy 100 WOW tokens"
-httpcat cat "What tokens do I own?"
-httpcat agent --chat
-httpcat cat --chat
-httpcat agent --setup
-httpcat cat --setup
+httpcat> cat
+# Starts interactive AI chat session
+# Type /exit to quit
 ```
 
 **Usage:**
 
-- `agent <query>` or `cat <query>` - Ask the cat to execute a task (e.g., "Buy WOW tokens", "Check my balance", "List my positions")
-- `agent --chat` or `cat --chat` - Enter interactive chat mode for extended conversations
-- `agent --setup` or `cat --setup` - Configure or reconfigure your AI provider (OpenAI or Anthropic) and API key
+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/agent, you'll need to configure it:
+Before using the cat command, you'll need to configure your AI provider:
 
 ```bash
-httpcat> agent --setup
-# or
-httpcat> cat --setup
+httpcat config
 ```
 
-You'll be prompted to:
+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 uses an AI agent (powered by OpenAI GPT-4 or Anthropic Claude) to understand natural language requests and execute token operations on your behalf. It can:
+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:**
+**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 help
-httpcat --help
-httpcat -h
+httpcat approve token usdc 0x... 1000
+httpcat approve token 0x... 0x... max --permit2
+httpcat approve check usdc 0x...
 ```
 
-All three commands show the same help output with available commands and options.
-
-### Configuration
+### RPC (`rpc`)
 
-Manage your httpcat configuration.
+JSON-RPC proxy for blockchain calls.
 
-**Interactive:**
+**Usage:**
 
 ```bash
-httpcat> config -s              # Show current config
-httpcat> config -S network=base  # Update a setting
-httpcat> config -r             # Re-run setup wizard
+httpcat rpc --method <method> --params <json-array>
 ```
 
-**CLI:**
+**Examples:**
 
 ```bash
-httpcat config                    # Run setup wizard
-httpcat config -s             # Show current config (JSON)
-httpcat config -S network=base # Update a setting
+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.
@@ -785,7 +1638,7 @@ Start the Model Context Protocol server for AI assistant integration.
 **CLI:**
 
 ```bash
-httpcat mcp-server
+httpcat mcp start
 ```
 
 **Description:**
@@ -801,7 +1654,7 @@ Add to your MCP client config:
   "mcpServers": {
     "httpcat": {
       "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
+      "args": ["-y", "httpcat-cli", "mcp", "start"],
       "env": {
         "HTTPCAT_PRIVATE_KEY": "0x..." // Optional
       }
@@ -1024,7 +1877,7 @@ All commands with `--json` flag return structured JSON responses. The output fol
 {
   "status": "ok",
   "timestamp": "2025-11-22T10:30:00.000Z",
-  "agent": "https://agent.402.cat"
+  "agent": "https://agent-test.402.cat"
 }
 ```
 
@@ -1045,7 +1898,7 @@ All commands with `--json` flag return structured JSON responses. The output fol
 ```json
 {
   "name": "httpcat-cli",
-  "version": "0.0.8"
+  "version": "0.3.0"
 }
 ```
 
@@ -1116,18 +1969,47 @@ httpcat includes a built-in MCP server that exposes all CLI commands as MCP tool
 **Start the MCP server:**
 
 ```bash
-httpcat mcp-server
+httpcat mcp start
 ```
 
 **Or use npx (no installation needed):**
 
 ```bash
-npx httpcat-cli mcp-server
+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
 ```
 
-### MCP Client Configuration
+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
 
-Add the httpcat MCP server to your MCP client configuration:
+If you prefer to configure manually, add to your MCP client config:
 
 #### For Cursor
 
@@ -1138,10 +2020,7 @@ Add to your Cursor settings (`.cursor/mcp.json` or settings UI):
   "mcpServers": {
     "httpcat": {
       "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..." // Optional - can also pass via tool params
-      }
+      "args": ["-y", "httpcat-cli", "mcp-server"]
     }
   }
 }
@@ -1156,10 +2035,7 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
   "mcpServers": {
     "httpcat": {
       "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..."
-      }
+      "args": ["-y", "httpcat-cli", "mcp-server"]
     }
   }
 }
@@ -1174,15 +2050,14 @@ If you've installed httpcat globally:
   "mcpServers": {
     "httpcat": {
       "command": "httpcat",
-      "args": ["mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..."
-      }
+      "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:
@@ -1347,6 +2222,379 @@ Get recent messages from chat (polling mechanism). Returns cached messages from
 
 **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:
@@ -1388,13 +2636,27 @@ const renewal = await mcp.callTool("chat_renew_lease", {
 
 ### Private Key Configuration
 
-Private keys can be configured in three ways (priority order):
+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` in the MCP client config
-3. **Config file** - Use `httpcat config` to set up `~/.config/httpcat/config.json`
+2. **Environment variable** - Set `HTTPCAT_PRIVATE_KEY` (for backward compatibility)
+3. **Config file** - Default: `~/.config/httpcat/config.json` (recommended)
 
-**Security Recommendation:** Use the environment variable in your MCP client config rather than passing it in each tool call.
+**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
 
@@ -1438,19 +2700,47 @@ All MCP tools return structured JSON responses matching the CLI's JSON output fo
 }
 ```
 
+### 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 can be managed via environment variables or config
+- **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** - Works out of the box with standard MCP clients
+- **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, sepolia, etc.) to easily switch between different agent deployments.
+httpcat supports multiple environments (local, base-sepolia, etc.) to easily switch between different agent deployments.
 
 #### List Environments
 
@@ -1466,8 +2756,8 @@ Shows all available environments with their agent URLs and networks.
 # Switch to local environment
 httpcat env use local
 
-# Switch to sepolia environment
-httpcat env use sepolia
+# Switch to base-sepolia environment
+httpcat env use base-sepolia
 ```
 
 #### Show Current Environment
@@ -1501,7 +2791,7 @@ Updates an existing environment's agent URL and optionally its network.
 #### Predefined Environments
 
 - **local** - `http://localhost:8787` (eip155:84532)
-- **sepolia** - `https://agent.402.cat` (eip155:84532)
+- **sepolia** - `https://agent-test.402.cat` (eip155:84532)
 
 #### Environment Priority
 
@@ -1585,20 +2875,20 @@ Config is stored at `~/.config/httpcat/config.json`:
   ],
   "activeAccountIndex": 0,
   "network": "eip155:84532",
-  "agentUrl": "https://agent.402.cat",
+  "agentUrl": "https://agent-test.402.cat",
   "facilitatorUrl": "https://facilitators.x402scan.com",
   "defaultMaxPayment": "10.00",
-  "environment": "sepolia",
+  "environment": "base-sepolia",
   "environments": {
     "local": {
       "name": "local",
       "agentUrl": "http://localhost:8787",
-      "network": "base-sepolia"
+      "network": "eip155:84532"
     },
-    "sepolia": {
-      "name": "sepolia",
-      "agentUrl": "https://agent.402.cat",
-      "network": "base-sepolia"
+    "base-sepolia": {
+      "name": "base-sepolia",
+      "agentUrl": "https://agent-test.402.cat",
+      "network": "eip155:84532"
     }
   },
   "preferences": {
@@ -1610,6 +2900,20 @@ Config is stored at `~/.config/httpcat/config.json`:
     "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"
   }
 }
 ```
@@ -1618,21 +2922,26 @@ Config is stored at `~/.config/httpcat/config.json`:
 
 - **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**:
-  - **Seed-Derived** (Account 1+): Generated from your seed phrase using BIP-32/BIP-39
-  - **Custom** (Account 0): Imported via private key
+  - **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)
-- **With password**: Private key, seed phrase, and AI API keys are encrypted
+- **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
+  - 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
+  - Use a dedicated wallet with limited funds for trading operations
 
 ## How It Works
 
@@ -1706,16 +3015,6 @@ Check your config:
 httpcat config --show
 ```
 
-### Check Wallet Balance
-
-Use the balances command to check your wallet's ETH and USDC balances:
-
-```bash
-httpcat balances
-```
-
-This will show your wallet address, ETH balance (for gas fees), and USDC balance (for trading), with warnings if balances are low.
-
 ## Examples
 
 ### Complete Workflow
@@ -1793,5 +3092,5 @@ MIT
 ## Support
 
 - Report issues: https://github.com/hathbanger/httpcat-cli/issues
-- httpcat agent: https://agent.402.cat
+- httpcat agent: https://agent-test.402.cat
 - x402 protocol: https://x402.org