🦙 Trailing Llama

🦙 How Trailing Llama works

Trailing Llama is an automated trading harness for your Alpaca account — works with both paper (fake money) and live (real money) accounts, selected per-account when you register your keys. It watches a list of symbols and decides when to enter / exit based on simple-moving-average (SMA) crossovers, with server-side trailing stops managed at Alpaca.

The strategy in one paragraph

For each watchlist symbol, the bot computes a fast SMA (default 10 periods) and a slow SMA (default 30 periods) on 1-minute bars. When the fast SMA crosses above the slow SMA by a configurable threshold, the bot buys. When the fast SMA crosses below, it sells. A small neutral zone (default 2.5%) suppresses whipsaw signals.

Trailing stops

Every new position gets a 10% trailing stop placed at Alpaca server-side as a trailing_stop order, GTC. Alpaca tracks the high-water mark tick-by-tick and fires the stop without the bot needing to be running. Once a position's unrealized gain crosses +10%, the bot cancels the loose stop and replaces it with a tighter 5% trail to lock in gains.

Additional guardrails

• SPY regime filter — if SPY is below its 200-day SMA, new buys are suppressed (existing positions and stops are unaffected).
• 31-day loss blocklist — if a position is sold at a loss, the symbol is blocked from re-entry for 31 days. You can override manually (a wash-sale warning will display).
• Market-hours only — the bot is dormant on weekends, overnight, and US market holidays (including early-close days).
• Profit-take (optional) — sell a configurable fraction of any position once unrealized gain crosses your threshold.

Getting your Alpaca keys

For paper trading (recommended for first use):

1. Sign up free at https://app.alpaca.markets (no funding needed for paper trading).
2. Confirm your email.
3. Open the paper dashboard at https://app.alpaca.markets/paper/dashboard/overview.
4. Click "View" / "Generate New Key" under API Keys.
5. Copy the Key ID (starts with PK) and the Secret.
6. In Trailing Llama, scroll to "Add Alpaca account", select Paper, and paste them in.

For LIVE trading (real money — extra confirmation required):

1. Complete Alpaca's brokerage onboarding (KYC, ID, funding) at https://app.alpaca.markets.
2. Open the live dashboard at https://app.alpaca.markets/dashboard.
3. Generate live API Keys (Key ID starts with AK).
4. An admin must first set the encryption key for live storage: fly secrets set BOT_KEY_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
5. In Trailing Llama, scroll to "Add Alpaca account", select LIVE, paste your keys, and type I UNDERSTAND in the confirmation field.
6. The bot will now place real-money orders on your behalf according to its strategy. You accept full responsibility for the outcomes.

Important: the bot routes to paper-api.alpaca.markets for paper-flagged accounts and api.alpaca.markets for LIVE-flagged accounts. Choosing the wrong type at registration produces a 401. Each account row independently selects its endpoint based on its stored paper flag.

Multi-user model

Each Alpaca paper account UUID maps to exactly one bot user (free-tier Alpaca = one paper account per login). To run two isolated bot users, register two different Alpaca logins. An admin in /admin/users approves each new user's bot before it can trade automated entries.

Dashboard at a glance

• Symbol pills show current state: held (green = gain, red = loss), watchlist, or blocked.
• Click a pill to expand: live quote, chart, news sentiment, position details, manual buy/sell.
• The llama icon's mood reflects today's portfolio P/L (smoking cigar = happy, crying = sad).
• Banners at the top show: paused bot, market-closed state, risk-off regime, admin-disabled bot, or read-only-view.