clawncher 0.1.0

package/README.md

@@ -0,0 +1,494 @@
+# clawncher
+
+Command-line interface for [Clawncher](https://clawn.ch/er) - deploy tokens on Base with Uniswap V4 pools, MEV protection, and configurable fee distribution.
+
+## Installation
+
+```bash
+npm install -g clawncher
+```
+
+## Quick Start
+
+```bash
+# Configure your private key
+clawncher config --private-key YOUR_PRIVATE_KEY
+
+# Deploy a new token
+clawncher deploy --name "My Token" --symbol MYTKN
+
+# Show contract addresses
+clawncher addresses
+
+# Get token info from chain
+clawncher info 0xTokenAddress
+```
+
+## Commands
+
+### Deploy
+
+Deploy a new token on Base with Uniswap V4 pool:
+
+```bash
+# Basic deployment
+clawncher deploy --name "My Token" --symbol MYTKN
+
+# With image and description
+clawncher deploy --name "My Token" --symbol MYTKN \
+  --image "https://example.com/logo.png" \
+  --description "A great token"
+
+# Custom fee recipient
+clawncher deploy --name "My Token" --symbol MYTKN --recipient 0x1234...
+
+# 1% LP fee: 80% to deployer, 20% protocol
+# Change fee preference to receive in WETH instead:
+clawncher deploy --name "My Token" --symbol MYTKN --fee-preference Paired
+
+# With vault allocation
+clawncher deploy --name "My Token" --symbol MYTKN \
+  --vault-percent 10 \
+  --vault-lockup 30 \
+  --vault-recipient 0x1234...
+
+# With dev buy (instant purchase at launch)
+clawncher deploy --name "My Token" --symbol MYTKN \
+  --dev-buy 0.1 \
+  --dev-buy-recipient 0x1234...
+
+# Simulate deployment without sending transaction
+clawncher deploy --name "My Token" --symbol MYTKN --dry-run
+
+# Deploy to mainnet
+clawncher deploy --name "My Token" --symbol MYTKN --network mainnet
+
+# Use custom RPC
+clawncher deploy --name "My Token" --symbol MYTKN --rpc https://my-rpc.com
+
+# JSON output
+clawncher deploy --name "My Token" --symbol MYTKN --json
+```
+
+### Info
+
+Get token info directly from the blockchain:
+
+```bash
+# Get token info
+clawncher info 0xTokenAddress
+
+# Specify network
+clawncher info 0xTokenAddress --network mainnet
+
+# JSON output
+clawncher info 0xTokenAddress --json
+```
+
+### Fees
+
+Check and manage trading fees:
+
+```bash
+# Check claimable fees (on-chain)
+clawncher fees check 0xWalletAddress -t 0xToken1,0xToken2
+
+# Check available fees (via API)
+clawncher fees available 0xWalletAddress
+
+# Claim fees
+clawncher fees claim 0xToken... --network mainnet --private-key 0x...
+
+# Claim everything (fees + vault)
+clawncher fees claim 0xToken... --vault
+
+# Batch claim across multiple tokens
+clawncher fees batch-claim 0xToken1 0xToken2 --fee-owner 0x...
+```
+
+### Portfolio
+
+View token portfolio for a wallet:
+
+```bash
+# Check specific tokens
+clawncher portfolio 0xWallet --tokens 0xToken1,0xToken2
+
+# Auto-discover deployed tokens
+clawncher portfolio 0xWallet --discover
+```
+
+### Watch
+
+Monitor live deployments:
+
+```bash
+# Watch all new deployments
+clawncher watch
+
+# Filter by admin and set history depth
+clawncher watch --admin 0xAdmin --history 1000
+```
+
+### Config
+
+Manage CLI configuration:
+
+```bash
+# Show current configuration
+clawncher config --show
+
+# Set default network
+clawncher config --network mainnet
+
+# Set private key
+clawncher config --private-key 0x...
+
+# Set custom RPC URLs
+clawncher config --rpc-sepolia https://my-sepolia-rpc.com
+clawncher config --rpc-mainnet https://my-mainnet-rpc.com
+
+# Clear all configuration
+clawncher config --clear
+```
+
+Configuration is stored in `~/.clawncher/config.json`.
+
+### Addresses
+
+Show contract addresses for a network:
+
+```bash
+# Show mainnet addresses
+clawncher addresses --network mainnet
+
+# Show sepolia addresses
+clawncher addresses --network sepolia
+
+# JSON output
+clawncher addresses --json
+```
+
+### API Commands
+
+These commands fetch data from the Clawnch API:
+
+```bash
+# List all tokens
+clawncher tokens
+clawncher tokens --symbol DOG --limit 10
+
+# View launch history
+clawncher launches
+clawncher launches --agent "MyAgent" --source moltbook
+
+# Get market statistics
+clawncher stats
+```
+
+### Swap
+
+Execute token swaps via 0x aggregation:
+
+```bash
+# Get indicative price (read-only)
+clawncher swap price --sell ETH --buy 0xToken... --amount 0.01
+
+# Execute a swap
+clawncher swap exec --sell ETH --buy 0xToken... --amount 0.01 \
+  --network mainnet --private-key 0x...
+
+# Swap ERC20 for ETH
+clawncher swap exec --sell 0xToken... --buy ETH --amount 1000000 \
+  --slippage 200 --network mainnet
+
+# JSON output
+clawncher swap price --sell ETH --buy 0xToken... --amount 0.01 --json
+```
+
+Swaps are routed through the Clawnch API — no API key needed.
+
+### Liquidity
+
+Manage Uniswap V3/V4 liquidity positions:
+
+```bash
+# List V3 positions for a wallet
+clawncher liquidity positions 0xWallet...
+
+# Create new V3 position
+clawncher liquidity mint \
+  --token0 0xTokenA --token1 0xTokenB \
+  --fee 3000 --tick-lower -887220 --tick-upper 887220 \
+  --amount0 1.0 --amount1 2000 \
+  --network mainnet --private-key 0x...
+
+# Add liquidity to position
+clawncher liquidity add --id 123456 \
+  --amount0 0.5 --amount1 1000 \
+  --network mainnet --private-key 0x...
+
+# Remove 50% of liquidity
+clawncher liquidity remove --id 123456 --percent 50 \
+  --network mainnet --private-key 0x...
+
+# Remove 100% and burn NFT
+clawncher liquidity remove --id 123456 --percent 100 --burn \
+  --network mainnet --private-key 0x...
+
+# View unclaimed fees
+clawncher liquidity fees --id 123456 --network mainnet
+
+# Collect fees
+clawncher liquidity fees --id 123456 --collect \
+  --network mainnet --private-key 0x...
+```
+
+### About
+
+Show Clawncher information and links:
+
+```bash
+clawncher about
+```
+
+## Deploy Options Reference
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--name` | Token name | `--name "My Token"` |
+| `--symbol` | Token symbol | `--symbol MYTKN` |
+| `--image` | Token image URL | `--image "https://..."` |
+| `--description` | Token description | `--description "A great token"` |
+| `--recipient` | Fee recipient address | `--recipient 0x1234...` |
+| `--fee-preference` | Fee token: Clawnch (default), Paired, Both | `--fee-preference Paired` |
+| `--vault-percent` | Vault allocation (1-90%) | `--vault-percent 10` |
+| `--vault-lockup` | Vault lockup in days | `--vault-lockup 30` |
+| `--vault-vesting` | Vault vesting in days | `--vault-vesting 60` |
+| `--vault-recipient` | Vault recipient address | `--vault-recipient 0x...` |
+| `--dev-buy` | ETH amount for instant dev buy | `--dev-buy 0.1` |
+| `--dev-buy-recipient` | Dev buy recipient address | `--dev-buy-recipient 0x...` |
+| `--no-vanity` | Disable vanity address mining | `--no-vanity` |
+| `--dry-run` | Simulate deployment without sending transaction | `--dry-run` |
+| `--network` | Network (sepolia/mainnet) | `--network mainnet` |
+| `--rpc` | Custom RPC URL | `--rpc https://...` |
+| `--json` | Output as JSON | `--json` |
+
+### Vanity Addresses
+
+Vanity addresses are handled by Clanker's remote service. Use `--no-vanity` to disable.
+
+### Dev Buy
+
+**Dev Buy** (`--dev-buy`): Instantly purchases tokens at launch using ETH. Tokens are sent directly to the recipient with no lockup.
+
+## Swap Options Reference
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--sell` | Token to sell (address or `ETH`) | `--sell ETH` |
+| `--buy` | Token to buy (address or `ETH`) | `--buy 0x...` |
+| `--amount` | Amount to sell (human-readable) | `--amount 0.01` |
+| `--slippage` | Max slippage in bps (default: 100 = 1%) | `--slippage 200` |
+| `--network` | Network (mainnet/sepolia) | `--network mainnet` |
+| `--private-key` | Private key (for exec) | `--private-key 0x...` |
+| `--json` | JSON output | `--json` |
+
+## Liquidity Options Reference
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--id` | Position NFT token ID | `--id 123456` |
+| `--token0` | Token 0 address (for mint) | `--token0 0x...` |
+| `--token1` | Token 1 address (for mint) | `--token1 0x...` |
+| `--fee` | Fee tier (for mint) | `--fee 3000` |
+| `--tick-lower` | Lower tick (for mint) | `--tick-lower -887220` |
+| `--tick-upper` | Upper tick (for mint) | `--tick-upper 887220` |
+| `--amount0` | Token 0 amount (human-readable) | `--amount0 1.0` |
+| `--amount1` | Token 1 amount (human-readable) | `--amount1 2000` |
+| `--percent` | % to remove (for remove) | `--percent 50` |
+| `--burn` | Burn NFT after 100% remove | `--burn` |
+| `--collect` | Collect fees (for fees cmd) | `--collect` |
+
+### Wallet Management
+
+Securely create, import, and manage encrypted wallets:
+
+```bash
+# Create a new wallet (generates mnemonic + encrypts with password)
+clawncher wallet create my-wallet --set-active
+
+# Import from private key
+clawncher wallet import trading --private-key 0x...
+
+# Import from mnemonic
+clawncher wallet import recovery --mnemonic "word1 word2 ... word12"
+
+# List all wallets
+clawncher wallet list
+
+# Set active wallet (used automatically by all commands)
+clawncher wallet use my-wallet
+
+# Check balances
+clawncher wallet balance
+clawncher wallet balance my-wallet --token 0xTokenAddress
+
+# Send ETH
+clawncher wallet send --to 0x... --amount 0.1
+
+# Send ERC20 tokens
+clawncher wallet send --to 0x... --amount 100 --token 0xTokenAddress
+
+# Sign a message
+clawncher wallet sign --message "Hello World"
+
+# Export private key (requires password)
+clawncher wallet export my-wallet --show-mnemonic
+
+# Change wallet password
+clawncher wallet password my-wallet
+
+# Remove a wallet
+clawncher wallet remove my-wallet
+```
+
+#### Wallet Options
+
+| Option | Description |
+|--------|-------------|
+| `--set-active` | Set as active wallet after create/import |
+| `--private-key <key>` | Import from private key hex |
+| `--mnemonic <phrase>` | Import from 12-word mnemonic |
+| `--show-mnemonic` | Show mnemonic on export |
+| `--force` | Skip confirmation on remove |
+| `--token <address>` | ERC20 token for balance/send |
+| `--to <address>` | Recipient for send |
+| `--amount <value>` | Amount for send |
+| `--message <text>` | Message for sign |
+
+#### Security
+
+- Private keys encrypted at rest with AES-256-GCM
+- scrypt KDF (N=2^18, r=8, p=1) for password-to-key derivation
+- Keystore files stored in `~/.clawncher/wallets/` with 0o600 permissions
+- Keys only decrypted on-demand, never cached in memory
+- Mnemonic phrases encrypted alongside private key
+
+## Configuration
+
+### Private Key
+
+You can provide your private key in four ways (in order of precedence):
+
+1. **Command line flag:** `--private-key 0x...`
+2. **Environment variable:** `CLAWNCHER_PRIVATE_KEY=0x...`
+3. **Config file:** `clawncher config --private-key 0x...`
+4. **Active wallet:** `clawncher wallet use my-wallet` (prompts for password)
+
+### Network
+
+Default network is `sepolia`. Change with:
+
+```bash
+clawncher config --network mainnet
+```
+
+Or per-command:
+
+```bash
+clawncher deploy --name "My Token" --symbol MYTKN --network mainnet
+```
+
+### RPC URLs
+
+Default RPCs are used if not configured:
+- Sepolia: `https://sepolia.base.org`
+- Mainnet: `https://mainnet.base.org`
+
+Configure custom RPCs:
+
+```bash
+clawncher config --rpc-sepolia https://my-rpc.com
+clawncher config --rpc-mainnet https://my-rpc.com
+```
+
+Or per-command:
+
+```bash
+clawncher deploy --name "My Token" --symbol MYTKN --rpc https://my-rpc.com
+```
+
+## Verified Agent Launches
+
+Register as a verified agent and deploy tokens via the Clawnch API:
+
+```bash
+# One-time: register agent and receive API key
+clawncher agent register --name "MyAgent" --description "AI trading agent"
+
+# One-time: approve $CLAWNCH token spend
+clawncher agent approve --api-key YOUR_API_KEY
+
+# Check agent status
+clawncher agent status --api-key YOUR_API_KEY
+
+# Deploy a verified token
+clawncher deploy-verified --api-key YOUR_API_KEY --name "My Token" --symbol MYTKN
+```
+
+### Agent Options
+
+| Option | Description |
+|--------|-------------|
+| `--name` | Agent display name |
+| `--description` | Short agent description |
+| `--api-key` | API key from registration |
+| `--api-url` | Clawnch API URL (default: https://clawn.ch) |
+| `--network` | Network: mainnet or sepolia |
+| `--private-key` | Override wallet private key |
+| `--json` | JSON output |
+
+### Deploy-Verified Options
+
+| Option | Description |
+|--------|-------------|
+| `--api-key` | API key from registration |
+| `--name` | Token name |
+| `--symbol` | Token symbol |
+| `--image` | Token image URL |
+| `--description` | Token description |
+| `--recipient` | Fee recipient address |
+| `--fee-preference` | Fee type: Clawnch, Paired, or Both |
+| `--vault-percentage` | Vault percentage (0-100) |
+| `--vault-lockup` | Vault lockup duration (seconds) |
+| `--vault-vesting` | Vault vesting duration (seconds) |
+| `--dev-buy-eth` | Dev buy ETH amount |
+| `--no-vanity` | Disable vanity address |
+| `--json` | JSON output |
+
+## Environment Variables
+
+- `CLAWNCHER_PRIVATE_KEY` - Private key for deployments
+- `CLAWNCHER_API_KEY` - API key for verified agent launches
+- `CLAWNCHER_API_URL` - Override the default API URL (default: https://clawn.ch)
+
+## JSON Output
+
+All commands support `--json` flag for machine-readable output:
+
+```bash
+clawncher deploy --name "My Token" --symbol TEST --json | jq '.tokenAddress'
+clawncher info 0x... --json | jq '.symbol'
+```
+
+## Related
+
+- [Clawncher Website](https://clawn.ch/er)
+- [Agent Skill](https://clawn.ch/er/skill)
+- [Documentation](https://clawn.ch/er/docs)
+- [@clawnch/clawncher-sdk](https://npmjs.com/package/@clawnch/clawncher-sdk) - TypeScript SDK
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Clawncher CLI
+ *
+ * Command-line interface for deploying tokens on Base with Uniswap V4 pools.
+ * Uses ClawnchDeployer from SDK (Clanker-backed infrastructure).
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}