# Clodds User Guide This guide focuses on day-to-day usage: starting the gateway, pairing users, chat commands, and common workflows. ## Quick start ```bash npm install -g clodds clodds onboard ``` The wizard sets up your API key, picks a channel, and starts the gateway. **From source (alternative):** ```bash git clone https://github.com/alsk1992/CloddsBot.git && cd CloddsBot npm install && cp .env.example .env # Add ANTHROPIC_API_KEY to .env npm run build && npm start ``` The gateway listens on `http://127.0.0.1:18789` by default. ## CLI Commands Reference All `clodds` CLI commands: ### Core Commands ```bash clodds start # Start the gateway clodds repl # Interactive REPL mode clodds doctor # System diagnostics and health checks clodds status # Show gateway status clodds endpoints # List all registered endpoints clodds secure [--dry-run] # Server security hardening (Linux) clodds secure audit # Run security audit only ``` ### Pairing Commands ```bash clodds pairing list # List pending pairing requests clodds pairing approve # Approve a pairing request clodds pairing reject # Reject a pairing request clodds pairing users # List paired users clodds pairing set-owner # Set channel owner clodds pairing remove-owner # Remove channel owner clodds pairing owners # List channel owners clodds pairing add # Manually add user clodds pairing remove # Remove user ``` ### Configuration Commands ```bash clodds config get [key] # Get config value or show all clodds config set # Set config value clodds config unset # Remove config value clodds config path # Show config file path ``` ### Model Commands ```bash clodds model list # List available models clodds model default [model] # Get or set default model ``` ### Session Commands ```bash clodds session list # List active sessions clodds session clear [id] # Clear all or specific session ``` ### Cron Commands (Scheduled Tasks) ```bash clodds cron list # List scheduled jobs clodds cron show # Show job details clodds cron enable # Enable a job clodds cron disable # Disable a job clodds cron delete # Delete a job ``` ### User Management Commands ```bash clodds users list # List all users clodds users settings # Show user settings clodds users settings-by-id # Show settings by ID clodds users set-settings [options] # Update settings clodds users set-settings-by-id [options] # Update settings by ID ``` ### Memory Commands ```bash clodds memory list # List user's memories clodds memory search # Search user's memories clodds memory clear # Clear user's memories clodds memory export # Export user's memories ``` ### Hooks Commands ```bash clodds hooks list # List all hooks clodds hooks install # Install a hook from path clodds hooks uninstall # Uninstall a hook clodds hooks enable # Enable a hook clodds hooks disable # Disable a hook clodds hooks trace # Show hook execution trace clodds hooks state get [key] # Get hook state clodds hooks state set # Set hook state clodds hooks state clear [key] # Clear hook state ``` ### MCP (Model Context Protocol) Commands ```bash clodds mcp list # List MCP servers clodds mcp add # Add an MCP server clodds mcp remove # Remove an MCP server clodds mcp test # Test an MCP server clodds mcp stats # Show MCP stats clodds mcp sync # Sync MCP servers ``` ### Permissions Commands ```bash clodds permissions list # List permission rules clodds permissions allow # Allow a command pattern clodds permissions remove # Remove permission rule clodds permissions mode # Set permission mode clodds permissions ask # Set ask mode clodds permissions pending # Show pending approvals clodds permissions approve # Approve pending request clodds permissions deny # Deny pending request ``` ### Usage & Analytics Commands ```bash clodds usage summary # Usage summary clodds usage by-model # Usage breakdown by model clodds usage by-user # Usage breakdown by user clodds usage export # Export usage data clodds usage today # Today's usage ``` ### Credentials Commands ```bash clodds creds test [platform] # Test credentials for a platform ``` ### Skills Commands ```bash clodds skills list # List available skills clodds skills search # Search for skills clodds skills install # Install a skill clodds skills update [slug] # Update skill(s) clodds skills uninstall # Uninstall a skill clodds skills info # Show skill details clodds skills check-updates # Check for skill updates ``` ### MCP Server Commands ```bash clodds mcp # Start MCP server (stdio JSON-RPC) clodds mcp install # Auto-configure Claude Desktop & Claude Code clodds mcp uninstall # Remove Clodds from Claude config ``` Exposes all 119 skills as MCP tools. After `clodds mcp install`, restart Claude Desktop/Code to use Clodds skills directly from Claude. ### QMD (Quantitative Market Data) Commands ```bash clodds qmd status # Show QMD status clodds qmd update # Update market data clodds qmd embed # Generate embeddings clodds qmd get # Get market data clodds qmd multi-get # Get multiple markets clodds qmd collection add # Add collection clodds qmd context add # Add context clodds qmd polymarket # Search Polymarket clodds qmd kalshi # Search Kalshi clodds qmd metaculus # Search Metaculus clodds qmd manifold # Search Manifold ``` ### Market Index Commands ```bash clodds market-index stats # Show index statistics clodds market-index sync # Sync market index ``` ### WhatsApp Commands ```bash clodds whatsapp login # Login with QR code ``` ### Bittensor Commands ```bash clodds bittensor setup # Interactive setup wizard (Python, btcli, wallet, config) clodds bittensor status # Show mining configuration and status clodds bittensor check # Verify all dependencies are installed clodds bittensor wallet show # Show wallet address and balance clodds bittensor wallet create # Create a new Bittensor wallet clodds bittensor wallet balance # Check TAO balance clodds bittensor register # Register on a subnet (e.g. 64 for Chutes) ``` ### Doctor Command ```bash clodds doctor # Comprehensive system health check clodds doctor --verbose # Include all optional features and services ``` Checks AI providers, messaging channels, trading platforms, external services, and Bittensor dependencies. Use this to diagnose configuration issues. ### Locale Commands (i18n) ```bash clodds locale list # List supported languages clodds locale get # Show current locale clodds locale set # Set locale (en, zh, es, ja, ko, de, fr, pt, ru, ar) clodds locale test [key] # Test a translation key ``` ### Trade Ledger Commands Decision audit trail for AI trading transparency. ```bash clodds ledger list [userId] # List recent decisions clodds ledger list -n 50 # List more decisions clodds ledger list -c trade # Filter by category (trade/copy/arbitrage/risk) clodds ledger list -d rejected # Filter by decision (approved/rejected/blocked) clodds ledger stats [userId] # Show decision statistics clodds ledger stats -p 30d # Stats for last 30 days clodds ledger calibration [userId] # Show confidence calibration clodds ledger export [userId] # Export decisions to JSON clodds ledger export -f csv # Export as CSV clodds ledger prune --days 90 # Delete decisions older than 90 days clodds ledger verify # Verify decision hash integrity clodds ledger config # Show ledger configuration ``` Enable the ledger: ```bash clodds config set ledger.enabled true clodds config set ledger.hashIntegrity true # Optional: SHA-256 hashing ``` Onchain anchoring (tamper-proof verification): ```bash clodds ledger anchor # Anchor to Solana (default) clodds ledger anchor -c polygon # Anchor to Polygon clodds ledger anchor -c base # Anchor to Base clodds ledger verify-anchor # Verify onchain anchor ``` ### Auth Commands ```bash clodds login # Login to Clodds clodds logout # Logout from Clodds clodds version # Show version ``` ### Other Commands ```bash clodds init # Initialize config clodds upgrade # Check for updates ``` ## Pairing and access control Clodds uses a pairing flow to protect DMs. ### Approve a pairing request (CLI) ``` clodds pairing list telegram clodds pairing approve telegram ABC123 ``` ### Set an owner (can approve via chat) ``` clodds pairing set-owner telegram 123456789 -u "username" ``` ## WebChat (browser) WebChat is a local browser chat UI at: ``` http://127.0.0.1:18789/webchat ``` If you set `WEBCHAT_TOKEN`, the browser will prompt for it on first load and store it in localStorage. Features: - **Unlimited message history** — messages stored in a dedicated database table, not capped - **Sidebar with tabs** — Chats, Projects, Artifacts, Code - **Thinking indicator** — shows elapsed time while the AI is generating - **Context compacting** — older messages are summarized so the AI never fully forgets earlier conversation - **Session management** — create, rename, delete, search across conversations ## Chat commands Send these in any supported channel (Telegram, Discord, WebChat, etc.): - `/help` - list commands - `/status` - session status and token estimate - `/new` or `/reset` - reset the current session - `/context` - preview recent context - `/model [sonnet|opus|haiku|claude-...]` - change model - `/markets [platform] ` - search markets - `/compare [platforms=polymarket,kalshi] [limit=3]` - compare prices **Opportunity Finding:** - `/opportunity scan [query]` - find arbitrage opportunities - `/opportunity combinatorial` - scan for combinatorial arb (based on arXiv:2508.03474) - `/opportunity active` - show active opportunities - `/opportunity stats` - performance statistics - `/opportunity link ` - link equivalent markets - `/opportunity realtime start` - enable real-time scanning **Trading:** - `/trades stats` - trade statistics - `/trades recent` - recent trades - `/bot list` - list trading bots - `/bot start ` - start a bot - `/safety status` - safety controls - `/safety kill` - emergency stop **Advanced Trading:** - `/whale track
` - follow a whale address - `/whale top [limit]` - top traders by volume - `/whale activity ` - whale activity for market - `/copy start
` - start copy trading - `/copy stop` - stop copy trading - `/route ` - find best execution route - `/swap ` - EVM DEX swap **Virtuals Protocol (AI Agents):** - `/virt search ` - search AI agents - `/virt agent ` - get agent details - `/virt agents [category]` - list agents with sorting - `/virt trending [limit]` - top agents by volume - `/virt new [limit]` - recently launched agents - `/virt price ` - get bonding curve price - `/virt graduation ` - check graduation status **Betfair Exchange (Sports):** - `/bf markets ` - search sports markets - `/bf market ` - get market details - `/bf prices ` - get market book/odds - `/bf book ` - view orderbook - `/bf back ` - place back bet - `/bf lay ` - place lay bet - `/bf orders` - view open orders - `/bf positions` - view current positions - `/bf balance` - check account funds **Smarkets Exchange:** - `/sm markets ` - search markets - `/sm market ` - get market details - `/sm quotes ` - get current quotes - `/sm book ` - view orderbook - `/sm buy ` - place buy order - `/sm sell ` - place sell order - `/sm orders` - view open orders - `/sm balance` - check account balance **Metaculus (Forecasting):** - `/mc search ` - search questions - `/mc question ` - get question details and community prediction - `/mc tournaments` - list tournaments - `/mc tournament ` - get tournament details **PredictIt (Political Markets):** - `/pi search ` - search markets - `/pi market ` - get market and contract details - `/pi all` - list all markets **Portfolio & Risk:** - `/portfolio` - show positions and P&L - `/pnl [24h|7d|30m] [limit=50]` - historical P&L snapshots - `/digest [on|off|HH:MM|show|reset]` - daily digest settings - `/risk` - risk status, limits, and circuit breaker - `/risk dashboard` - real-time risk metrics (VaR, regime, HHI) - `/risk var` - Value-at-Risk and CVaR numbers - `/risk stress [scenario]` - run stress test - `/risk regime` - current volatility regime ## Trading credentials To enable trading tools, store per-user credentials via the agent tools (chat commands or agent prompts) or the onboarding flow. Supported platforms: - Polymarket - Kalshi - Manifold - Betfair - Smarkets - Opinion.trade - Virtuals Protocol (AI agents) - Hyperliquid (perp DEX) - Drift Protocol (Solana perps) - Jupiter (Solana aggregator) - Raydium (Solana AMM) - Orca (Solana Whirlpools) - Meteora (Solana DLMM) - Pump.fun (Solana launchpad) - Percolator (On-chain Solana perpetual futures) These are stored encrypted in the database and loaded at runtime. ### Environment Variables for New Skills | Skill | Required Env Vars | |-------|-------------------| | Copy Trading (Solana) | `SOLANA_PRIVATE_KEY` | | Signal Trading | `SOLANA_PRIVATE_KEY` | | AI Strategy | `SOLANA_PRIVATE_KEY` | | Weather Betting | `POLY_API_KEY`, `POLY_API_SECRET` | | Pump.fun Swarm | `SOLANA_PRIVATE_KEY`, optionally `SOLANA_SWARM_KEY_1..20` | | Percolator | `SOLANA_PRIVATE_KEY`, `PERCOLATOR_SLAB`, `PERCOLATOR_ORACLE` | ## Risk management Use `/risk` to control guardrails: ``` /risk Current status + portfolio metrics /risk status Detailed status /risk limits View all configured limits /risk dashboard Full dashboard (VaR, regime, concentration, etc.) /risk var Value-at-Risk / CVaR numbers /risk regime Volatility regime + position size multiplier /risk stress flash_crash Run a stress test scenario /risk set max-loss 1000 Set max daily loss ($) /risk set max-drawdown 20 Set max drawdown (%) /risk check 500 Check if a $500 trade is allowed /risk trip "reason" Manually trip circuit breaker /risk reset Reset circuit breaker /risk kill Emergency stop all trading ``` **Stress test scenarios:** `flash_crash`, `liquidity_crunch`, `platform_down`, `correlation_spike`, `black_swan` **Volatility regimes:** low (1.2x size), normal (1.0x), high (0.5x), extreme (0.25x or halt) Note: automated stop-loss execution respects `trading.dryRun` in config. ## Advanced Trading Configuration Configure advanced trading features in `clodds.json`: ```json { "whaleTracking": { "enabled": true, "minTradeSize": 10000, "minPositionSize": 50000, "platforms": ["polymarket"], "realtime": true }, "copyTrading": { "enabled": true, "dryRun": true, "followedAddresses": ["0x1234..."], "sizingMode": "fixed", "fixedSize": 100, "maxPositionSize": 500, "copyDelayMs": 5000 }, "smartRouting": { "enabled": true, "mode": "balanced", "platforms": ["polymarket", "kalshi"], "maxSlippage": 1, "preferMaker": true }, "evmDex": { "enabled": true, "defaultChain": "ethereum", "slippageBps": 50, "mevProtection": "basic", "maxPriceImpact": 3 } } ``` | Config | Options | Description | |--------|---------|-------------| | `whaleTracking.minTradeSize` | number | Min USD to track (default: 10000) | | `copyTrading.sizingMode` | fixed/proportional/percentage | How to size copied trades | | `smartRouting.mode` | best_price/best_liquidity/lowest_fee/balanced | Routing strategy | | `evmDex.mevProtection` | none/basic/aggressive | MEV protection level | | `realtimeAlerts.enabled` | boolean | Enable push notifications (default: false) | | `realtimeAlerts.whaleTrades.minSize` | number | Min whale trade to alert (default: 50000) | | `realtimeAlerts.arbitrage.minEdge` | number | Min arb edge % to alert (default: 2) | | `arbitrageExecution.enabled` | boolean | Enable auto-execution (default: false) | | `arbitrageExecution.dryRun` | boolean | Simulate without executing (default: true) | | `arbitrageExecution.minEdge` | number | Min edge % to execute (default: 1.0) | ## Auto-Arbitrage Execution Automatically execute detected arbitrage opportunities: ```json { "arbitrageExecution": { "enabled": true, "dryRun": true, "minEdge": 1.0, "minLiquidity": 500, "maxPositionSize": 100, "maxDailyLoss": 500, "maxConcurrentPositions": 3, "platforms": ["polymarket", "kalshi"], "preferMakerOrders": true, "confirmationDelayMs": 0 } } ``` | Setting | Description | |---------|-------------| | dryRun | Simulate trades without executing (recommended for testing) | | minEdge | Minimum edge % to trigger execution | | maxPositionSize | Max USD per trade | | maxDailyLoss | Stop executing if daily loss exceeds this | | maxConcurrentPositions | Maximum simultaneous positions | | confirmationDelayMs | Wait time before executing (allows price recheck) | The executor listens for opportunities from the opportunity finder and automatically places orders when criteria are met. Always test with `dryRun: true` first. ## Real-time Alerts Push notifications for trading events. Configure in `clodds.json`: ```json { "realtimeAlerts": { "enabled": true, "targets": [ { "platform": "telegram", "chatId": "123456789" } ], "whaleTrades": { "enabled": true, "minSize": 50000, "cooldownMs": 300000 }, "arbitrage": { "enabled": true, "minEdge": 2, "cooldownMs": 600000 }, "priceMovement": { "enabled": true, "minChangePct": 5, "windowMs": 300000 }, "copyTrading": { "enabled": true, "onCopied": true, "onFailed": true } } } ``` | Alert Type | Trigger | |------------|---------| | Whale Trade | Large trades above minSize threshold | | Arbitrage | Opportunities above minEdge % | | Price Movement | Price changes above minChangePct % | | Copy Trading | When trades are copied or fail | ## Performance Dashboard Access the web-based performance dashboard at: ``` http://127.0.0.1:18789/dashboard ``` The dashboard shows: - Total trades and win rate - Cumulative P&L with interactive chart - Sharpe ratio and max drawdown - Strategy breakdown with P&L per strategy - Recent trades table with entry/exit prices API endpoint for programmatic access: ``` GET /api/performance ``` ## Portfolio and P&L - `/portfolio` shows current positions and live P&L. - `/pnl` shows snapshots over time. Enable via: - `POSITIONS_PNL_SNAPSHOTS_ENABLED=true` - `POSITIONS_PNL_HISTORY_DAYS=90` ## Daily digest Enable daily summaries: ``` /digest on /digest 09:00 /digest show /digest off ``` ## Market index search Enable the market index in config or `.env`: ``` MARKET_INDEX_ENABLED=true ``` Then use: - `/markets ` in chat - HTTP endpoint `GET /market-index/search` ## Webhooks (automation) Webhooks are mounted at `/webhook` or `/webhook/*`. They require HMAC signatures by default: - Header: `x-webhook-signature` (or `x-hub-signature-256`) - Value: hex HMAC-SHA256 of the raw request body using the webhook secret Set `CLODDS_WEBHOOK_REQUIRE_SIGNATURE=0` to disable signature checks. ## Troubleshooting Common checks: - `clodds doctor` - environment and config checks - `npm run build` - verify TypeScript compilation - `npm run dev` - start in dev mode with logs If a channel is not responding, confirm: - Token set in `.env` - Channel enabled in config (or `.env`) - Pairing approved (for DMs) Monitoring targets can include an `accountId` for multi-account channels, e.g. WhatsApp: ```json { "monitoring": { "alertTargets": [ { "platform": "whatsapp", "accountId": "work", "chatId": "+15551234567" } ] } } ``` If you omit `accountId`, Clodds will attempt to route alerts using the most recent session for that chat (when available). You can also specify per-account WhatsApp DM policies under `channels.whatsapp.accounts..dmPolicy` (e.g. `pairing` vs `open`). ## Advanced Trading Features ### Whale Tracking (Polymarket) Monitor large trades on Polymarket: ``` /whale track 0x1234... # Follow a specific address /whale top 10 # Top 10 traders by volume /whale activity trump # Whale activity for Trump markets ``` ### Crypto Whale Tracking (Multi-Chain) Monitor whale activity across Solana and EVM chains: ``` /crypto-whale start # Start tracking all configured chains /crypto-whale watch solana ABC123... # Watch a Solana wallet /crypto-whale watch ethereum 0x1234... # Watch an ETH wallet /crypto-whale top solana 10 # Top 10 Solana whales /crypto-whale recent ethereum 20 # Recent 20 ETH whale transactions /crypto-whale stop # Stop tracking ``` **Supported chains:** Solana, Ethereum, Polygon, Arbitrum, Base, Optimism Configure thresholds in `clodds.json`: ```json { "cryptoWhaleTracking": { "enabled": true, "chains": ["solana", "ethereum", "polygon"], "thresholds": { "solana": 10000, "ethereum": 50000, "polygon": 5000 }, "birdeyeApiKey": "...", "alchemyApiKey": "..." } } ``` ### Copy Trading (Polymarket) Automatically mirror trades from successful wallets with automatic stop-loss and take-profit: ``` /copy start 0x1234... # Start copying an address /copy config size=100 # Set copy size to $100 /copy config sl=10 # Set 10% stop-loss /copy config tp=20 # Set 20% take-profit /copy status # View active positions and SL/TP status /copy stop # Stop copy trading ``` **SL/TP Monitoring:** - Positions are monitored every 5 seconds - Automatic exit when stop-loss or take-profit triggers - Notifications sent when positions are closed ### Copy Trading (Solana) Monitor Solana wallets and automatically copy their trades using Jupiter aggregator: ``` /copy add [--mult 1.0] [--max 0.5] Follow a wallet /copy add 7xKXtg... --name "whale1" With friendly name /copy remove Stop following /copy list List followed wallets /copy pause Pause copying /copy resume Resume copying /copy history [wallet] View trade history /copy stats View overall stats /copy config --mult 0.5 Update multiplier ``` **Configuration Options:** - `--mult `: Position size multiplier (0.5 = half, 2.0 = double) - `--max `: Maximum SOL per trade (default: 0.5) - `--min `: Minimum trade to copy (default: 0.01) - `--delay `: Delay before copying (stealth mode) - `--slippage `: Slippage tolerance in basis points - `--buys-only` / `--sells-only`: Filter trade direction **Features:** - Real-time monitoring via Solana WebSocket - Auto-detects trades on Pump.fun, Raydium, Jupiter, Orca, Meteora - Configurable position sizing with multiplier and max cap - Trade history and P&L tracking ### Signal Trading Monitor external signals from RSS feeds, Twitter, and webhooks to trigger automatic trades: ``` /signal add rss --name "news" Add RSS feed /signal add twitter whale_alert Add Twitter/X account /signal add webhook --name "custom" Get webhook URL /signal list List all sources /signal remove Remove source /signal pause Pause source /signal resume Resume source /signal history [source] View signal history /signal filter add keyword "pump" buy Add filter rule /signal config --amount 0.1 Set SOL per trade ``` **Signal Sources:** - **RSS Feeds**: Monitor any RSS/Atom feed (polls every 30s) - **Twitter/X**: Monitor tweets via Nitter proxy - **Webhooks**: Receive signals via HTTP POST **Filters:** - `keyword`: Match text content → action (buy/sell) - `sentiment`: Match bullish/bearish - `regex`: Custom regex patterns - `mint`: Match specific token address **Webhook payload:** ```json { "content": "Buy BONK now! 5BqXr...", "author": "trader", "secret": "your-secret" } ``` ### AI Strategy Convert natural language descriptions into executable trading strategies: ``` /strategy "buy $100 of SOL if it drops 5%" /strategy "sell half my BONK when it hits $0.00003" /strategy "DCA $50 into JUP every hour for 12 hours" /strategy "set stop loss at 20% for my SOL position" /strategies List active strategies /strategy status Check strategy status /strategy cancel Cancel strategy /strategy templates List templates /execute buy 0.5 SOL of TOKEN... Execute immediately ``` **Strategy Types:** - **Price Triggers**: Buy/sell when price crosses threshold - **DCA**: Dollar cost average over time intervals - **Take Profit / Stop Loss**: Automatic exit at targets - **Scale In/Out**: Buy/sell in tranches - **Ladder Orders**: Multiple orders at different price levels **Templates:** `dip-buy`, `take-profit`, `dca-daily`, `stop-loss`, `ladder-buy`, `scale-out` **Monitoring:** Strategies checked every 5 seconds via Jupiter/Birdeye prices. ### Weather Betting Use NOAA weather forecasts to find edge on Polymarket weather markets: ``` /weather scan Scan all weather markets for edge /weather forecast "New York" Get NOAA forecast /weather markets List active weather markets /weather edge Calculate edge for specific market /weather bet 10 Execute $10 bet /weather auto --threshold 15 Auto-bet when edge >= 15% /weather history View bet history ``` **How It Works:** 1. Fetch NOAA forecast (free, no API key) 2. Match to Polymarket weather markets 3. Compare NOAA probability to market YES price 4. Bet if significant edge exists **Edge Calculation:** ``` Edge = NOAA Probability - Market Price Example: NOAA 80% rain, Market 65% → +15% edge → Bet YES ``` **Supported Market Types:** Temperature, precipitation, snow, record highs **Position Sizing:** Quarter-Kelly criterion, capped at 10% of bankroll. ### Pump.fun Swarm Trading Coordinate up to 20 wallets for synchronized trades on Pump.fun tokens: ``` /swarm wallets List all swarm wallets /swarm balances Refresh SOL balances from chain /swarm enable Enable a wallet /swarm disable Disable a wallet /swarm buy 0.1 Buy 0.1 SOL on each wallet /swarm sell 100% Sell all positions /swarm position Show cached positions /swarm refresh Fetch fresh positions /swarm preset list List saved presets /swarm preset save Save a preset ``` **Execution Modes:** - `--parallel`: All wallets simultaneously (fastest) - `--bundle`: Jito bundle, all-or-nothing (≤5 wallets) - `--multi-bundle`: Multiple Jito bundles (6-20 wallets) - `--sequential`: Staggered 200-400ms delays (stealth) **Built-in Presets:** `fast`, `atomic`, `stealth`, `aggressive`, `safe` **Multi-DEX Support:** Pump.fun (default), Bags.fm (`--dex bags`), Meteora (`--dex meteora`) **Setup:** ```bash export SOLANA_PRIVATE_KEY="wallet_0" export SOLANA_SWARM_KEY_1="wallet_1" # ... up to SOLANA_SWARM_KEY_20 ``` ### Smart Order Routing Find the best execution across platforms: ``` /route trump buy 1000 # Find best route for $1000 buy ``` ### EVM DEX Trading Trade on Uniswap/1inch across EVM chains: ``` /swap ethereum USDC WETH 1000 # Swap $1000 USDC for WETH /swap base USDC ETH 500 # Swap on Base ``` Supported chains: ethereum, arbitrum, optimism, base, polygon ### Solana DEX Trading Trade on Solana DEXes via unified interface or direct DEX commands: **Unified Commands:** ``` /sol swap 1 SOL to USDC Execute swap (uses Jupiter) /sol quote 100 USDC to JUP Get quotes from all DEXes /sol pools BONK List all pools /sol route SOL USDC Find best route /sol balance Check balance ``` **Jupiter Aggregator:** ``` /jup swap 1 SOL to USDC Execute swap /jup quote 100 USDC to JUP Get quote /jup route SOL BONK Show route details ``` **Raydium DEX:** ``` /ray swap 1 SOL to USDC Execute swap /ray pools SOL List pools ``` **Orca Whirlpools:** ``` /orca swap 1 SOL to USDC Execute swap /orca pools SOL List Whirlpools ``` **Meteora DLMM:** ``` /met swap 1 SOL to USDC Execute swap /met pools SOL List DLMM pools ``` ### Solana Lending Protocols Lend, borrow, and earn yield on Solana lending protocols. Requires `SOLANA_PRIVATE_KEY`. **Kamino Finance (15 commands):** ``` /kamino deposit 100 USDC Deposit collateral /kamino withdraw all USDC Withdraw collateral /kamino borrow 1 SOL Borrow assets /kamino repay all SOL Repay borrowed /kamino obligation View positions (deposits & borrows) /kamino health Check health factor & liquidation risk /kamino reserves List reserves with APY /kamino rates Interest rates table /kamino strategies List liquidity vault strategies /kamino vault-deposit [amtB] Deposit to vault /kamino vault-withdraw [shares|all] Withdraw from vault /kamino shares View your vault shares /kamino markets List lending markets ``` **MarginFi:** ``` /marginfi deposit 100 USDC Deposit collateral /marginfi withdraw all USDC Withdraw collateral /marginfi borrow 1 SOL Borrow assets /marginfi repay all SOL Repay borrowed /marginfi account View positions (deposits & borrows) /marginfi health Check health factor & liquidation risk /marginfi banks List lending pools with APY /marginfi rates Interest rates table ``` **Solend:** ``` /solend deposit 100 USDC Deposit collateral /solend withdraw all USDC Withdraw collateral /solend borrow 1 SOL Borrow assets /solend repay all SOL Repay borrowed /solend obligation View positions (deposits & borrows) /solend health Check health factor & liquidation risk /solend reserves List reserves with APY /solend rates Interest rates table /solend markets List lending markets ``` **Pump.fun:** ``` /pump buy 0.1 Buy with 0.1 SOL /pump sell 1000 Sell 1000 tokens ``` **Security Shield:** ``` /shield scan Scan code/plugin for malicious patterns (75 rules, 9 categories) /shield check
Check address safety (auto-detect Solana/EVM) /shield validate [token] Pre-flight transaction validation /shield scams [solana|evm] List known scam addresses (70+ entries) /shield status Show scanner statistics /shield help Show help ``` **Token Security Audit:** ``` /audit
Auto-detect chain, full security audit /audit
--chain eth Specify chain (eth, bsc, polygon, arb, base, solana...) /audit help Show usage ``` **DCA (Dollar-Cost Averaging):** ``` /dca poly --per <$> --every [--price

] Polymarket DCA /dca kalshi --per <$> --every [--price

] Kalshi DCA /dca pump --per --every [--slippage ] [--pool pump|raydium|auto] PumpFun DCA /dca hl --per <$> --every [--side long|short] [--leverage ] Hyperliquid DCA /dca bf --per <$> --every [--side long|short] [--leverage ] Binance Futures DCA /dca bb --per <$> --every [--side long|short] [--leverage ] Bybit DCA /dca mexc --per <$> --every [--side long|short] [--leverage ] MEXC Futures DCA /dca drift --per <$> --every [--type perp|spot] [--side long|short] Drift DCA /dca opinion --per <$> --every [--price

] Opinion.trade DCA /dca predict --per <$> --every [--price

] Predict.fun DCA /dca orca --per --every [--slippage ] Orca DCA /dca raydium to --per --every [--slippage ] Raydium DCA /dca virtuals --per --every [--slippage ] Virtuals DCA (Base) /dca base to --per --every [--slippage ] Base chain swap DCA /dca evm to --per --every [--slippage ] EVM swap DCA (Odos) /dca sol to --per --every Jupiter DCA (Solana) /dca list List active DCA orders /dca info Show order details and progress /dca pause Pause a running DCA order /dca resume Resume a paused DCA order /dca cancel Cancel a DCA order ``` **Drift Protocol (Perpetuals):** ``` /drift long SOL-PERP 0.5 Open long position /drift short BTC-PERP 0.01 Open short position /drift positions View open positions /drift orders View open orders /drift balance Check balance /drift leverage SOL 5 Set 5x leverage ``` **Percolator (On-Chain Solana Perps):** ``` /percolator status Market state (oracle price, OI, funding, spread) /percolator positions Your open positions /percolator long 100 Open $100 long position /percolator short 50 Open $50 short position /percolator deposit 500 Deposit USDC collateral /percolator withdraw 100 Withdraw USDC collateral /percolator help Show all commands ``` Also available via `/perc` alias. **Bags.fm (Token Launchpad - Complete):** ``` # Trading /bags quote 1 SOL to USDC Get swap quote /bags swap 0.5 SOL to BONK Execute swap # Discovery /bags pools List all pools /bags trending Trending by volume /bags token Full token info /bags creators Get creators /bags lifetime-fees Total fees collected # Fee Claiming /bags fees [wallet] Check claimable fees /bags claim [wallet] Claim all fees /bags claim-events Claim history /bags stats Per-claimer stats # Token Launch /bags launch Launch new token /bags fee-config Set up fee shares # Wallet Lookup (providers: twitter, github, kick, tiktok, instagram, onlyfans, solana, apple, google, email, moltbook) /bags wallet twitter Lookup by social /bags wallets github user1,user2 Bulk lookup # Partner System /bags partner-config Create partner key /bags partner-claim Claim partner fees /bags partner-stats View partner stats ``` ### MEV Protection MEV protection is automatically enabled for swaps: - **Ethereum**: Flashbots Protect, MEV Blocker - **Solana**: Jito bundles - **L2s**: Sequencer protection (built-in) ### Hyperliquid DEX Trade perpetual futures on Hyperliquid (69% market share, 130+ markets, up to 50x leverage). **Setup:** ```bash export HYPERLIQUID_WALLET="0x..." export HYPERLIQUID_PRIVATE_KEY="0x..." ``` **Quick Commands:** ``` /hl balance # Positions & balances /hl long BTC 0.1 # Open long 0.1 BTC /hl short ETH 1 3000 # Short 1 ETH at $3000 /hl close BTC # Close BTC position /hl closeall # Close all positions /hl portfolio # PnL breakdown /hl funding BTC # Funding rates /hl orders # Open orders ``` **TWAP & Advanced:** ``` /hl twap buy BTC 1 60 # Buy 1 BTC over 60 minutes /hl leverage BTC 10 # Set 10x leverage /hl hlp deposit 1000 # Deposit to HLP vault /hl transfer spot2perp 500 # Move to perps ``` **Database Tracking:** All trades are logged to SQLite with full PnL tracking: ``` /hl trades [coin] [limit] # Trade history /hl dbstats [coin] [period] # Win rate, profit factor /hl dbfunding [coin] # Funding payments ``` **Shortcuts:** `/hl b` (balance), `/hl l` (long), `/hl s` (short), `/hl p` (price), `/hl f` (funding) ## Telegram Mini App Access Clodds as a Telegram Mini App (Web App) for mobile-friendly portfolio and market access. ### Setup 1. Register your Mini App with BotFather: ``` /newapp ``` 2. Set the Web App URL to your gateway: ``` https://your-domain.com/miniapp ``` 3. Users can access via the menu button in your bot's chat. ### Features - **Portfolio**: View total value, P&L, and recent positions - **Markets**: Search prediction markets across platforms - **Arbitrage**: Scan for opportunities with one tap The Mini App uses Telegram's native theming and haptic feedback for a native experience. ### Direct Link Share the Mini App directly: ``` https://t.me/YourBot/app ``` ## Data Sources Clodds integrates multiple external data sources for edge detection and trading signals. ### News Feed RSS feeds from political and financial news sources: - Reuters Politics - NPR Politics - Politico - FiveThirtyEight Twitter/X integration (requires `X_BEARER_TOKEN` or `TWITTER_BEARER_TOKEN`): ```json { "feeds": { "news": { "enabled": true, "twitter": { "accounts": ["nikiivan", "NateSilver538", "redistrict"] } } } } ``` ### External Probability Sources Edge detection compares market prices to external data: | Source | Env Var | Description | |--------|---------|-------------| | CME FedWatch | `CME_FEDWATCH_ACCESS_TOKEN` | Fed rate probabilities | | FiveThirtyEight | `FIVETHIRTYEIGHT_FORECAST_URL` | Election model | | Silver Bulletin | `SILVER_BULLETIN_FORECAST_URL` | Nate Silver's model | | Odds API | `ODDS_API_KEY` | Sports betting odds | ### Crypto Price Feed Real-time prices via Binance WebSocket with Coinbase/CoinGecko fallback: - BTC, ETH, SOL, XRP, DOGE, ADA, AVAX, MATIC, DOT, LINK - 24h volume and price changes - OHLCV historical data ## Authentication Clodds supports multiple authentication methods for AI providers: ### OAuth Authentication ```bash # Interactive OAuth flow clodds auth login anthropic clodds auth login openai clodds auth login google # Check status clodds auth status # Revoke tokens clodds auth logout anthropic ``` ### GitHub Copilot ```bash # Authenticate with GitHub Copilot clodds auth copilot ``` ### Google/Gemini ```bash # API key authentication export GOOGLE_API_KEY=your-key # Or OAuth clodds auth login google ``` ### Qwen/DashScope ```bash export DASHSCOPE_API_KEY=your-key ``` ## Telemetry & Monitoring Enable OpenTelemetry for observability: ```json { "telemetry": { "enabled": true, "serviceName": "clodds", "otlpEndpoint": "http://localhost:4318", "metricsPort": 9090, "sampleRate": 1.0 } } ``` Access Prometheus metrics at `http://localhost:9090/metrics`. ### LLM Metrics - `llm_requests_total` - Total LLM requests by provider/model/status - `llm_request_duration_ms` - Request latency histogram - `llm_tokens_input_total` - Input tokens by provider/model - `llm_tokens_output_total` - Output tokens by provider/model ## Extensions ### Task Runner AI-powered task execution with planning: ```bash # Run a complex task clodds task run "Build a REST API with authentication" # View task status clodds task status # Cancel running task clodds task cancel ``` ### Open Prose AI-assisted document editing: ```bash # Create a document clodds prose create "My Article" # Edit with AI clodds prose edit "Make it more concise" # Export clodds prose export html ``` ## Production Deployment ### Channel Adapters All channel adapters include production-grade features: - **Rate Limiting**: Token bucket algorithm (30 req/s default) - **Circuit Breaker**: Auto-disable on repeated failures - **Health Checks**: Periodic connectivity checks - **Auto-Reconnection**: Exponential backoff reconnection - **Metrics**: Request counts, latency, error rates Configure in `clodds.json`: ```json { "channels": { "telegram": { "rateLimit": 30, "rateLimitBurst": 10, "circuitBreakerThreshold": 5, "healthCheckIntervalMs": 30000, "maxReconnectAttempts": 10 } } } ``` ## Server Security Hardening For production Linux deployments, use the built-in security hardening CLI: ```bash # Preview changes (safe, no modifications) clodds secure --dry-run # Apply all hardening sudo clodds secure # Run security audit only clodds secure audit ``` ### What gets hardened | Component | Changes | |-----------|---------| | SSH | Disable password auth, root login, limit attempts | | Firewall | Configure ufw with minimal ports | | fail2ban | Block brute-force attempts | | Auto-updates | Enable security patches | | Kernel | Apply sysctl hardening | ### Important 1. **Always test SSH** in a new terminal before closing your session 2. **Backup SSH keys** before disabling password auth 3. **Check firewall rules** don't block your app ports See [SECURITY_AUDIT.md](./SECURITY_AUDIT.md) for detailed security documentation. ## Tips - Keep the gateway on loopback unless you add auth and a reverse proxy. - Use WebChat for fast local testing before wiring up a messaging platform. - For production, use Docker or a process manager and enable monitoring. - Run `clodds secure` on production servers for security hardening.