katbot-trading

# 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. **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 CL...