Katbot Trading Skill

This skill teaches the agent how to use the Katbot.ai API to manage a Hyperliquid trading portfolio.

Capabilities

1. Subscription Monitoring: Check subscription status, expiry, and feature usage limits at session start.
2. Market Analysis: Check the BTC Momentum Index (BMI) and 24h gainers/losers.
   • btc_momentum.py: Calculates the BMI (BTC Momentum Index) based on trend, MACD, body, volume, and RSI. Returns a signal (BULLISH, BEARISH, NEUTRAL).
   • bmi_alert.py: Runs btc_momentum.py and sends a Telegram alert if the market direction has changed. Uses portfolio_tokens.json for custom token tracking.
3. Token Selection: Automatically pick the best tokens for the current market direction.
4. Recommendations: Get AI-powered trade setups (Entry, TP, SL, Leverage).
5. Execution: Execute and close trades on Hyperliquid with user confirmation.
6. Portfolio Tracking: Monitor open positions, uPnL, and balances.
7. Performance Charts: Generate cumulative PnL charts (24H/7D/30D) as PNG images for Telegram sharing.
8. Chat: Send free-form messages to the portfolio agent and receive analysis.

Tools

All tool scripts live exclusively in {baseDir}/tools/ — this is the single canonical location. There are no copies elsewhere in the project. Always reference tools via {baseDir}/tools/<script> and set PYTHONPATH={baseDir}/tools so inter-tool imports resolve correctly.

Dependencies are listed in {baseDir}/requirements.txt.

• ensure_env.sh: Run before any tool. Checks if dependencies are installed for the current skill version and re-installs if needed. Safe to call every time — it exits immediately if already up to date.
• katbot_onboard.py: First-time setup wizard. Authenticates via SIWE using your Wallet Key, creates/selects a portfolio, and saves credentials locally to the secure identity directory.
• katbot_client.py: Core API client. Handles authentication, token refresh, portfolio management, recommendations, trade execution, chat, and subscription monitoring. Also usable as a CLI script.
• katbot_workflow.py: End-to-end trading workflow (BMI -> token selection -> recommendation). Imports katbot_client and token_selector — requires PYTHONPATH={baseDir}/tools.
• token_selector.py: Momentum-based token selection via CoinGecko.
• btc_momentum.py: Calculates BTC Momentum Index (BMI).
• bmi_alert.py: Telegram alerting workflow for BMI changes.
• portfolio_chart.py: Fetches portfolio trade history, reconstructs cumulative realized PnL using FIFO coin-level matching, and saves an 800×450px dark-theme PNG chart for Telegram sharing. Supports --window 24H|7D|30D, --output PATH, and --json flags.

BMI Analysis Tool Usage

The BMI (BTC Momentum Index) is a proprietary indicator used to determine market bias.