Getting Started

Get Mahoraga running in 10 minutes.

Prerequisites

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
OPENAI_BASE_URL=https://api.openai.com/v1  # optional (OpenAI-compatible proxy)
MAHORAGA_API_TOKEN=generate_a_secure_random_token
KILL_SWITCH_SECRET=another_secure_random_token

Generate secure tokens with: openssl rand -base64 48

Important: Always start with ALPACA_PAPER=true until you understand how the system works.
SecretPurpose
MAHORAGA_API_TOKENRequired for all API access (dashboard, curl commands)
KILL_SWITCH_SECRETEmergency shutdown + approval token signing

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
Estimated costs: ~$0.50-2/day using gpt-4o-mini, depending on trading activity.

4. Start the Server

npm run dev

The server runs at http://localhost:8787. You should see output like:

Ready on http://localhost:8787

5. Enable the Trading Agent

All API endpoints require your MAHORAGA_API_TOKEN:

# Set your token (copy from .dev.vars)
export MAHORAGA_TOKEN="your_token_here"

# Enable the agent
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/enable

# Check status
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/status

The agent will start monitoring StockTwits and Reddit for trading signals.

6. Open the Dashboard (Optional)

In another terminal:

cd dashboard
npm run dev

Open http://localhost:5173 in your browser.

First time setup: Click the Settings icon and enter your MAHORAGA_API_TOKEN to authenticate.

The dashboard shows:

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