{"_id":"@alzarak/trading-bot","name":"@alzarak/trading-bot","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alzarak/trading-bot","version":"1.0.0","description":"Autonomous stock day trading bot for Claude Code — Alpaca Markets API","bin":{"trading-bot":"bin/install.mjs"},"keywords":["claude-code","trading","alpaca","day-trading","autonomous"],"author":{"name":"Alzarak"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Alzarak/trading-bot.git"},"gitHead":"6b6e647468cae408cc79cadc5b8158aac418cc31","_id":"@alzarak/trading-bot@1.0.0","bugs":{"url":"https://github.com/Alzarak/trading-bot/issues"},"homepage":"https://github.com/Alzarak/trading-bot#readme","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-95YKIlbEnvBMbBYOHA+rU9v1lmxXIivAapJlkoh8FnhRDF/UBXZGLfH7bOYvWKFg3psd9JfRZQ5bs74mpfaYfw==","shasum":"af9eee238a95435a0935f069c532f10a477944d3","tarball":"https://registry.npmjs.org/@alzarak/trading-bot/-/trading-bot-1.0.0.tgz","fileCount":59,"unpackedSize":415347,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD06cLno3GwQQLEXWQNVwkhh1MRhDztInTtDIG+oXHkNgIgUCHWTLD+Q36IraR9d0OoGehf/jPqTe8Ey+bOPKmtOW0="}]},"_npmUser":{"name":"alzarak","email":"dillionbaity94@gmail.com"},"directories":{},"maintainers":[{"name":"alzarak","email":"dillionbaity94@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/trading-bot_1.0.0_1774227187732_0.8498281668373506"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T00:53:07.667Z","1.0.0":"2026-03-23T00:53:07.906Z","modified":"2026-03-23T00:53:08.093Z"},"maintainers":[{"name":"alzarak","email":"dillionbaity94@gmail.com"}],"description":"Autonomous stock day trading bot for Claude Code — Alpaca Markets API","homepage":"https://github.com/Alzarak/trading-bot#readme","keywords":["claude-code","trading","alpaca","day-trading","autonomous"],"repository":{"type":"git","url":"git+https://github.com/Alzarak/trading-bot.git"},"author":{"name":"Alzarak"},"bugs":{"url":"https://github.com/Alzarak/trading-bot/issues"},"license":"MIT","readme":"# Trading Bot\n\nA Claude Code plugin that automates stock day trading on US markets via the Alpaca API. After an interactive setup, it trades autonomously — scanning markets, analyzing signals with Claude, and executing trades on a loop.\n\n## Features\n\n- **Interactive setup wizard** — `/initialize` adapts to your experience level and risk tolerance\n- **4 pluggable strategies** — Momentum (RSI+MACD+EMA), Mean Reversion (Bollinger+RSI), Breakout (resistance+volume), VWAP intraday\n- **Built-in risk management** — Circuit breaker, PDT compliance, position limits, mandatory stop-losses\n- **Paper & live trading** — Defaults to paper ($100K simulated); one config change for live\n- **Two deployment modes** — Run inside Claude Code with AI analysis, or `/build` a standalone bot for any server\n- **Full audit trail** — Every signal, risk decision, and order is logged\n- **Optional Alpaca MCP integration** — 44 Alpaca API tools available to Claude for real-time market data (opt-in during setup)\n\n## Requirements\n\n- [Claude Code](https://claude.ai/code) with plugin support\n- Python 3.12+\n- [uv](https://docs.astral.sh/uv/) (for dependency management; also required if enabling MCP server)\n- [Alpaca](https://alpaca.markets/) account (free tier works for paper trading)\n\n## Installation\n\n### From a marketplace\n\nFirst, add the marketplace that hosts this plugin:\n\n```\n/plugin marketplace add Alzarak/claude-marketplace\n```\n\nThen install the plugin:\n\n```\n/plugin install trading-bot@Alzarak-claude-marketplace\n```\n\n### From a local directory (development)\n\n```bash\nclaude --plugin-dir ./trading-bot\n```\n\nDependencies install automatically on first load via the `SessionStart` hook. Run `/reload-plugins` after installation to activate.\n\n## Quick Start\n\n```\n/initialize    # Set up API keys, strategy, risk tolerance\n/build         # Generate standalone bot scripts (optional)\n/run           # Start the trading loop\n```\n\n### 1. Initialize\n\nThe setup wizard asks about your experience level, risk tolerance, budget, strategy preference, and watchlist. Config is saved to `config.json` in the plugin data directory.\n\n### 2. Build (optional)\n\nGenerates a self-contained `trading-bot-standalone/` directory with `bot.py`, `requirements.txt`, `.env.template`, and your selected strategies. Deployable to any server — no Claude Code needed at runtime.\n\n### 3. Run\n\nStarts the trading loop in one of two modes:\n\n- **Agent mode** — Claude analyzes indicator DataFrames and returns structured recommendations, which pass through the Python risk manager before execution\n- **Standalone mode** — Runs the pre-built `bot.py` directly with APScheduler\n\n## Architecture\n\n```\nMarket Data (Alpaca) → MarketScanner → Technical Indicators (pandas-ta)\n                                            ↓\n                        Strategy Evaluation / Claude Analysis\n                                            ↓\n                              RiskManager (deterministic Python)\n                              - Circuit breaker\n                              - PDT guard (< 3 day trades / 5 days)\n                              - Position limits & sizing\n                                            ↓\n                              OrderExecutor → Alpaca API\n                                            ↓\n                              AuditLogger + PortfolioTracker\n```\n\nClaude acts as a **strategy-level analyst only** — all recommendations pass through deterministic Python risk checks before any order is placed.\n\n## Plugin Structure\n\n```\ntrading-bot/\n├── .claude-plugin/plugin.json   # Plugin manifest\n├── commands/                    # /initialize, /build, /run (slash command stubs)\n├── agents/                      # market-analyst, risk-manager, trade-executor\n│   ├── market-analyst.md        # Sonnet — technical indicator analysis\n│   ├── risk-manager.md          # Haiku — deterministic risk validation\n│   └── trade-executor.md        # Haiku — order routing and audit logging\n├── skills/                      # Auto-loaded context and workflows\n│   ├── initialize/SKILL.md      # Setup wizard workflow\n│   ├── build/SKILL.md           # Standalone bot generation workflow\n│   ├── run/SKILL.md             # Trading loop workflow\n│   └── trading-rules/SKILL.md   # Core trading rules (auto-loaded)\n├── hooks/                       # Event-driven automation\n│   ├── hooks.json               # SessionStart + PreToolUse + Stop hooks\n│   └── validate-order.sh        # Order validation (circuit breaker + PDT)\n├── scripts/                     # Python trading modules\n│   ├── bot.py                   # Main entry point (APScheduler loop)\n│   ├── market_scanner.py        # OHLCV + indicator computation\n│   ├── order_executor.py        # Alpaca order routing\n│   ├── risk_manager.py          # Circuit breaker, PDT, position sizing\n│   ├── claude_analyzer.py       # Claude recommendation parsing\n│   ├── state_store.py           # SQLite persistence\n│   └── strategies/              # momentum, mean_reversion, breakout, vwap\n├── references/                  # Detailed documentation\n│   ├── tech-stack.md            # Technology stack, versions, alternatives\n│   ├── trading-strategies.md    # Strategy logic, parameters, entry/exit\n│   ├── risk-rules.md            # Risk rules, circuit breaker, PDT\n│   └── alpaca-api-patterns.md   # Copy-paste Alpaca API code\n└── requirements.txt\n```\n\n## Agents\n\n| Agent | Model | Purpose |\n|-------|-------|---------|\n| **market-analyst** | Sonnet | Analyzes technical indicators, generates BUY/SELL/HOLD signals with confidence scores |\n| **risk-manager** | Haiku | Validates trades against circuit breaker, PDT limits, position sizing constraints |\n| **trade-executor** | Haiku | Executes approved signals through OrderExecutor, logs results for audit trail |\n\n## Hooks\n\n| Event | Type | Purpose |\n|-------|------|---------|\n| **SessionStart** | Command | Installs Python dependencies into plugin venv |\n| **PreToolUse** (Bash) | Command | Gates order submissions — checks circuit breaker and PDT count |\n| **Stop** | Command | Checks for open positions and circuit breaker status before ending a session |\n\n## Configuration\n\nAfter `/initialize`, your config is stored as JSON with these key settings:\n\n| Setting | Description | Default |\n|---------|-------------|---------|\n| `experience_level` | beginner / intermediate / expert | — |\n| `risk_tolerance` | conservative / moderate / aggressive | — |\n| `paper_trading` | Paper trading mode | `true` |\n| `strategies` | Active strategies with weights and params | `[momentum]` |\n| `max_position_pct` | Max equity per position (5%/10%/15% by risk) | varies |\n| `max_positions` | Max concurrent positions | `10` |\n| `max_daily_loss_pct` | Circuit breaker threshold | varies |\n| `watchlist` | Symbols to scan | `AAPL, MSFT, GOOGL, AMZN, SPY` |\n| `use_mcp` | Enable Alpaca MCP server (44 real-time tools) | `false` |\n\nAPI keys are read from environment variables or `.env`:\n\n```\nALPACA_API_KEY=your_key\nALPACA_SECRET_KEY=your_secret\n```\n\n### Alpaca MCP Server (Optional)\n\nDuring `/initialize`, you can opt into the Alpaca MCP server. If enabled, it's added to your project via `claude mcp add alpaca` and gives Claude direct access to 44 Alpaca API tools (quotes, positions, account info). Paper trading is the default. If you skip MCP, all API calls go through the Python alpaca-py SDK.\n\n## Safety\n\n- **Circuit breaker** halts all trading when daily loss exceeds the configured threshold\n- **PDT guard** blocks trades if 3+ day trades occur in a rolling 5-business-day window (accounts under $25K)\n- **PreToolUse hook** validates every order submission before it reaches Alpaca\n- **Stop hook** verifies all positions have stop-losses before ending a session\n- **Mandatory stop-losses** on all positions (ATR-based, minimum 0.5%)\n- **No averaging down** — the bot will not add to losing positions\n- **Graceful shutdown** closes positions on SIGINT/SIGTERM\n\n## Tech Stack\n\n| Package | Purpose |\n|---------|---------|\n| [alpaca-py](https://github.com/alpacahq/alpaca-py) 0.43.2 | Trading execution & market data |\n| [pandas-ta](https://github.com/twopirllc/pandas-ta) 0.4.71b0 | 150+ technical indicators |\n| [APScheduler](https://github.com/agronholm/apscheduler) 3.x | Market-hours-aware scheduling |\n| [pydantic-settings](https://github.com/pydantic/pydantic-settings) 2.x | Typed config with .env support |\n| [loguru](https://github.com/Delgan/loguru) | Structured logging with rotation |\n| [rich](https://github.com/Textualize/rich) | Terminal UI for setup wizard |\n\nSee `references/tech-stack.md` for the full stack reference including version compatibility, alternatives considered, and what not to use.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a9b8516d0b52debed39d1daec0c64a8d"}