Documentation
Everything you need to set up and run HAWK — from installation to understanding how the trading engine works.
HAWK is an autonomous crypto trading agent. It monitors 25+ cryptocurrency markets, computes technical signals, and executes trades directly on your exchange account — no cloud, no AI tokens for routine operations. Works standalone or as a plugin for Claude Code.
Scans markets every 15 minutes, executes trades, manages positions — all rule-based, no AI tokens
API keys never leave your machine. Trades execute directly on your exchange account
Real-time portfolio, trade history, signal scanner, strategy management, and backtesting at hawkish.app
The installer checks for all of these automatically and tells you what to install if anything is missing.
| Requirement | Purpose | Install |
|---|---|---|
| Python 3 | Technical indicator calculations + backtesting | python.org |
| curl | Exchange API requests | Usually pre-installed |
| jq | JSON processing | brew install jq / apt install jq |
| openssl | API request signing (HMAC) | Usually pre-installed |
| bash | Script execution | Pre-installed on all platforms |
You also need an account on a supported exchange (Binance or Hyperliquid) with API keys that have trading permissions enabled and withdrawals disabled.
Systemd user timers for scheduling. Tested on Ubuntu, Debian, Arch, Fedora.
LaunchAgent plists for scheduling. Apple Silicon and Intel supported.
Git Bash or WSL with Task Scheduler. Requires Windows 10+.
The installer auto-detects your platform and sets up the appropriate scheduling mechanism. All platforms get the same trading logic and features.
curl -fsSL https://hawkish.app/install.sh | bashThe installer checks prerequisites, deploys plugin files to ~/.hawk/, and sets up scheduled tasks.
Sign up at hawkish.app, then go to Settings and copy your license key.
hawk setup exchange hyperliquidInteractive setup walks you through API key creation. Your keys are stored locally with strict permissions and never leave your machine. Supports both Binance and Hyperliquid.
Visit the Strategies page on the dashboard and select Conservative, Moderate, or Aggressive. Moderate is recommended for most users.
Check hawk status in the terminal or visit the dashboard. Your first hourly report will arrive at the next :13 past the hour.
If you use Claude Code, install the plugin for AI-powered commands: claude plugin install hawk@hawkish. You can then ask “show portfolio”, “close ETH”, or “analyze my trades” in natural language.
HAWK ships with two built-in strategies and supports user-uploaded custom ones. All strategies are JSON definitions executed by a shared composable engine — the same code runs in live trading, the dashboard backtester, and the Python backtester.
Trend-following on hourly candles. Enters long when EMA 9/21/100 squeeze tight (≤1.5% spread) and curl upward, MACD positive, RSI 48–55, BTC trending up, price within 0.25% of EMA9. Short side fires when RSI ≥ 60 with MACD negative and price below EMA100. Conservative/Moderate/Aggressive risk profiles.
Faster, smaller, more frequent trades on 15-minute candles. Triple-confirmation entry: 3-hour momentum persistence + volume spike (1.8× the 80-candle average) + pullback to fast EMA + EMA slope confirmation. Gated by a BTC bull-score regime. Tight ATR-based stops, daily profit and loss caps lock in gains and prevent runaway losses.
Pro users can upload their own strategy JSON via Dashboard → Strategies → Upload. Each upload is server-side validated against the engine's condition + exit registries (29 entry conditions, 12 exit rules). Run a backtest meeting the live-eligibility gate (≥20 trades, profit factor ≥1.0, max DD ≥−30%, win rate ≥30%) and the strategy unlocks for live trading.
Enters when EMAs converge in uptrends — precision timing at support
Cuts stagnant trades after 12 hours if leveraged profit is below 1.5%
Automatically shorts in bear markets via RSI rejection signals
Stops trading for the day after the daily loss limit is hit (default 2%)
The strategy architecture is fully pluggable — every strategy is a JSON definition with entry conditions, exit rules, and risk profiles. Only one strategy is active at a time per user. See the strategy schema reference for the full field list when designing your own.
Choose a risk level that matches your comfort. Each level controls position size and leverage. All other parameters (entry timing, exit triggers, daily loss limit) stay the same.
Smaller positions with moderate leverage. Best for beginners.
Balanced growth and safety. Recommended for most users.
Larger positions for experienced traders comfortable with drawdowns.
Backtest results based on 2 years of historical data across 25 tokens. Past performance does not guarantee future results.
HAWK runs three independent timers on your machine. No cloud, no AI tokens for routine operations.
Reads the active strategy config, scans the full watchlist for entry signals. For Hawk: checks EMA convergence, RSI sweet spot, MACD, BTC correlation. Ranks candidates by tightest EMA spread. Enforces daily loss limit (2%) and max concurrent positions (3). One trade per cycle.
Checks open positions against strategy exit rules. For Hawk: disaster stop (ATR×4), time decay (exit if <1.5% after 12h), max hold (24h), EMA cross exit when EMA21 falls below EMA100. Auto-restores orphaned exchange positions.
Delivers a market pulse: BTC price, Fear & Greed, top movers, best opportunities, portfolio summary. Generates the signal snapshot for the dashboard.
Scores every watchlist coin on 1h + 4h + 1d timeframe alignment (0-100). When a coin scores ≥70 with matching direction, the Signal Scanner relaxes its entry conditions — requiring 5 of 8 filters instead of all 8. The multi-timeframe agreement compensates for missing single-timeframe signals, catching pullback opportunities the strict filter would miss. See the Opportunities tab on the Scanner page.
Each strategy defines its own ordered list of exit triggers. The first trigger that fires closes the position. Below are Hawk's exits — Viper and custom strategies use the same exit registry but in different combinations.
Pre-checks distance to the exchange liquidation price every cycle. Closes the position if it gets dangerously close, before the exchange forces a margin liquidation.
ATR×4 from entry. A safety net for extreme moves — the hard stop the strategy is built around. Uses close price, not wicks.
Closes positions held longer than 12 hours if leveraged profit is below 1.5%. Frees capital from stagnant trades for better opportunities.
Hard ceiling at 24 hours. If a trade hasn't resolved by then, the thesis has expired — close it and free the slot.
Closes longs when EMA21 crosses below EMA100 — the trend structure has broken. Only applies to long positions.
Stops all new entries for the day after 2% account loss. Existing positions continue to be monitored. Prevents compounding losses.
Hawk deliberately disables trailing stops, breakeven acceleration, scale-out, and signal reversal exits. These generic modules interfere with the strategy's precise exit timing.
These limits are enforced on every trade, every cycle. No exceptions.
HAWK can run on multiple exchanges simultaneously. Each exchange gets its own state file, systemd timer, and independent position tracking.
Full support for spot longs, futures shorts, and leveraged longs. Most liquid markets, lowest fees for high-volume traders.
On-chain perpetual exchange. All trades are perps — spot longs execute as 1x perp longs. No KYC required.
Add an exchange:
hawk setup exchange binanceInteractive setup walks you through API key creation and saves credentials locally. The dashboard shows a combined portfolio across all exchanges.
Test strategies risk-free with virtual money and real market data. Enable from the Settings page on the dashboard.
Run historical simulations to see how the strategy would have performed. Available from the dashboard or CLI.
hawk backtest --strategy hawk --period 90d --balance 1000HAWK keeps you informed via WhatsApp, Telegram, or the web dashboard.
| Event | When |
|---|---|
| Hourly market report | Every hour |
| Trade opened (long or short) | Immediately |
| Trade closed (profit or loss) | Immediately |
| Daily loss limit hit | Immediately |
| Circuit breaker triggered | Immediately |
| Exchange error / API failure | On detection |
hawk statusCurrent positions and PnLhawk scanRun signal scan nowhawk versionShow plugin versionhawk setup exchange binanceAdd exchange credentialshawk backtest --strategy hawk --period 90dRun backtesthawk updateUpdate to latest version"show portfolio"Account balances across exchanges"show positions"Open positions with unrealized PnL"close ETH"Close specific position"close all"Emergency: close everything"pause trading"Halt automated trading"resume trading"Resume trading"status"Overview of everything| Issue | Solution |
|---|---|
| Not receiving hourly reports | Check timer: systemctl --user status hawk-hourly-report.timer (Linux) or launchctl list | grep hawk (macOS) |
| No trades happening | Check that strategy is active on the Strategy page. Also check market conditions — Hawk only enters when EMAs converge in the right regime. |
| Orders rejected | Usually MIN_NOTIONAL (too small) or LOT_SIZE (precision). Increase position size or check exchange filters. |
| API credentials error | Re-run hawk setup exchange <name> to reconfigure. Verify permissions (chmod 600) at ~/.hawk/credentials/. |
| Multi-exchange not working | Check systemd template timers: systemctl --user status hawk-signal-scan@binance.timer. Each exchange needs its own timer. |
| Dashboard not updating | Run hawk sync or check that sync-dashboard.sh timer is running. Verify your license key in Settings. |
Sign up for free, install the plugin, and have HAWK watching the markets for you within minutes.
Hawk runs on 1h candles and enters long when EMA 9/21/100 converge tightly (≤1.5% spread) with RSI 48–55, MACD confirmation, and BTC slope > 0.1. Positions exit on a disaster stop (ATR×4), time decay (cut after 12h if profit <1.5%), max hold (24h), or an EMA21/100 bearish cross. The companion strategy Viper runs on 15m candles for faster, smaller momentum trades. Both were backtested across 2 years on 25 tokens.
EMA (9, 21, 100) for trend structure and convergence detection, RSI for momentum sweet spot (48–55 for entry), MACD for trend confirmation, ATR for disaster stop sizing, and BTC 14-day slope for regime detection. The signal scanner also uses Bollinger Bands, ADX, OBV, ROC, and divergence detection for the hourly market reports.
Risk levels control position size and leverage. Conservative: 5% per trade at 3x leverage. Moderate: 10% at 5x. Aggressive: 15% at 5x. All levels share the same entry/exit logic, daily loss limit (2%), and max concurrent positions (3). You can switch risk levels anytime from the Strategies page — it applies to the next trade.
Yes. Hawk supports running Binance and Hyperliquid simultaneously. Each exchange gets its own state file, systemd timer, and position tracking. The dashboard combines all exchanges into a unified portfolio view. Run 'hawk setup exchange <name>' to add each exchange.
Paper trading lets you test the strategy with virtual money and real market data. Enable it from the Settings page. All execution is simulated (virtual orders, virtual balance) but market prices are real. Notifications are prefixed with [PAPER] so you can tell them apart. Your paper state is separate from live state.
No. The trading engine is entirely rule-based — bash scripts and Python indicator calculations. No ML models, no trained weights, no black-box predictions. The optional Claude Code integration adds natural language commands, but trading decisions are always deterministic.
API keys are stored locally on your machine with strict file permissions (chmod 600). They never leave your machine. For Hyperliquid, a dedicated agent wallet is generated — your main wallet's private key is never stored. Hawk's servers never see your keys.
Toggling the strategy off stops new trade entries. Existing positions continue to be monitored — exit logic (TP, time decay, disaster stop) still runs. You can close positions manually or let them exit on their own.
Yes. Hawk is an autonomous trading tool, not a guaranteed profit machine. Markets are unpredictable, and past backtest results don't guarantee future performance. Risk management limits losses, but drawdowns are inevitable. Never trade with money you can't afford to lose.