Spaces:
Running
Running
File size: 3,696 Bytes
4811dd1 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 |
# Munger Engine API
This project converts the Munger Stock Analysis Strategy into a deployable API for Hugging Face Spaces.
## Quick Start
### Local Development
1. Install dependencies:
```bash
npm install
```
2. Run the development server:
```bash
npm run dev
```
*Note: If behind a corporate proxy or experiencing SSL issues, use:*
```bash
npm run dev:insecure
```
3. Endpoints will be available at `http://localhost:3000/api/v1/...`
### API Endpoints
> [!TIP]
> You can import the included `munger-api.postman_collection.json` file into Postman to quickly test all endpoints.
| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `GET` | `/api/v1/health` | Check system status. |
| `POST` | `/api/v1/sync` | Trigger scan. Payload: `{ "force": true, "symbols": ["AAPL"] }`. |
| `GET` | `/api/v1/signals` | Get list of filtered stocks. Query params: `signal` (e.g. BUY_TRIGGER), `interesting=true` (BUY_TRIGGER + WATCHLIST). |
| `GET` | `/api/v1/ticker/[symbol]` | Get detailed analysis for a specific stock. |
| `GET` | `/api/v1/portfolio` | Get Alpaca Paper Trading positions. |
### Usage Examples
**Trigger Scan (Full):**
```bash
curl -X POST http://localhost:3000/api/v1/sync \
-H "Content-Type: application/json" \
-d '{"force": true}'
```
**Trigger Scan (Specific Symbols - Ideal for Testing):**
```bash
curl -X POST http://localhost:3000/api/v1/sync \
-H "Content-Type: application/json" \
-d '{"symbols": ["ERIE", "AAPL"], "force": true}'
```
**Get Signals:**
```bash
curl http://localhost:3000/api/v1/signals
```
**Get Ticker Details:**
```bash
curl http://localhost:3000/api/v1/ticker/AAPL
```
## Order Execution Engine
The API uses a deterministic **Trade Plan Builder** for signals marked as `BUY_TRIGGER`.
### Advanced Logic Blueprint
* **Playbook:** `BUY_TRIGGER_REBOUND_CONFIRM` (Breakout-style Entry).
* **Risk Model:** Wilder's ATR(14) with 1:3 Risk-Reward Ratio.
* *Risk Unit (R):* 2.0 * ATR.
* **Entry Order:** `STOP_LIMIT` (Day).
* *Stop Price:* Trigger Level + Tick ($0.01).
* *Limit Price:* Entry Stop + Slippage Buffer (0.75%).
* *Expiry:* 5 Trading Days.
* **Protective Stop:** `STOP` Order (GTC).
* *Price:* Entry - 1R.
* **Take Profit:** `LIMIT` Order (GTC).
* *Price:* Entry + 3R.
* **Position Sizing:** Portfolio Aware (Alpaca Integration).
* Fetches Equity & Buying Power.
* Risks **0.5%** of Equity per trade.
* Caps Position Size at **10%** of Equity.
* Checks Buying Power constraints.
* **Output:** Returns a comprehensive JSON `TradePlan` including specific order parameters, risk calculation details, and sizing constraints.
### Deployment to Hugging Face Spaces
1. Create a new **Docker** Space on Hugging Face.
2. Upload this repository.
3. Set the following **Secret** variables in your Space settings:
* `ALPACA_KEY`
* `ALPACA_SECRET`
* `HF_TOKEN` (optional, for future dataset integration)
The Dockerfile is configured to run the Next.js application on port 7860.
### Hugging Face Space Access
Your API is deployed and accessible at:
`https://dromerosm-munger-engine.hf.space`
**Authentication Required**
The API is protected by an API Key. All requests to `/api/*` endpoint must include the `x-api-key` header.
```bash
x-api-key: <YOUR_API_KEY>
```
**Example:**
```bash
curl -H "x-api-key: 5664955..." https://dromerosm-munger-engine.hf.space/api/v1/health
```
## Configuration
* **Watchlist**: Currently uses `scripts/sp500_symbols.json`.
* **Persistence**: Data is stored in `data/stocks.json`. **Note:** On standard HF Spaces, this data is ephemeral and will reset on restart. For production, consider using HF Datasets or an external DB.
|