httpcat-cli 0.0.1

package/README.md

@@ -0,0 +1,796 @@
+# httpcat CLI
+
+> 🐱 Command-line interface for interacting with the httpcat agent - create, buy, and sell tokens with x402 payments
+
+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.
+
+## Features
+
+- 🎨 **Interactive Shell** - Beautiful REPL with ASCII art cats and colored output
+- 🤖 **Headless Mode** - JSON output for scripting and LLM/agent 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
+
+### From Source
+
+```bash
+cd httpcat-cli
+yarn install
+yarn build
+yarn link
+```
+
+### Global Install (when published)
+
+```bash
+yarn global add httpcat-cli
+```
+
+## 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** - `base-sepolia` (testnet) or `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: base-sepolia
+🌐 Agent: http://209.97.152.182:8787
+
+httpcat> help
+Available Commands:
+
+  create <name> <symbol>          Create a new token
+  buy <tokenId> <amount>          Buy tokens ($1, $2, or $5)
+  sell <tokenId> <amount|all>     Sell tokens
+  info <tokenId>                  Get token information
+  list [--sort mcap|created]      List all tokens
+  health                          Check agent health
+  config [--show|--set|--reset]   Manage configuration
+  network <name>                  Switch network
+  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)                    │
+├─────────────────────────────────────────┤
+│ Token ID:  abc123-4567-89ab-cdef-...    │
+│ Address:   0x789abcd...                 │
+│ Supply:    1,000,000,000 MEOW           │
+│ Status:    Active                       │
+└─────────────────────────────────────────┘
+
+httpcat> buy abc123-4567-89ab-cdef-0123456789ab 5
+
+💰 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!
+```
+
+## 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
+```
+
+**CLI:**
+
+```bash
+httpcat create "My Token" "MTK"
+httpcat create "My Token" "MTK" --photo https://example.com/photo.png --website https://mytoken.io
+```
+
+**Options:**
+
+- `--photo <url>` - Token photo URL
+- `--banner <url>` - Banner image URL
+- `--website <url>` - Website URL
+
+**Cost:** $0.01 USDC
+
+### Buy Tokens
+
+Purchase tokens from the bonding curve.
+
+**Interactive:**
+
+```bash
+httpcat> buy abc123-... 5
+httpcat> buy "My Token" 2
+httpcat> buy MTK 1
+```
+
+**CLI:**
+
+```bash
+httpcat buy abc123-4567-89ab-cdef-0123456789ab 5
+httpcat buy "My Token" 2
+httpcat buy MTK 1
+```
+
+**Token Identifier:**
+
+- Token ID (UUID): `abc123-4567-89ab-cdef-0123456789ab`
+- Token name: `"My Token"` (use quotes if it contains spaces)
+- Token symbol: `MTK` (case-insensitive)
+
+**Amounts:**
+
+- Test mode (base-sepolia): `1`, `2`, or `5` USDC
+- Production (base): `50`, `100`, or `200` USDC
+
+**Cost:** Amount + 1% fee (e.g., $5.05 for $5 purchase)
+
+### Sell Tokens
+
+Sell tokens back to the bonding curve.
+
+**Interactive:**
+
+```bash
+httpcat> sell abc123-... 1000        # Sell 1000 tokens
+httpcat> sell "My Token" 50%         # Sell 50% of holdings
+httpcat> sell MTK all                # Sell all tokens
+```
+
+**CLI:**
+
+```bash
+httpcat sell abc123-4567-89ab-cdef-0123456789ab 1000
+httpcat sell "My Token" 50%
+httpcat sell MTK all
+```
+
+**Token Identifier:**
+
+- Token ID (UUID), 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 abc123-...
+httpcat> info "My Token"
+httpcat> info MTK
+```
+
+**CLI:**
+
+```bash
+httpcat info abc123-4567-89ab-cdef-0123456789ab
+httpcat info "My Token"
+httpcat info MTK
+```
+
+**Token Identifier:**
+
+- Token ID (UUID), 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:**
+
+- `--sort <field>` - Sort by `mcap`, `created`, or `name` (default: `mcap`)
+- `--limit <n>` - Items per page (default: 20, max: 100)
+- `--page <n>` - Page number (default: 1)
+
+**Cost:** $0.0001 USDC
+
+### Health Check
+
+Check if the agent is running.
+
+**Interactive:**
+
+```bash
+httpcat> health
+```
+
+**CLI:**
+
+```bash
+httpcat health
+```
+
+**Cost:** $0.0001 USDC (or 402 response)
+
+### Configuration
+
+Manage your httpcat configuration.
+
+**Interactive:**
+
+```bash
+httpcat> config --show              # Show current config
+httpcat> config --set network=base  # Update a setting
+httpcat> config --reset             # Re-run setup wizard
+```
+
+**CLI:**
+
+```bash
+httpcat config                    # Run setup wizard
+httpcat config --show             # Show current config (JSON)
+httpcat config --set network=base # Update a setting
+```
+
+## Headless Mode (JSON Output)
+
+Perfect for scripting, automation, or LLM/agent integration.
+
+### JSON Output
+
+Add `--json` flag to any command:
+
+```bash
+$ httpcat --json 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
+}
+```
+
+**Health Check (`health`)**
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2025-11-22T10:30:00.000Z",
+  "agent": "http://209.97.152.182:8787"
+}
+```
+
+**Version (`--version --json`)**
+
+```json
+{
+  "name": "httpcat-cli",
+  "version": "0.1.0"
+}
+```
+
+### Quiet Mode
+
+Minimal output, only exit codes:
+
+```bash
+$ httpcat --quiet buy abc123-... 5
+$ echo $?
+0
+```
+
+**Exit Codes:**
+
+- `0` - Success
+- `1` - General error
+- `2` - Configuration error
+- `3` - Network error
+- `4` - Insufficient funds
+- `5` - Validation error
+
+### Example: LLM/Agent Integration
+
+```bash
+#!/bin/bash
+
+# Create a token
+RESULT=$(httpcat --json create "AI Token" "AI")
+TOKEN_ID=$(echo $RESULT | jq -r '.data.tokenId')
+
+# Buy some tokens
+httpcat --json buy $TOKEN_ID 5
+
+# Get current info
+httpcat --json info $TOKEN_ID
+
+# Sell 50% if profitable
+INFO=$(httpcat --json info $TOKEN_ID)
+PNL=$(echo $INFO | jq -r '.data.userPosition.pnl')
+
+if (( $(echo "$PNL > 0" | bc -l) )); then
+  httpcat --json sell $TOKEN_ID 50%
+fi
+```
+
+## Advanced Usage
+
+### Environment Management
+
+httpcat supports multiple environments (local, sepolia, etc.) to easily switch between different agent deployments.
+
+#### List Environments
+
+```bash
+httpcat env list
+```
+
+Shows all available environments with their agent URLs and networks.
+
+#### Switch Environment
+
+```bash
+# Switch to local environment
+httpcat env use local
+
+# Switch to sepolia environment
+httpcat env use sepolia
+```
+
+#### Show Current Environment
+
+```bash
+httpcat env show
+```
+
+#### Add Custom Environment
+
+```bash
+# Add a custom environment
+httpcat env add production http://production-agent:8787 --network base
+
+# Switch to it
+httpcat env use production
+```
+
+#### Predefined Environments
+
+- **local** - `http://localhost:8787` (base-sepolia)
+- **sepolia** - `http://209.97.152.182:8787` (base-sepolia)
+
+#### Environment Priority
+
+Agent URL resolution priority:
+
+1. `HTTPCAT_AGENT_URL` environment variable
+2. Current environment's agent URL
+3. Config file `agentUrl` setting
+4. Default value
+
+### Environment Variables
+
+Override config with environment variables:
+
+```bash
+# Private key (most secure - doesn't save to config)
+export HTTPCAT_PRIVATE_KEY=0x1234567890abcdef...
+
+# Agent URL (overrides environment)
+export HTTPCAT_AGENT_URL=http://custom-agent:8787
+
+# Run commands
+httpcat create "My Token" "MTK"
+```
+
+### Private Key Command-Line Option
+
+You can also pass the private key directly via command-line flag (highest priority):
+
+```bash
+# Private key priority: CLI flag > Environment variable > Config file
+httpcat --private-key 0x1234567890abcdef... create "My Token" "MTK"
+httpcat --private-key 0x1234567890abcdef... --json buy abc123-... 5
+```
+
+**Note:** The `--private-key` flag takes precedence over environment variables and config file settings.
+
+### Custom Network Configuration
+
+```bash
+# Switch to mainnet
+httpcat config --set network=base
+httpcat config --set agentUrl=http://production-url:8787
+
+# Or in interactive mode
+httpcat> network base
+```
+
+### Disable ASCII Art
+
+```bash
+# Globally
+httpcat config --set preferences.enableAsciiArt=false
+
+# Per session
+httpcat --no-art
+```
+
+## Configuration File
+
+Config is stored at `~/.config/httpcat/config.json`:
+
+```json
+{
+  "privateKey": "0x...",
+  "network": "base-sepolia",
+  "agentUrl": "http://209.97.152.182:8787",
+  "facilitatorUrl": "https://facilitators.x402scan.com",
+  "defaultMaxPayment": "10.00",
+  "preferences": {
+    "enableAsciiArt": true,
+    "colorOutput": true,
+    "verboseLogging": false
+  }
+}
+```
+
+**Security Note:** The private key is stored in plain text. For production use, consider:
+
+- Using `HTTPCAT_PRIVATE_KEY` environment variable instead
+- Setting restrictive file permissions: `chmod 600 ~/.config/httpcat/config.json`
+- Using a dedicated wallet with limited funds
+
+## How It Works
+
+### x402 Payment Protocol
+
+httpcat uses the [x402 protocol](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): 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 (base-sepolia vs base)
+3. Agent URL is reachable
+4. Facilitator URL is correct
+
+### Connection errors
+
+Verify the agent is running:
+
+```bash
+httpcat health
+```
+
+Check your config:
+
+```bash
+httpcat config --show
+```
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# Setup
+httpcat config
+
+# Create a token
+httpcat create "Moon Cat" "MOON" --website https://mooncat.io
+
+# Buy tokens
+httpcat buy <tokenId> 5
+
+# Check your position
+httpcat info <tokenId>
+
+# Sell half when profitable
+httpcat sell <tokenId> 50%
+
+# List all your tokens (shows positions)
+httpcat list
+```
+
+### Scripted Trading Bot
+
+```bash
+#!/bin/bash
+
+TOKEN_ID="abc123-..."
+
+# Monitor and trade
+while true; do
+  INFO=$(httpcat --json info $TOKEN_ID)
+  PROGRESS=$(echo $INFO | jq -r '.data.graduationProgress')
+
+  # Buy if close to graduation
+  if (( $(echo "$PROGRESS > 90" | bc -l) )); then
+    httpcat --quiet buy $TOKEN_ID 5
+  fi
+
+  sleep 60
+done
+```
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build
+yarn build
+
+# Watch mode
+yarn dev
+
+# Link for local testing
+yarn link
+
+# Test
+httpcat --version
+```
+
+## License
+
+MIT
+
+## Support
+
+- Report issues: https://github.com/your-org/httpcat-cli/issues
+- httpcat agent: http://209.97.152.182:8787
+- x402 protocol: https://x402.org