Getting Started

Get Mahoraga running in 10 minutes.

Prerequisites

• Node.js 18 or higher
• Alpaca account (free, supports paper trading)
• OpenAI API key (for LLM analysis)

1. Clone and Install

git clone https://github.com/ygwyg/MAHORAGA.git
cd MAHORAGA
npm install
cd dashboard && npm install && cd ..

2. Configure API Keys

Create a .dev.vars file in the project root:

ALPACA_API_KEY=your_alpaca_key
ALPACA_API_SECRET=your_alpaca_secret
ALPACA_PAPER=true
OPENAI_API_KEY=your_openai_key
KILL_SWITCH_SECRET=any_random_string_here

3. Get Your API Keys

Alpaca (Required)

1. Create a free account at alpaca.markets
2. Go to Paper Trading → API Keys
3. Click Generate New Keys
4. Copy both the key and secret to .dev.vars

OpenAI (Required)

1. Create an account at platform.openai.com
2. Add billing and credits ($10 is plenty to start)
3. Go to API Keys → Create new secret key
4. Add to .dev.vars: OPENAI_API_KEY=sk-your_key

4. Start the MCP Server

npm run dev

The server runs at http://localhost:8787

5. Start the Trading Agent

In a new terminal:

node agent-v1.mjs

The agent will start monitoring StockTwits and making trading decisions.

6. Open the Dashboard (Optional)

In another terminal:

cd dashboard
npm run dev

Open http://localhost:5173 in your browser to monitor:

• Account balance and positions
• Current signals and research
• Agent activity logs
• LLM cost tracking

What Happens Next

The agent runs in a loop:

1. Data gathering (24/7) — Fetches trending stocks from StockTwits
2. LLM research — Analyzes top signals for red flags and catalysts
3. Trading (market hours) — Executes buy/sell based on LLM decisions
4. Position management — Monitors held positions for exit signals

Next Steps

• Configuration — Customize trading parameters
• Architecture — How the system works
• Extending — Add your own data sources