npm - httpcat-cli - Versions diffs - 0.3.0 → 0.3.1-rc.1 - Mend

httpcat-cli 0.3.0 → 0.3.1-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (760) hide show

package/README.md CHANGED Viewed

@@ -1,1790 +1,232 @@
 # httpcat-cli
-> 🐱 Command-line interface for interacting with the httpcat agent - create, buy, and sell tokens with x402 payments
+![Banner](brand-assets/png/social/og-v12-ears-1280x320-dark.png)
-httpcat is a full-featured CLI tool that provides both interactive (with ASCII art cats!) and headless modes for token operations on the httpcat agent. It supports creating tokens, buying, selling, and managing your portfolio with seamless x402 payment integration.
+> **The CLI that enables agents to use x402 protocol. No middleware. No wallets. Just HTTP-native micropayments.**
-## Features
+**Give your agent claws.**
-- 🎨 **Interactive Shell** - Beautiful REPL with ASCII art cats and colored output
-- 🐱 **Headless Mode** - JSON output for scripting and LLM/agent integration
-- 🔌 **MCP Server** - Built-in Model Context Protocol server for AI assistant integration
-- 💳 **x402 Payments** - Automatic payment handling via x402 protocol
-- 🔐 **Secure Config** - Local configuration storage in `~/.config/httpcat`
-- 🌐 **Multi-Network** - Support for Base Sepolia (testnet) and Base (mainnet)
-- 📊 **Rich Output** - Tables, progress bars, and detailed token information
-- ⚡ **Fast & Simple** - Built with TypeScript and optimized for performance
+---
-## Installation
-### npm (recommended)
-```bash
-npm install -g httpcat-cli
-```
-Or use with npx without installing:
-```bash
-npx httpcat-cli
-```
-### Homebrew (macOS/Linux)
-```bash
-brew tap hathbanger/httpcat
-brew install httpcat
-```
-### From Source
-```bash
-cd httpcat-cli
-yarn install
-yarn build
-yarn link
-```
-## Upgrading
-### npm (Global Install)
-If you installed httpcat globally via npm:
-```bash
-npm update -g httpcat-cli
-```
-### Yarn (Global Install)
-If you installed httpcat globally via yarn:
-```bash
-yarn global upgrade httpcat-cli
-```
-### Homebrew
-If you installed via Homebrew:
-```bash
-brew upgrade httpcat
-```
-### npx (No Upgrade Needed)
-If you're using `npx httpcat-cli`, it automatically uses the latest version - no upgrade needed!
-```bash
-npx httpcat-cli@latest
-```
-### From Source (Development)
-If you're developing locally with `yarn link`:
-```bash
-cd httpcat-cli
-git pull
-yarn install
-yarn build
-```
-## Quick Start
-### First-Time Setup
-Run `httpcat` to start the configuration wizard:
-```bash
-httpcat
-```
-You'll be prompted to enter:
-- **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
-- **ASCII Art** - Enable or disable cat art
-### Interactive Mode
-Once configured, running `httpcat` without arguments starts an interactive shell:
-```bash
-$ httpcat
-  /\_/\
- ( ^.^ ) Welcome to httpcat!
-  > ^ <  Your agent for token operations
-🔗 Connected to: eip155:84532 (Base Sepolia)
-🌐 Agent: https://agent.402.cat
-httpcat> help
-Available Commands:
-  create <name> <symbol>          Create a new token
-  buy <id|name|symbol> <amount>   Buy tokens ($0.05, $0.10, $0.20, or percentage like 50%)
-  sell <id|name|symbol> <amount|all>  Sell tokens
-  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
-  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
-  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
-httpcat> create "Meow Token" "MEOW"
-  /\_/\  Creating your token...
- ( o.o )💭
-💳 Payment required: $0.01 USDC
-✅ Token created successfully!
-┌─────────────────────────────────────────┐
-│ 🎉 Meow Token (MEOW)                    │
-├─────────────────────────────────────────┤
-│ Address:   0x789abcd...                 │
-│ Supply:    1,000,000,000 MEOW           │
-│ Status:    Active                       │
-└─────────────────────────────────────────┘
-httpcat> buy 0x789abcd... 0.20
-💰 Tokens purchased successfully!
-┌─────────────────────────────────────────┐
-│ 💰 Purchase Summary                     │
-├─────────────────────────────────────────┤
-│ Tokens Received: 50,000                 │
-│ Amount Spent:    $5.00                  │
-│ Fee (1%):        $0.05                  │
-│ New Price:       $0.0002                │
-│ New Market Cap:  $200,000               │
-│ Graduation:      0.15%                  │
-└─────────────────────────────────────────┘
-[🐱==>                  ] 0.15% to moon!
-```
-## Global Options
-These options can be used with any command:
-- `-j, --json` - Output in JSON format for scripting and automation
-- `-q, --quiet` - Minimal output (exit codes only)
-- `-v, --verbose` - Show verbose error messages and debugging information
-- `--no-art` - Disable ASCII art cats
-- `-k, --private-key <key>` - Use specific private key (overrides config and env var)
-- `-a, --account <index>` - Use specific account index (overrides active account)
-**Examples:**
-```bash
-# Use account 2 for getting positions
-httpcat -a 2 positions
-# Use account 1 to buy tokens
-httpcat -a 1 buy MTK 0.10
-# JSON output for account 0
-httpcat --json -a 0 balances
-# Use specific private key
-httpcat -k 0x1234... create "Test" "TEST"
-# Quiet mode with exit code checking
-httpcat -q buy MTK 0.20 && echo "Success!" || echo "Failed"
-```
-**Note:** The `-a, --account` flag allows you to use different accounts without switching your active account in the config.
-## Commands
-### Create Token
-Create a new token on the bonding curve.
-**Interactive:**
-```bash
-httpcat> create "My Token" "MTK"
-httpcat> create "My Token" "MTK" --photo https://example.com/photo.png
-httpcat> create "My Token" "MTK" --photo ./logo.png
-```
-**CLI:**
-```bash
-httpcat create "My Token" "MTK"
-httpcat create "My Token" "MTK" --photo https://example.com/photo.png --website https://mytoken.io
-httpcat create "My Token" "MTK" --photo ./logo.png
-```
-**Options:**
-- `-p, --photo <url|path>` - Token photo URL or file path (supports http/https URLs, local file paths, or base64 data URLs)
-- `-w, --website <url>` - Website URL
-**Cost:** $0.01 USDC
-### Buy Tokens
-Purchase tokens from the bonding curve.
-**Interactive:**
-```bash
-httpcat> buy 0x1234... 0.20
-httpcat> buy "My Token" 0.10
-httpcat> buy MTK 0.05
-```
-**CLI:**
-```bash
-httpcat buy 0x1234567890abcdef1234567890abcdef12345678 0.20
-httpcat buy "My Token" 0.10
-httpcat buy MTK 0.05
-```
-**Options:**
-- `-r, --repeat <count>` - Execute multiple buys in sequence (stops early if token graduates or insufficient funds)
-- `-d, --delay <ms>` - Delay in milliseconds between repeat operations (default: 0)
-**Examples with repeat:**
-```bash
-# Execute 10 buys back-to-back
-httpcat buy MTK 0.10 -r 10
-# Execute 10 buys with 500ms delay between each
-httpcat buy MTK 0.10 -r 10 -d 500
-```
-**Token Identifier:**
-- Token address: `0x1234...` (contract address)
-- Token name: `"My Token"` (use quotes if it contains spaces)
-- Token symbol: `MTK` (case-insensitive)
-**Amounts:**
-- Test mode (Base Sepolia / eip155:84532): `0.05`, `0.10`, or `0.20` USDC
-- Production (base): `50`, `100`, or `200` USDC
-- Percentage: `10%`, `50%`, `100%` (percentage of your USDC balance)
-  - Example: `httpcat buy MTK 50%` - Buy with 50% of your USDC balance
-  - Works with any percentage from 0.01% to 100%
-**Cost:** Amount + 1% fee (e.g., $5.05 for $5 purchase)
-**Repeat Mode Behavior:**
-When using `-r, --repeat`, the command will:
-- Execute the specified number of buys sequentially
-- Stop early if the token graduates (reaches 100% graduation progress)
-- Stop early if you run out of funds (HTTP 402 error)
-- Display a compact summary for each buy
-- Show a final summary with total buys completed, total spent, and final status
-### Sell Tokens
-Sell tokens back to the bonding curve.
-**Interactive:**
-```bash
-httpcat> sell 0x1234... 1000        # Sell 1000 tokens
-httpcat> sell "My Token" 50%         # Sell 50% of holdings
-httpcat> sell MTK all                # Sell all tokens
-```
-**CLI:**
-```bash
-httpcat sell 0x1234567890abcdef1234567890abcdef12345678 1000
-httpcat sell "My Token" 50%
-httpcat sell MTK all
-```
-**Token Identifier:**
-- Address, name, or symbol (same as buy command)
-**Cost:** Dynamic based on amount (1% fee deducted from proceeds)
-### Token Info
-Get detailed information about a token.
-**Interactive:**
-```bash
-httpcat> info 0x1234...
-httpcat> info "My Token"
-httpcat> info MTK
-```
-**CLI:**
-```bash
-httpcat info 0x1234567890abcdef1234567890abcdef12345678
-httpcat info "My Token"
-httpcat info MTK
-```
-**Token Identifier:**
-- Address, name, or symbol (same as buy command)
-**Output:**
-- Token name, symbol, address
-- Current price and market cap
-- Graduation progress
-- Your position (if you hold any)
-- P&L calculation
-**Cost:** $0.0001 USDC
-### List Tokens
-List all tokens with pagination and sorting.
-**Interactive:**
-```bash
-httpcat> list
-httpcat> list --sort mcap --limit 10
-httpcat> list --page 2
-```
-**CLI:**
-```bash
-httpcat list
-httpcat list --sort created --limit 50
-httpcat list --page 3 --sort name
-```
-**Options:**
-- `-s, --sort <field>` - Sort by `mcap`, `created`, or `name` (default: `mcap`)
-- `-l, --limit <n>` - Items per page (default: 20, max: 100)
-- `-p, --page <n>` - Page number (default: 1)
-**Cost:** $0.0001 USDC
-### Positions
-Get all your positions with comprehensive information including current value, profit/loss, ROI, transaction history, and portfolio summary.
-**Interactive:**
-```bash
-httpcat> positions
-```
-**CLI:**
-```bash
-httpcat positions
-httpcat positions --active           # Only active positions
-httpcat positions --graduated        # Only graduated positions
-httpcat -j positions
-httpcat -k 0x... positions
-```
-**Options:**
-- `-a, --active` - Show only active (non-graduated) positions
-- `-g, --graduated` - Show only graduated positions (historical)
-**Output:**
-For each position:
-- Token information (name, symbol, address, status, price, market cap, graduation progress)
-- Position details (tokens owned, USDC invested, current value, average cost per token)
-- Performance metrics (profit/loss in USDC and percentage ROI)
-- Position age (days, hours, minutes, seconds since first purchase)
-- Transaction history (total transaction count, last transaction date)
-- Timestamps (position created and updated dates)
-Portfolio summary:
-- Total positions count
-- Total portfolio value
-- Total amount invested
-- Total profit/loss and overall ROI percentage
-**Cost:** $0.01 USDC
-### Claim LP Fees
-View and claim accumulated liquidity provider fees for graduated tokens.
-**Interactive:**
-```bash
-httpcat> claim "My Token"           # View accumulated fees
-httpcat> claim MTK                  # View by symbol
-httpcat> claim MTK --execute        # Claim fees
-```
-**CLI:**
-```bash
-httpcat claim "My Token"
-httpcat claim MTK
-httpcat claim MTK --execute
-httpcat claim 0x1234... --execute
-httpcat --json claim "My Token"
-```
-**Options:**
-- `-e, --execute` - Execute the claim transaction (default is view-only)
-- `-A, --address <address>` - Caller address (defaults to wallet address)
-**Token Identifier:**
-- Address, name, or symbol (same as buy/sell commands)
-**Output:**
-When viewing (without `--execute`):
-- Total accumulated fees (tokens and USDC)
-- Creator share (80%)
-- Platform share (20%)
-- LP lock status and details
-- V4 position details (if applicable)
-When claiming (with `--execute`):
-- Transaction hash
-- Fees claimed (tokens and USDC)
-- Creator and platform shares distribution
-**Cost:** Free to view, gas fees apply for claiming
-### Transactions
-Get paginated transaction history with filtering options.
-**Interactive:**
-```bash
-httpcat> transactions
-httpcat> transactions --type buy
-httpcat> transactions --token abc123-...
-```
-**CLI:**
-```bash
-httpcat transactions
-httpcat transactions --user 0x1234...
-httpcat transactions --token abc123-... --type buy
-httpcat transactions --type sell --limit 20
-httpcat --json transactions --offset 50
-```
-**Options:**
-- `-u, --user <address>` - Filter by user address (defaults to active account)
-- `-t, --token <tokenId>` - Filter by token ID
-- `-T, --type <type>` - Filter by type: `buy`, `sell`, or `airdrop`
-- `-l, --limit <number>` - Number of results (default: 50, max: 100)
-- `-o, --offset <number>` - Pagination offset (default: 0)
-**Output:**
-For each transaction:
-- Transaction type (buy, sell, or airdrop)
-- Status (pending, success, or failed)
-- Token information (name, symbol, ID)
-- User address
-- Amount and fee
-- Transaction hash
-- Date/time
-**Cost:** Varies based on API call
-**Note:** Defaults to showing transactions for your active account. Use `--user` to view transactions for a different address.
-### Check Balances
-Check your wallet's ETH and USDC balances.
-**Interactive:**
-```bash
-httpcat> balances
-```
-**CLI:**
-```bash
-httpcat balances
-httpcat balances -k 0x...
-```
-**Output:**
-- Wallet address
-- ETH balance (for gas fees)
-- USDC balance (for trading)
-- CAT balance (402CAT token)
-- Low balance warnings if applicable
-**Cost:** Free (no payment required)
-**Note:** If no private key is configured, you'll be prompted to enter it interactively (same as other commands).
-### Account Management
-Manage multiple accounts, view account information, and switch between accounts.
-**Interactive:**
-```bash
-httpcat> account                    # Show active account info
-httpcat> account list               # List all accounts
-httpcat> account switch 1           # Switch to account 1
-httpcat> account add                # Add new account
-```
-**CLI:**
-```bash
-httpcat account                     # Show active account
-httpcat account list                # List all accounts
-httpcat account switch 1            # Switch to account 1
-httpcat account add                 # Add new account
-httpcat --account 2 positions       # Use account 2 for positions
-httpcat -a 1 buy MTK 0.10           # Use account 1 for buy
-httpcat --json account
-```
-**Subcommands:**
-- `account` (no args) - Display active account information (address, balances, positions)
-- `account list` - List all configured accounts with their details
-- `account switch <index>` - Switch to a different account by index
-- `account add` - Add a new seed-derived account (HD wallet)
-**Account Types:**
-1. **Seed-Derived** (Account 1+) - Accounts generated from your seed phrase using BIP-32/BIP-39
-2. **Custom** (Account 0) - Account added via private key import
-**Output:**
-Account information includes:
-- Account index and type (Seed-Derived or Custom)
-- Wallet address (checksummed)
-- ETH balance (for gas fees)
-- USDC balance (for trading)
-- CAT balance (402CAT token)
-- All positions (if any) with P&L
-**Cost:** Free
-**Security Note:** All accounts share the same password protection when password is enabled. Switch accounts anytime using the `--account` flag or `account switch` command.
-### Health Check
-Check if the agent is running.
-**Interactive:**
-```bash
-httpcat> health
-```
-**CLI:**
-```bash
-httpcat health
-```
-**Cost:** $0.0001 USDC (or 402 response)
-### Chat
-Start streaming chat with the httpcat community. Join general chat or token-specific discussions.
-**Interactive:**
-```bash
-httpcat> chat                    # Join general chat
-httpcat> chat MTK                # Join chat for token with symbol "MTK"
-httpcat> chat "My Token"         # Join chat for token with name "My Token"
-httpcat> chat 0x1234...          # Join chat for token at address
-```
-**CLI:**
-```bash
-httpcat chat
-httpcat chat MTK
-httpcat chat "My Token"
-httpcat chat 0x1234...
-httpcat -j chat MTK
-httpcat -j -f stream-json chat MTK  # Structured JSON input
-```
-**Token Identifier:**
-- Token symbol: `MTK` (case-insensitive)
-- Token name: `"My Token"` (use quotes if it contains spaces)
-- Token address: `0x1234...`
-**In-Chat Commands:**
-While in a chat session, you can use these commands:
-- `/exit` or `/quit` - Exit the chat
-- `/renew` - Renew your 10-minute lease
-- `/buy <amount>` - Buy tokens (token-specific chats only)
-- `/sell <amount>` - Sell tokens (token-specific chats only)
-- `/help` - Show available commands
-**Examples:**
-```
-/renew
-/buy 0.10
-/sell 50%
-/sell all
-```
-**Note:** The `/buy` and `/sell` commands are only available in token-specific chats, not in general chat.
-**Options:**
-- `-f, --input-format <format>` - Input format (only works with `--json`): `"text"` (default) or `"stream-json"` (realtime streaming input)
-  - `"text"`: Line-delimited text input (default)
-  - `"stream-json"`: Newline-delimited JSON (NDJSON) objects. Each line is a JSON object: `{"message": "text"}` or `{"command": "/renew"}`
-**Cost:** $0.01 USDC to join, $0.0001 USDC per message, 10 minute lease
-**Note:** For AI agents, consider using MCP tools (`chat_join`, `chat_send_message`, etc.) instead of CLI streaming for better integration. See [MCP Chat Tools](#chat-tools-usage-example) section.
-### Cat / Agent
-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.
-**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
-```
-**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
-**First-Time Setup:**
-Before using the cat/agent, you'll need to configure it:
-```bash
-httpcat> agent --setup
-# or
-httpcat> cat --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:
-- Buy and sell tokens
-- Check balances and positions
-- List tokens
-- Get token information
-- 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.
-### Help
-Display help information for httpcat.
-**CLI:**
-```bash
-httpcat help
-httpcat --help
-httpcat -h
-```
-All three commands show the same help output with available commands and options.
-### Configuration
-Manage your httpcat configuration.
-**Interactive:**
-```bash
-httpcat> config -s              # Show current config
-httpcat> config -S network=base  # Update a setting
-httpcat> config -r             # Re-run setup wizard
-```
-**CLI:**
-```bash
-httpcat config                    # Run setup wizard
-httpcat config -s             # Show current config (JSON)
-httpcat config -S network=base # Update a setting
-```
-### MCP Server
-Start the Model Context Protocol server for AI assistant integration.
-**CLI:**
-```bash
-httpcat mcp-server
-```
-**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-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..." // Optional
-      }
-    }
-  }
-}
-```
-See the [MCP Server section](#mcp-server-model-context-protocol) for detailed documentation.
-## Headless Mode (JSON Output)
-Perfect for scripting, automation, or LLM/agent integration.
-### JSON Output
-Add `-j, --json` flag to any command:
-```bash
-$ httpcat -j create "Test Token" "TEST"
-{
-  "success": true,
-  "operation": "create_token",
-  "data": {
-    "tokenId": "abc123-4567-89ab-cdef-0123456789ab",
-    "tokenAddress": "0x789abcdef123...",
-    "name": "Test Token",
-    "symbol": "TEST",
-    "totalSupply": "1000000000000000000000000000",
-    "status": "active",
-    "createdAt": "2025-11-22T10:30:00.000Z",
-    "entrypointKey": "create_token_..."
-  },
-  "payment": {
-    "txHash": "0x1234567890abcdef..."
-  }
-}
-```
-### JSON Output Schema
-All commands with `--json` flag return structured JSON responses. The output follows a consistent schema:
-#### Success Response
-```json
-{
-  "success": true,
-  "operation": "operation_name",
-  "data": {
-    // Operation-specific data (see below)
-  },
-  "payment": {
-    "txHash": "0x...", // Optional: transaction hash if payment was made
-    "amount": "0.01" // Optional: payment amount
-  }
-}
-```
-#### Error Response
-```json
-{
-  "success": false,
-  "operation": "operation_name",
-  "error": {
-    "message": "Human-readable error message",
-    "code": 1, // Exit code (see Exit Codes section)
-    "details": {
-      // Optional: Additional error details
-      // May contain nested error objects from the API
-    }
-  }
-}
-```
-#### Operation-Specific Data Structures
-**Create Token (`create_token`)**
-```json
-{
-  "tokenId": "uuid-string",
-  "tokenAddress": "0x...",
-  "name": "Token Name",
-  "symbol": "SYMBOL",
-  "totalSupply": "1000000000000000000000000000",
-  "status": "active",
-  "createdAt": "2025-11-22T10:30:00.000Z",
-  "entrypointKey": "create_token_..."
-}
-```
-**Buy Token (`token_buy`)**
-```json
-{
-  "tokenId": "uuid-string",
-  "tokensReceived": "50000",
-  "amountSpent": "5.00",
-  "fee": "0.05",
-  "newPrice": "0.0002",
-  "newMarketCap": "200000",
-  "graduationProgress": 0.15,
-  "txHash": "0x..."
-}
-```
-**Sell Token (`token_sell`)**
-```json
-{
-  "tokenId": "uuid-string",
-  "tokensSold": "1000",
-  "usdcReceived": "0.20",
-  "fee": "0.002",
-  "newPrice": "0.00018",
-  "newMarketCap": "180000",
-  "txHash": "0x..."
-}
-```
-**Token Info (`token_info`)**
-```json
-{
-  "tokenId": "uuid-string",
-  "name": "Token Name",
-  "symbol": "SYMBOL",
-  "address": "0x...",
-  "status": "active",
-  "price": "0.0002",
-  "mcap": "200000",
-  "graduationProgress": 0.15,
-  "totalSupply": "1000000000000000000000000000",
-  "createdAt": "2025-11-22T10:30:00.000Z",
-  "userPosition": {
-    // Optional: only if you own tokens
-    "tokensOwned": "50000",
-    "usdcInvested": "5.00",
-    "currentValue": "10.00",
-    "pnl": "5.00"
-  }
-}
-```
-**List Tokens (`list_tokens`)**
-```json
-{
-  "tokens": [
-    {
-      "tokenId": "uuid-string",
-      "name": "Token Name",
-      "symbol": "SYMBOL",
-      "address": "0x...",
-      "status": "active",
-      "mcap": "200000",
-      "price": "0.0002",
-      "graduationProgress": 0.15,
-      "createdAt": "2025-11-22T10:30:00.000Z",
-      "entrypointKey": "..."
-    }
-  ],
-  "total": 100,
-  "page": 1,
-  "limit": 20,
-  "pages": 5
-}
-```
-**Positions (`positions`)**
-```json
-{
-  "positions": [
-    {
-      "tokenId": "uuid-string",
-      "tokensOwned": "50000",
-      "usdcInvested": "5000000",
-      "currentValue": "10000000",
-      "pnl": "5000000",
-      "pnlPercentage": 100.0,
-      "averageCostPerToken": "0.0001",
-      "positionAge": {
-        "days": 2,
-        "hours": 5,
-        "minutes": 30,
-        "seconds": 15
-      },
-      "createdAt": "2025-11-22T10:30:00.000Z",
-      "updatedAt": "2025-11-24T15:30:00.000Z",
-      "lastTransactionDate": "2025-11-24T15:30:00.000Z",
-      "transactionCount": 3,
-      "token": {
-        "name": "Token Name",
-        "symbol": "SYMBOL",
-        "address": "0x...",
-        "status": "active",
-        "price": "0.0002",
-        "mcap": "200000",
-        "graduationProgress": 0.15
-      }
-    }
-  ],
-  "total": 1,
-  "summary": {
-    "totalPositions": 1,
-    "totalValue": "10000000",
-    "totalInvested": "5000000",
-    "totalPnl": "5000000",
-    "totalPnlPercentage": 100.0
-  }
-}
-```
-**Health Check (`health`)**
-```json
-{
-  "status": "ok",
-  "timestamp": "2025-11-22T10:30:00.000Z",
-  "agent": "https://agent.402.cat"
-}
-```
-**Balances (`balances`)**
-```json
-{
-  "address": "0x...",
-  "ethBalance": "1000000000000000000",
-  "usdcBalance": "5000000",
-  "ethFormatted": "1.0 ETH",
-  "usdcFormatted": "5.00 USDC"
-}
-```
+## What is httpcat?
-**Version (`--version --json`)**
+httpcat is the command-line interface for [402.cat](https://402.cat) — the tool that lets agents interact with x402-protected endpoints and build economic capabilities.
-```json
-{
-  "name": "httpcat-cli",
-  "version": "0.0.8"
-}
-```
+**The foundation:** x402 protocol enables HTTP-native micropayments. Every API call can be a paid transaction. No API keys. No accounts. Just pay-per-call.
-### Quiet Mode
+httpcat wraps this in a CLI that agents can use directly. It handles payment signatures automatically.
-Minimal output, only exit codes:
+---
-```bash
-$ httpcat -q buy abc123-... 0.20
-$ echo $?
-0
-```
-**Exit Codes:**
+## How It Works
-- `0` - Success
-- `1` - General error
-- `2` - Configuration error
-- `3` - Network error
-- `4` - Insufficient funds
-- `5` - Validation error
+### x402 Protocol Integration
-### Example: LLM/Agent Integration
+httpcat uses the x402 protocol to handle payments automatically:
-```bash
-#!/bin/bash
+1. **Request** → CLI makes HTTP request to x402 endpoint
+2. **402 Response** → Endpoint returns payment requirements
+3. **Payment** → CLI generates payment signature and retries
+4. **Response** → Endpoint processes and returns result
-# Create a token
-RESULT=$(httpcat -j create "AI Token" "AI")
-TOKEN_ADDRESS=$(echo $RESULT | jq -r '.data.tokenAddress')
+All of this happens automatically. No middleware. No wallet management in your code. Just HTTP requests with payment headers.
-# Buy some tokens
-httpcat -j buy $TOKEN_ADDRESS 5
+### Entrypoints
-# Get current info
-httpcat -j info $TOKEN_ADDRESS
+Entrypoints are services wrapped in x402 protocol. They're composable and automatically handle payments.
-# Sell 50% if profitable
-INFO=$(httpcat -j info $TOKEN_ADDRESS)
-PNL=$(echo $INFO | jq -r '.data.userPosition.pnl')
+**Built-in entrypoints:**
-if (( $(echo "$PNL > 0" | bc -l) )); then
-  httpcat -j sell $TOKEN_ADDRESS 50%
-fi
-```
+- `swap` — DEX aggregator for token swaps
+- `launchpad` — Token creation and trading
+- `rpc` — JSON-RPC proxy for blockchain calls
-### Example: Chat Streaming with Structured Input
+---
-For scripts that need raw streaming access:
+## Installation
 ```bash
-# Using stream-json input format
-echo '{"message": "Hello!"}' | httpcat -j -f stream-json chat MTK
-echo '{"command": "/renew"}' | httpcat -j -f stream-json chat MTK
-# Or pipe multiple messages
-cat messages.ndjson | httpcat -j -f stream-json chat MTK
+npm install -g httpcat-cli
 ```
-**Note:** For AI agents, MCP tools are recommended over CLI streaming. See [MCP Chat Tools](#chat-tools-usage-example) section.
-## MCP Server (Model Context Protocol)
-httpcat includes a built-in MCP server that exposes all CLI commands as MCP tools, enabling seamless integration with AI assistants like Claude (via Claude Desktop) or Cursor.
-### Quick Start
-**Start the MCP server:**
+Or use with npx:
 ```bash
-httpcat mcp-server
+npx httpcat-cli
 ```
-**Or use npx (no installation needed):**
+Homebrew:
 ```bash
-npx httpcat-cli mcp-server
-```
-### MCP Client Configuration
-Add the httpcat MCP server to your MCP client configuration:
-#### For Cursor
-Add to your Cursor settings (`.cursor/mcp.json` or settings UI):
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..." // Optional - can also pass via tool params
-      }
-    }
-  }
-}
-```
-#### For Claude Desktop
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "npx",
-      "args": ["-y", "httpcat-cli", "mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..."
-      }
-    }
-  }
-}
-```
-#### Using Global Install
-If you've installed httpcat globally:
-```json
-{
-  "mcpServers": {
-    "httpcat": {
-      "command": "httpcat",
-      "args": ["mcp-server"],
-      "env": {
-        "HTTPCAT_PRIVATE_KEY": "0x..."
-      }
-    }
-  }
-}
-```
-### Available MCP Tools
-The MCP server exposes the following tools:
-#### `create_token`
-Create a new token on the bonding curve.
-**Parameters:**
-- `name` (string, required) - Token name (e.g., "My Token")
-- `symbol` (string, required) - Token symbol/ticker (3-10 characters)
-- `photoUrl` (string, optional) - Photo URL, file path, or base64 data URL for token logo
-- `websiteUrl` (string, optional) - Website URL
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** $0.01 USDC
-#### `buy_token`
-Buy tokens from the bonding curve.
-**Parameters:**
-- `identifier` (string, required) - Address, name, or symbol
-- `amount` (string, required) - Amount: "0.05", "0.10", or "0.20" (testnet) | "50", "100", or "200" (mainnet)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** Amount + 1% fee
-#### `sell_token`
-Sell tokens back to the bonding curve.
-**Parameters:**
-- `identifier` (string, required) - Address, name, or symbol
-- `amount` (string, required) - Amount: number (e.g., "1000"), percentage (e.g., "50%"), or "all"
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** 1% fee deducted from proceeds
-#### `token_info`
-Get detailed information about a token.
-**Parameters:**
-- `identifier` (string, required) - Address, name, or symbol
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** Token details, price, market cap, graduation progress, and your position (if you own tokens)
-**Cost:** $0.0001 USDC
-#### `list_tokens`
-List all tokens with pagination and sorting.
-**Parameters:**
-- `page` (number, optional) - Page number (default: 1)
-- `limit` (number, optional) - Items per page (default: 20, max: 100)
-- `sort` (string, optional) - Sort by: "mcap", "created", or "name" (default: "mcap")
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** $0.0001 USDC
-#### `positions`
-Get all your positions with comprehensive information including current value, profit/loss, ROI, transaction history, and portfolio summary.
-**Parameters:**
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** All positions for the requesting address with:
-- Position details (tokens owned, USDC invested, current value, average cost)
-- Performance metrics (profit/loss, ROI percentage)
-- Position age and transaction history
-- Token information for each position
-- Portfolio summary (total value, total invested, total P/L, overall ROI)
-**Cost:** $0.01 USDC
-#### `check_balance`
-Check wallet balance (ETH and USDC).
-**Parameters:**
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** Free (no payment required)
-#### `health_check`
-Check if the httpcat agent is running and healthy.
-**Parameters:**
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Cost:** $0.0001 USDC
-#### `chat_join`
-Join a chat room (general or token-specific). Establishes a WebSocket connection and returns a leaseId for subsequent chat operations.
-**Parameters:**
-- `tokenIdentifier` (string, optional) - Token symbol, name, or address (e.g., "FRIDA", "My Token", or "0x1234..."). If not provided, joins general chat.
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** `{ leaseId, leaseExpiresAt, wsUrl, lastMessages[] }`
-**Cost:** $0.01 USDC to join, $0.0001 USDC per message, 10 minute lease
-**Note:** The MCP server maintains the WebSocket connection in the background and caches messages. Use `chat_get_recent_messages` to poll for new messages.
-#### `chat_send_message`
-Send a message to the active chat.
-**Parameters:**
-- `message` (string, required) - Message text to send
-- `leaseId` (string, required) - Lease ID from `chat_join` result
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** `{ messageId, timestamp, message, author }`
-**Cost:** $0.0001 USDC per message
-#### `chat_renew_lease`
-Renew an expiring or expired chat lease.
-**Parameters:**
-- `leaseId` (string, optional) - Lease ID to renew. If not provided, renews most recent lease for the private key.
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** `{ leaseId, leaseExpiresAt }`
-**Cost:** $0.01 USDC
-#### `chat_get_recent_messages`
-Get recent messages from chat (polling mechanism). Returns cached messages from the active chat session.
-**Parameters:**
-- `leaseId` (string, required) - Lease ID from `chat_join` result
-- `limit` (number, optional) - Maximum number of messages to return (default: 50)
-- `privateKey` (string, optional) - Private key (overrides config/env)
-**Returns:** `{ messages[] }` with recent chat messages
-**Cost:** Free (uses cached data)
-**Note:** Messages are cached in memory as they arrive via WebSocket. Poll this tool periodically to check for new messages.
-### Chat Tools Usage Example
-Here's how an AI agent like Claude Code would use the chat tools:
-```javascript
-// Step 1: Join the FRIDA token chat room
-const joinResult = await mcp.callTool("chat_join", {
-  tokenIdentifier: "FRIDA",
-});
-// Returns: { leaseId: "abc123...", leaseExpiresAt: "...", lastMessages: [...] }
-// Step 2: Send a message
-const sendResult = await mcp.callTool("chat_send_message", {
-  message: "Hello FRIDA community!",
-  leaseId: joinResult.leaseId,
-});
-// Returns: { messageId: "msg456...", timestamp: "...", message: "...", author: "0x..." }
-// Step 3: Poll for new messages (agent does this periodically)
-const messages = await mcp.callTool("chat_get_recent_messages", {
-  leaseId: joinResult.leaseId,
-  limit: 20,
-});
-// Returns: { messages: [...] }
-// Step 4: Renew lease when needed
-const renewal = await mcp.callTool("chat_renew_lease", {
-  leaseId: joinResult.leaseId,
-});
-// Returns: { leaseId: "new-lease-id...", leaseExpiresAt: "..." }
-```
-**Key Benefits:**
-- No shell scripting or process management required
-- WebSocket connections maintained automatically by MCP server
-- Messages cached in memory for quick retrieval
-- Simple polling model for agents
-### Private Key Configuration
-Private keys can be configured in three ways (priority order):
-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`
-**Security Recommendation:** Use the environment variable in your MCP client config rather than passing it in each tool call.
-### Example MCP Tool Usage
-Once configured, AI assistants can use the tools like this:
-```
-create_token(name="Moon Token", symbol="MOON", websiteUrl="https://moon.com")
-buy_token(identifier="0x1234...", amount="0.20")
-token_info(identifier="MOON")
-list_tokens(sort="mcap", limit=10)
-check_balance()
+brew tap hathbanger/httpcat
+brew install httpcat
 ```
-### Response Format
+---
-All MCP tools return structured JSON responses matching the CLI's JSON output format:
-**Success:**
+## Quick Start
-```json
-{
-  "success": true,
-  "operation": "tool_name",
-  "data": {
-    // Tool-specific data
-  }
-}
-```
+### Setup
-**Error:**
+Run `httpcat` to create your wallet:
-```json
-{
-  "success": false,
-  "operation": "tool_name",
-  "error": {
-    "message": "Error message",
-    "code": 1,
-    "details": {}
-  }
-}
+```bash
+httpcat
 ```
-### 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
-- **Always Up-to-Date** - Using `npx` ensures you always get the latest version
-- **Zero Configuration** - Works out of the box with standard MCP clients
+Your seed phrase is generated locally and never transmitted to any server.
-## Advanced Usage
+### Use Entrypoints
-### Environment Management
-httpcat supports multiple environments (local, sepolia, etc.) to easily switch between different agent deployments.
+```bash
+# Swap tokens via DEX aggregator
+httpcat swap USDC WETH 1.0
-#### List Environments
+# Launchpad operations
+httpcat launchpad list
+httpcat launchpad create "My Token" "MTK"
+httpcat launchpad buy MTK 0.10
+httpcat launchpad positions
-```bash
-httpcat env list
+# Call any x402 endpoint
+httpcat call https://api.example.com/endpoint --method POST --body '{"data": "value"}'
 ```
-Shows all available environments with their agent URLs and networks.
+### MCP Integration
-#### Switch Environment
+Give your agent claws:
 ```bash
-# Switch to local environment
-httpcat env use local
-# Switch to sepolia environment
-httpcat env use sepolia
+httpcat mcp install
 ```
-#### Show Current Environment
+Your agent can now use all CLI commands as MCP tools. One integration, access to everything.
-```bash
-httpcat env show
-```
+---
-#### Add Custom Environment
-```bash
-# Add a custom environment
-httpcat env add production http://production-agent:8787 -n base
+## Commands
-# Switch to it
-httpcat env use production
-```
+### Launchpad
-#### Update Environment
+- `launchpad list` — List all tokens (FREE)
+- `launchpad info <identifier>` — Get token information (FREE)
+- `launchpad buy <identifier> <amount>` — Buy tokens from bonding curve
+- `launchpad sell <identifier> <amount>` — Sell tokens to bonding curve ($0.01)
+- `launchpad positions` — Get token positions (FREE)
-```bash
-# Update existing environment URL
-httpcat env update local http://localhost:8788
+**Shortcuts:** `list`, `info`, `buy`, `sell`, `positions`
-# Update environment with different network
-httpcat env update production http://prod-agent:8787 -n base
-```
+### Entrypoints
-Updates an existing environment's agent URL and optionally its network.
+- `swap <tokenIn> <tokenOut> <amount>` — Execute swaps via DEX aggregator
+- `call <url> [options]` — Call any x402-protected endpoint
-#### Predefined Environments
+### Tools
-- **local** - `http://localhost:8787` (eip155:84532)
-- **sepolia** - `https://agent.402.cat` (eip155:84532)
+- `rpc` — JSON-RPC proxy for blockchain calls ($0.05)
-#### Environment Priority
+### Infrastructure
-Agent URL resolution priority:
+- `accounts` — List all configured accounts
+- `mcp install [llm-name]` — Install MCP server for AI assistants
+- `mcp start` — Start MCP server
+- `config` — Configure httpcat settings
+- `use <value>` — Switch account or environment
-1. `HTTPCAT_AGENT_URL` environment variable
-2. Current environment's agent URL
-3. Config file `agentUrl` setting
-4. Default value
+**Shortcuts:** `balances`, `health`, `transactions`
-### Environment Variables
+---
-Override config with environment variables:
+## x402 Protocol
-```bash
-# Private key (most secure - doesn't save to config)
-export HTTPCAT_PRIVATE_KEY=0x1234567890abcdef...
+httpcat is built on the [x402 protocol](https://x402.org) — HTTP-native micropayments that work without middleware or wallets.
-# Agent URL (overrides environment)
-export HTTPCAT_AGENT_URL=http://custom-agent:8787
+**How it works:**
-# Run commands
-httpcat create "My Token" "MTK"
-```
+1. Make HTTP request to x402 endpoint
+2. Receive `402 Payment Required` response
+3. Generate payment signature using your private key
+4. Retry request with `PAYMENT-SIGNATURE` header
+5. Endpoint verifies payment and processes request
-### Private Key Command-Line Option
+**No middleware required.** The protocol is built into HTTP. No wallet management. No complex setup. Just HTTP requests with payment headers.
-You can also pass the private key directly via command-line flag (highest priority):
+httpcat handles all of this automatically. You just make requests.
-```bash
-# Private key priority: CLI flag > Environment variable > Config file
-httpcat -k 0x1234567890abcdef... create "My Token" "MTK"
-httpcat -k 0x1234567890abcdef... -j buy 0x1234... 0.20
-```
+---
-**Note:** The `--private-key` flag takes precedence over environment variables and config file settings.
+## MCP Server
-### Custom Network Configuration
+The MCP server exposes all CLI commands as tools for AI assistants:
 ```bash
-# Switch to mainnet
-httpcat config -S network=base
-httpcat config -S agentUrl=http://production-url:8787
-# Or in interactive mode
-httpcat> network base
+httpcat mcp install
 ```
-### Disable ASCII Art
+Or start manually:
 ```bash
-# Globally
-httpcat config --set preferences.enableAsciiArt=false
-# Per session
-httpcat --no-art
+httpcat mcp start
 ```
-## Configuration File
-Config is stored at `~/.config/httpcat/config.json`:
+**Configuration:**
 ```json
 {
-  "encryptedPrivateKey": "...",
-  "encryptedSeedPhrase": "...",
-  "password": "hashed_password",
-  "passwordTimeoutMinutes": 15,
-  "accounts": [
-    {
-      "index": 0,
-      "type": "custom",
-      "address": "0x...",
-      "label": "Main Account"
-    },
-    {
-      "index": 1,
-      "type": "seed",
-      "address": "0x..."
-    }
-  ],
-  "activeAccountIndex": 0,
-  "network": "eip155:84532",
-  "agentUrl": "https://agent.402.cat",
-  "facilitatorUrl": "https://facilitators.x402scan.com",
-  "defaultMaxPayment": "10.00",
-  "environment": "sepolia",
-  "environments": {
-    "local": {
-      "name": "local",
-      "agentUrl": "http://localhost:8787",
-      "network": "base-sepolia"
-    },
-    "sepolia": {
-      "name": "sepolia",
-      "agentUrl": "https://agent.402.cat",
-      "network": "base-sepolia"
+  "mcpServers": {
+    "httpcat": {
+      "command": "npx",
+      "args": ["-y", "httpcat-cli", "mcp", "start"]
     }
-  },
-  "preferences": {
-    "enableAsciiArt": true,
-    "colorOutput": true,
-    "verboseLogging": false
-  },
-  "aiAgent": {
-    "provider": "openai",
-    "apiKey": "encrypted_key_here",
-    "model": "gpt-4"
   }
 }
 ```
-**Security Features:**
-- **Password Protection**: Set a password during setup to encrypt your private keys and seed phrase
-- **Session Management**: Configurable timeout (default: 15 minutes via `passwordTimeoutMinutes`)
-- **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
-**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
-- **For production use**:
-  - Enable password protection during setup for encryption
-  - Use `HTTPCAT_PRIVATE_KEY` environment variable for additional security
-  - Set restrictive file permissions: `chmod 600 ~/.config/httpcat/config.json`
-  - Use a dedicated wallet with limited funds
-## How It Works
-### x402 Payment Protocol
-httpcat uses the [x402 protocol V2](https://x402.org) for micropayments:
-1. **Request** - CLI makes a request to the agent
-2. **402 Response** - Agent returns payment requirements
-3. **Payment** - CLI automatically transfers USDC
-4. **Verification** - Agent verifies payment via facilitator
-5. **Response** - Agent processes request and returns result
-All of this happens automatically - you just see the result!
-### Bonding Curve
-Tokens use a bonding curve pricing mechanism:
-- Price increases as more tokens are bought
-- Price decreases as tokens are sold
-- 1% fee on all buy/sell operations
-- Automatic graduation at market cap threshold
-- Graduated tokens get Uniswap V2 liquidity
-## Troubleshooting
-### "No private key configured"
-Run the setup wizard:
-```bash
-httpcat config
-```
-Or use environment variable:
-```bash
-export HTTPCAT_PRIVATE_KEY=0x...
-```
-### "Insufficient USDC balance"
-Make sure you have enough USDC in your wallet:
-- Test mode (Base Sepolia / eip155:84532): Get testnet USDC from faucets
-- Production (base): Bridge USDC to Base
-You also need ETH for gas fees.
-### "Request failed with status 402"
-The payment verification failed. Check:
-1. Wallet has sufficient USDC and ETH
-2. Network is correct (eip155:84532 for testnet vs eip155:8453 for mainnet)
-3. Agent URL is reachable
-4. Facilitator URL is correct
-### Connection errors
-Verify the agent is running:
-```bash
-httpcat health
-```
-Check your config:
-```bash
-httpcat config --show
-```
-### 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
-```bash
-# Setup
-httpcat config
-# Check your wallet balances
-httpcat balances
-# Create a token
-httpcat create "Moon Cat" "MOON" -w --website https://mooncat.io
+**Note:** Private key is NOT included in MCP config — the server reads from `~/.config/httpcat/config.json` automatically.
-# Buy tokens
-httpcat buy 0x1234... 5
+Your agent can now:
-# Check your position
-httpcat info 0x1234...
+- Use entrypoints (swap, launchpad, rpc)
+- Call any x402 endpoint
+- Discover and compose services
+- Build capabilities
-# Get all your positions with comprehensive info
-httpcat positions
+---
-# Sell half when profitable
-httpcat sell 0x1234... 50%
+## Global Options
-# List all your tokens (shows positions)
-httpcat list
-```
+- `-j, --json` — JSON output for scripting
+- `-q, --quiet` — Minimal output
+- `-v, --verbose` — Verbose errors
+- `--no-art` — Disable ASCII art
+- `-k, --private-key <key>` — Override private key
+- `-a, --account <index>` — Use specific account
-### Scripted Trading Bot
+---
-```bash
-#!/bin/bash
+## Documentation
-TOKEN_ADDRESS="0x1234567890abcdef1234567890abcdef12345678"
+For detailed documentation, entrypoint reference, and deployment guides:
-# Monitor and trade
-while true; do
-  INFO=$(httpcat -j info $TOKEN_ADDRESS)
-  PROGRESS=$(echo $INFO | jq -r '.data.graduationProgress')
+**📖 [docs.402.cat](https://docs.402.cat)**
-  # Buy if close to graduation
-  if (( $(echo "$PROGRESS > 90" | bc -l) )); then
-    httpcat -q buy $TOKEN_ADDRESS 5
-  fi
+---
-  sleep 60
-done
-```
+## The Foundation
-## Development
+httpcat is built on three primitives:
-```bash
-# Install dependencies
-yarn install
+1. **x402 Protocol** — HTTP-native micropayments, no middleware
+2. **Entrypoint Registry** — Discoverable, composable services
+3. **Automatic Payments** — Payment signatures handled automatically
-# Build
-yarn build
+This is the infrastructure that lets agents transact without wallets, discover services without APIs, and build capabilities by composing entrypoints.
-# Watch mode
-yarn dev
+**Money is the alignment mechanism.** An agent with a budget has to prioritize. Every action costs something. Run out of funds, you stop. Make bad decisions, you go broke.
-# Link for local testing
-yarn link
+The constraint is what makes it work.
-# Test
-httpcat --version
-```
+---
 ## License
@@ -1792,6 +234,7 @@ MIT
 ## Support
-- Report issues: https://github.com/hathbanger/httpcat-cli/issues
-- httpcat agent: https://agent.402.cat
-- x402 protocol: https://x402.org
+- Issues: https://github.com/hathbanger/httpcat-cli/issues
+- Agent: https://agent-test.402.cat
+- Protocol: https://x402.org
+- Docs: https://docs.402.cat