httpcat-cli 0.2.11-rc.1 → 0.2.11-rc.2

package/README.md

@@ -7,7 +7,7 @@ httpcat is a full-featured CLI tool that provides both interactive (with ASCII a
 ## Features
 
 - 🎨 **Interactive Shell** - Beautiful REPL with ASCII art cats and colored output
-- 🤖 **Headless Mode** - JSON output for scripting and LLM/agent integration
+- 🐱 **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`
@@ -125,16 +125,23 @@ httpcat> help
 Available Commands:
 
   create <name> <symbol>          Create a new token
-  buy <id|name|symbol> <amount>   Buy tokens ($0.05, $0.10, or $0.20)
+  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                       Get all your positions with comprehensive info
+  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 and USDC)
+  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
 
@@ -173,6 +180,38 @@ httpcat> buy 0x789abcd... 0.20
 [🐱==>                  ] 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
@@ -184,6 +223,7 @@ Create a new token on the bonding curve.
 ```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:**
@@ -191,12 +231,12 @@ httpcat> create "My Token" "MTK" --photo https://example.com/photo.png
 ```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>` - Token photo URL
-- `-b, --banner <url>` - Banner image URL
+- `-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
@@ -246,6 +286,9 @@ httpcat buy MTK 0.10 -r 10 -d 500
 
 - Test mode (base-sepolia): `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)
 
@@ -361,10 +404,17 @@ httpcat> positions
 
 ```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:
@@ -385,6 +435,98 @@ Portfolio summary:
 
 **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.
@@ -407,12 +549,64 @@ httpcat balances -k 0x...
 - 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.
@@ -461,6 +655,27 @@ httpcat -j -f stream-json chat MTK  # Structured JSON input
 - 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)
@@ -471,6 +686,64 @@ httpcat -j -f stream-json chat MTK  # Structured JSON input
 
 **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.
@@ -922,8 +1195,7 @@ Create a new token on the bonding curve.
 
 - `name` (string, required) - Token name (e.g., "My Token")
 - `symbol` (string, required) - Token symbol/ticker (3-10 characters)
-- `photoUrl` (string, optional) - Photo URL for token logo
-- `bannerUrl` (string, optional) - Banner image URL
+- `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)
 
@@ -1214,6 +1486,18 @@ httpcat env add production http://production-agent:8787 -n base
 httpcat env use production
 ```
 
+#### Update Environment
+
+```bash
+# Update existing environment URL
+httpcat env update local http://localhost:8788
+
+# Update environment with different network
+httpcat env update production http://prod-agent:8787 -n base
+```
+
+Updates an existing environment's agent URL and optionally its network.
+
 #### Predefined Environments
 
 - **local** - `http://localhost:8787` (base-sepolia)
@@ -1282,24 +1566,73 @@ Config is stored at `~/.config/httpcat/config.json`:
 
 ```json
 {
-  "privateKey": "0x...",
+  "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": "base-sepolia",
   "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"
+    }
+  },
   "preferences": {
     "enableAsciiArt": true,
     "colorOutput": true,
     "verboseLogging": false
+  },
+  "aiAgent": {
+    "provider": "openai",
+    "apiKey": "encrypted_key_here",
+    "model": "gpt-4"
   }
 }
 ```
 
-**Security Note:** The private key is stored in plain text. For production use, consider:
+**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:**
 
-- Using `HTTPCAT_PRIVATE_KEY` environment variable instead
-- Setting restrictive file permissions: `chmod 600 ~/.config/httpcat/config.json`
-- Using a dedicated wallet with limited funds
+- **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
 

package/bun.lock

@@ -5,6 +5,7 @@
     "": {
       "name": "httpcat-cli",
       "dependencies": {
+        "@ax-llm/ax": "^15.1.1",
         "@modelcontextprotocol/sdk": "^1.23.0",
         "@scure/bip32": "^2.0.1",
         "@scure/bip39": "^2.0.1",
@@ -43,6 +44,8 @@
   "packages": {
     "@adraffy/ens-normalize": ["@adraffy/ens-normalize@1.11.1", "", {}, "sha512-nhCBV3quEgesuf7c7KYfperqSS14T8bYuvJ8PcLJp6znkZpFc0AuW4qBtr8eKVyPPe/8RSr7sglCWPU5eaxwKQ=="],
 
+    "@ax-llm/ax": ["@ax-llm/ax@15.1.1", "", { "dependencies": { "@opentelemetry/api": "^1.9.0", "dayjs": "^1.11.13" } }, "sha512-gKd0m+Fuw6xeAB+nAOVtfhLaGBjYhenQCOH7WwpmkP6bfbaAJ0BB0yci7alomjIvMDjv5j93ejCexQvti/FQZg=="],
+
     "@babel/code-frame": ["@babel/code-frame@7.27.1", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.27.1", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg=="],
 
     "@babel/compat-data": ["@babel/compat-data@7.28.5", "", {}, "sha512-6uFXyCayocRbqhZOB+6XcuZbkMNimwfVGFji8CTZnCzOHVGvDqzvitu1re2AU5LROliz7eQPhB8CpAMvnx9EjA=="],
@@ -281,6 +284,8 @@
 
     "@noble/hashes": ["@noble/hashes@2.0.1", "", {}, "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw=="],
 
+    "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
+
     "@paulmillr/qr": ["@paulmillr/qr@0.2.1", "", {}, "sha512-IHnV6A+zxU7XwmKFinmYjUcwlyK9+xkG3/s9KcQhI9BjQKycrJ1JRO+FbNYPwZiPKW3je/DR0k7w8/gLa5eaxQ=="],
 
     "@pkgr/core": ["@pkgr/core@0.2.9", "", {}, "sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA=="],