httpcat-cli 0.3.0-rc.9 → 0.3.1

package/README.md

@@ -94,18 +94,46 @@ 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:**
+
+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:
 
-- **Private Key** - Your wallet's private key (starts with 0x) or seed phrase for HD wallet
-- **Password** - (Optional) Password to encrypt your private keys and seed phrase
 - **Network** - Network format: `eip155:84532` (Base Sepolia testnet) or `eip155:8453` (Base mainnet)
-- **Agent URL** - The httpcat agent endpoint (default: https://agent.402.cat)
+- **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>`):
@@ -125,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:
@@ -139,6 +167,13 @@ Available Commands:
   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
@@ -219,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.
@@ -341,6 +378,8 @@ httpcat sell MTK all
 
 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
@@ -368,7 +407,273 @@ httpcat swap 0x036cbd53842c5426634e7929541ec2318f3dcf7e 0x4200000000000000000000
 httpcat swap 0x036c... 0x4200... 1000000 --slippage 100
 ```
 
-**Cost:** $0.10 USDC
+**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
 
@@ -671,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.
@@ -847,131 +1219,543 @@ httpcat config -s             # Show current config (JSON)
 httpcat config -S network=base # Update a setting
 ```
 
-### MCP Server
+### Sign
 
-Start the Model Context Protocol server for AI assistant integration.
+Cryptographic signing operations for messages, files, transactions, and structured data.
 
-**CLI:**
+**Interactive:**
 
 ```bash
-httpcat mcp-server
+httpcat> sign                    # Enter interactive signing mode
 ```
 
-**Description:**
+**CLI:**
 
-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.
+```bash
+# Sign a message (EIP-191)
+httpcat sign message "Hello, world!"
+httpcat sign message --file message.txt
+echo "Hello" | httpcat sign message --stdin
 
-**Configuration:**
+# Sign a file
+httpcat sign file document.pdf
+httpcat sign file document.pdf --hash-algorithm keccak256
 
-Add to your MCP client config:
+# Sign a transaction
+httpcat sign transaction '{"to":"0x...","value":"1000000000000000000"}'
 
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..." // Optional
-      }
-    }
-  }
-}
+# 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!"
 ```
 
-See the [MCP Server section](#mcp-server-model-context-protocol) for detailed documentation.
+**Subcommands:**
 
-## Headless Mode (JSON Output)
+- `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
 
-Perfect for scripting, automation, or LLM/agent integration.
+**Options:**
 
-### JSON Output
+- `--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)
 
-Add `-j, --json` flag to any command:
+**Examples:**
 
 ```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..."
-  }
-}
-```
+# Sign a message and verify
+httpcat sign message "Hello, world!" --verify
 
-### JSON Output Schema
+# Sign a file and save to output file
+httpcat sign file document.pdf --output signature.json
 
-All commands with `--json` flag return structured JSON responses. The output follows a consistent schema:
+# Sign with different format
+httpcat sign message "Test" --format rsv
 
-#### Success Response
+# Sign Permit2 with auto-generated nonce and deadline
+httpcat sign permit2 --token 0x... --amount 1000000 --spender 0x...
 
-```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
-  }
-}
+# Verify an EIP-712 signature
+httpcat sign verify --signature 0x... --message '{}' --type eip712 \
+  --domain '{"name":"MyApp"}' --types '{}' --primary-type Message
 ```
 
-#### Error Response
+**Cost:** $0.001 USDC per signature preparation (signing is done locally)
 
-```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
-    }
-  }
-}
-```
+**Note:** Signatures are created locally using your private key. The backend only prepares the signature data; actual signing happens client-side for security.
 
-#### Operation-Specific Data Structures
+## Command Groups
 
-**Create Token (`create_token`)**
+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.
 
-```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_..."
-}
-```
+### Launchpad (`launchpad` or `lp`)
 
-**Buy Token (`token_buy`)**
+Token creation and trading on the bonding curve.
 
-```json
-{
-  "tokenId": "uuid-string",
-  "tokensReceived": "50000",
-  "amountSpent": "5.00",
-  "fee": "0.05",
+**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,
@@ -1093,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"
 }
 ```
 
@@ -1114,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"
 }
 ```
 
@@ -1185,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
 ```
 
-### MCP Client Configuration
+### 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
 
-Add the httpcat MCP server to your MCP client configuration:
+**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
 
@@ -1207,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"]
     }
   }
 }
@@ -1225,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"]
     }
   }
 }
@@ -1243,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:
@@ -1461,6 +2267,334 @@ Get paginated transaction history with filtering options.
 
 **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:
@@ -1502,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 config file (default). The MCP server automatically reads from it, so you don't need to pass private keys in MCP configs.
 
-**Security Recommendation:** Use the environment variable in your MCP client config rather than passing it in each tool call.
+### 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
 
@@ -1552,13 +2700,41 @@ 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
 
@@ -1615,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
 
@@ -1699,7 +2875,7 @@ 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": "base-sepolia",
@@ -1711,7 +2887,7 @@ Config is stored at `~/.config/httpcat/config.json`:
     },
     "base-sepolia": {
       "name": "base-sepolia",
-      "agentUrl": "https://agent.402.cat",
+      "agentUrl": "https://agent-test.402.cat",
       "network": "eip155:84532"
     }
   },
@@ -1916,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