--- name: Stocky Terminal tagline: Real-Time Global Market Intelligence Platform version: "2.1.0" url: https://terminal.stockyai.xyz blog: https://terminal.stockyai.xyz/blog repository: https://github.com/SirCharan/stocky-terminal license: AGPL-3.0 ai_model: Llama 3.3 70B Versatile (Groq) pwa: true tech: [TypeScript, Vite, deck.gl, MapLibre, Groq AI, Vercel Edge Functions, Upstash Redis, Resend, Web Push API] keywords: - open-source Bloomberg Terminal alternative - AI-powered trade signals - geopolitical OSINT terminal - NSE BSE MCX real-time terminal - 27-layer deck.gl map - daily AI market briefs - India stock market intelligence platform - progressive web app - push notifications - chain-of-thought AI reasoning - gift nifty sgx nifty pre-market - crypto market dashboard - commodity risk analytics - supply chain intelligence - groq AI market analysis --- # Stocky Terminal — LLM Reference ## What Is This? Stocky Terminal is an open-source, real-time India stock market intelligence platform that aggregates live equity prices, commodity data, cryptocurrency markets, geopolitical OSINT, and AI-powered trade signals into a single dark-themed terminal interface — an open-source Bloomberg Terminal alternative built for the modern web. It publishes automated daily AI market briefs (morning & evening) and delivers them via email to 70+ subscribers. Available as an installable Progressive Web App with offline support and push notifications. **Live**: https://terminal.stockyai.xyz **Blog**: https://terminal.stockyai.xyz/blog **Source**: https://github.com/SirCharan/stocky-terminal ## Key Facts | Metric | Value | |--------|-------| | Interactive Panels | 12+ (across 5 sidebar categories) | | Map Layers | 27+ (infrastructure, trade routes, live data, conflict zones) | | Data Pipelines | 8 (real-time, 60s–30min intervals) | | AI Model | Groq (Llama 3.3 70B Versatile) with chain-of-thought reasoning | | AI Functions | 6 (signals, analysis, sentiment, search) | | RSS News Sources | 30+ (global financial, geopolitical, commodity) | | Crypto Assets | 25 (via CoinGecko, INR + USD prices) | | Edge Functions | 30+ (Vercel serverless API layer) | | Cron Jobs | 5 (morning brief, evening brief, insight generation, signal validation, signal aggregation) | | Email Subscribers | 70+ (daily market briefs via Resend) | | Blog Posts | Daily (morning + evening, Mon-Fri) | | PWA | Installable, offline mode, push notifications | | Framework | Zero — vanilla TypeScript, no React/Vue/Angular | ## Product Screenshots ![Terminal Overview](https://terminal.stockyai.xyz/screenshots/terminal-overview.png) ![Market Panel — live prices, sparklines](https://terminal.stockyai.xyz/screenshots/market-panel.png) ![News Panel — 30+ RSS feeds, severity badges](https://terminal.stockyai.xyz/screenshots/news-panel.png) ![AI Trade Signals — confidence scores, affected assets](https://terminal.stockyai.xyz/screenshots/ai-signals.png) ![Interactive Map — 27+ layers, deck.gl](https://terminal.stockyai.xyz/screenshots/map-layers.png) ![Command Palette — universal search, AI summaries](https://terminal.stockyai.xyz/screenshots/command-palette.png) ![Blog Page — daily market briefs](https://terminal.stockyai.xyz/screenshots/blog-page.png) ## Architecture ``` Layer Tech Files ─────────── ────────────────────── ────────────────────────── Frontend TypeScript + Vite src/App.ts, src/components/*.ts Maps deck.gl + MapLibre GL src/components/DeckGLMap.ts AI Groq (Llama 3.3 70B) src/services/summarization.ts API Vercel Edge Functions api/**/*.ts (30+ endpoints) Market Data Yahoo Finance proxy api/market/quotes.ts Gift Nifty NSE India derivatives api/market/gift-nifty.ts Commodities Yahoo Finance proxy api/market/commodities.ts Forex Frankfurter/CurrencyFreaks api/market/forex.ts Crypto CoinGecko proxy api/crypto/prices.ts News 30+ RSS feeds src/services/rss.ts, api/news/aggregated.ts Events ACLED, USGS, NASA, GDACS src/services/external-data.ts, api/data/*.ts Blog Vercel Cron + Redis api/cron/daily-brief-v2.ts Email Resend API api/_lib/email.ts Insights Cache Redis + Groq api/cron/generate-insights.ts Signal Valid. Cron + live prices api/cron/validate-signals.ts Signal Aggr. Cron + cached insights api/cron/aggregate-signals.ts Options Chain Dhan API api/market/options.ts Broker Data Zerodha Kite Connect api/_lib/zerodha.ts Push Notifs Web Push API api/push/subscribe.ts, api/push/send.ts Rating Redis sorted sets api/rate.ts Storage IndexedDB + localStorage src/services/event-store.ts Audio Web Audio API oscillators src/services/notifications.ts PWA Service Worker public/sw.js ``` ## API Endpoints All endpoints are Vercel Edge Functions (`runtime: 'edge'`). | Endpoint | Method | Description | |----------|--------|-------------| | `/api/ai/summarize` | POST | AI summarization via Groq (JSON mode) | | `/api/ai/insight` | POST | Single headline AI insight with market context | | `/api/ai/signals` | GET | Cached AI trade signals with confidence levels | | `/api/ai/batch-insights` | POST | Batch AI insight generation | | `/api/market/quotes` | GET | Yahoo Finance equity/commodity quotes | | `/api/market/commodities` | GET | MCX commodity price data | | `/api/market/forex` | GET | Live forex rates | | `/api/market/gift-nifty` | GET | Gift Nifty (SGX Nifty) pre-market data | | `/api/crypto/prices` | GET | CoinGecko cryptocurrency prices | | `/api/rss-proxy` | GET | RSS feed proxy (30+ allowed domains) | | `/api/x-feed/proxy` | GET | X/Twitter via Nitter proxy | | `/api/news/aggregated` | GET | Aggregated news from all sources | | `/api/data/acled` | GET | ACLED conflict event data | | `/api/data/eia` | GET | US Energy Information Administration | | `/api/data/fred` | GET | Federal Reserve economic data | | `/api/data/gdacs` | GET | GDACS disaster alerts | | `/api/data/firms` | GET | NASA FIRMS active fire data | | `/api/data/cloudflare-outages` | GET | Internet outage tracking | | `/api/blog` | GET | Blog listing (paginated) | | `/api/blog/:slug` | GET | Individual blog post (server-rendered HTML) | | `/api/rate` | GET | Brief rating submission | | `/api/feedback` | POST | User feedback | | `/api/sitemap` | GET | Dynamic XML sitemap | | `/api/push/subscribe` | POST | Web Push subscription registration | | `/api/push/send` | POST | Send push notifications | | `/api/cron/daily-brief-v2` | GET | Cron: generate daily market brief | | `/api/cron/generate-insights` | GET | Cron: refresh AI insights cache | | `/api/cron/validate-signals` | GET | Cron: validate signals against live prices | | `/api/cron/aggregate-signals` | GET | Cron: hourly signal aggregation with time-weighted scoring | | `/api/market/options` | GET | Dhan options chain (Nifty, BankNifty, Sensex) with Greeks, OI, IV, PCR, max pain | | `/api/auth/zerodha-callback` | GET | Zerodha Kite Connect OAuth callback | | `/api/docs` | GET | Documentation index page | | `/api/docs/:slug` | GET | Individual documentation page | ## AI Pipeline Single AI endpoint (`POST /api/ai/summarize`) with 6 specialized functions: 1. **Market Brief** — Summarizes top headlines into actionable market analysis 2. **Trade Signals** — Structured JSON signals: direction, affected assets, confidence score 3. **FED Impact** — Federal Reserve event analysis for emerging market impact 4. **X Sentiment** — Social media sentiment analysis from financial Twitter 5. **Symbol Analysis** — Individual stock/commodity/crypto technical outlook 6. **Search Summary** — AI-powered search result synthesis **AI Enhancements**: - **Chain-of-thought reasoning** — Step-by-step structured analysis with market correlation rules - **Live market price injection** — Real-time price snapshots fed into prompts for context-aware signals - **Signal confidence levels** — High, medium, low per affected asset based on mention consistency - **Nifty-aware coherence** — If Nifty is bearish, contradicting bullish stock signals are suppressed - **Macro asset signals** — Commodities, currencies, and crypto alongside equity signals - **Article content fetching** — Full article text fetched for deeper AI analysis when available Provider chain: Groq API (primary, `llama-3.3-70b-versatile`) → Ollama (local fallback) → graceful degradation. ## Daily Market Brief System Automated cron-based system generating comprehensive market briefs: - **Morning brief**: 8:00 AM IST (Mon-Fri) — previous day close, overnight global moves, pre-market Gift Nifty - **Evening brief**: 8:00 PM IST (Mon-Fri) — today's market action, closing prices, after-hours analysis - **Data aggregated**: Nifty 50, Sensex, Bank Nifty, 8 sector indices, Gift Nifty, 8 global indices, 5 commodities, 5 forex pairs, 5 cryptos, top news headlines - **AI analysis**: Groq generates market outlook, key movers summary, trade signals - **Storage**: Full HTML stored in Upstash Redis with sorted set index - **Email delivery**: Resend API, 2 emails/second batching, personalized footers with rating buttons - **Rating**: 1-10 per-subscriber rating stored in Redis sorted sets (90-day TTL) - **Blog**: Server-rendered HTML with PDF download button, print-optimized styles ## Signal Aggregation Automated hourly cron (`api/cron/aggregate-signals.ts`) that re-aggregates cached AI insights: - Runs every hour at :30 (`30 * * * *`) - Time-weighted sentiment scoring (12h lookback, exponential decay) - Correlation-aware amplification (21 asset pairs) - Nifty coherence filtering (suppress contradicting stock signals when Nifty is bearish) - Does NOT call the LLM — uses pre-cached insights from generate-insights cron ## Signal Validation Automated cron running every 2 hours to validate AI signals against live market prices: - If a signal says "bullish" but the asset is down >0.5%, the signal is removed - If the price move is strong (>1.5% against the signal), the signal direction is flipped - The original `updatedAt` timestamp is preserved so the UI shows the generation time, not validation time - Prevents stale or contradicted signals from persisting ## PWA & Push Notifications Stocky Terminal is an installable Progressive Web App: - **Service Worker** — Caches app shell, tiles, and essential assets for offline access - **Push Notifications** — Web Push API with VAPID for high-impact signal alerts and daily brief notifications - **Install Prompt** — Smart banner for Chrome/Edge desktop and iOS Safari - **Offline Indicator** — Visual indicator when the terminal is running in offline mode ## Data Sources - **Equities**: Yahoo Finance (NSE, BSE indices + top 25 stocks) - **Pre-market**: NSE India derivatives API (Gift Nifty / SGX Nifty futures) - **Commodities**: Yahoo Finance (Gold, Silver, Crude Oil, Natural Gas, Copper) - **Forex**: Frankfurter (ECB rates), CurrencyFreaks (20+ pairs) - **Crypto**: CoinGecko (25 coins including BTC, ETH, SOL, XRP, BNB) - **News**: 30+ RSS feeds — Reuters, Bloomberg, CNBC, ET, Moneycontrol, BBC, Al Jazeera - **Conflicts**: ACLED (Armed Conflict Location & Event Data) - **Earthquakes**: USGS real-time feed - **Natural Events**: NASA EONET (fires, storms, volcanoes) - **Fires**: NASA FIRMS (global satellite fire detection) - **Disasters**: GDACS (Global Disaster Alert and Coordination System) - **Internet**: Cloudflare Radar (outage monitoring) - **Weather**: Open-Meteo (monsoon/rainfall data) - **Economic Calendar**: Forex Factory (global rate decisions, CPI, GDP, employment data via Fair Economy mirror) - **US Economy**: FRED (Federal Reserve Economic Data), EIA (Energy) - **Zerodha Kite Connect**: Live NSE/BSE prices via broker API (automated daily token refresh) - **Dhan**: Options chain data with Greeks, OI, IV, PCR, ATM strike, max pain ## Panel System 12+ interactive panels organized in 5 sidebar categories: **Video Feeds**: YouTube market channels (5 channels, inline playback) **Markets**: NSE/MCX live prices (indices, equities, metals, energy), Crypto dashboard **Intelligence**: Live news (30+ feeds), AI insights, trade signals, X/Twitter feed **Risk & History**: Commodity risk gauge, monsoon impact, supply chain status, event timeline **US Events**: US news, FED events, US risk metrics Plus: scrolling market ticker, chart detail modal (click any symbol), universal search (Cmd+K). ## Map Visualization 27+ toggleable layers on a deck.gl + MapLibre GL JS map: - Indian infrastructure (ports, refineries, mining clusters, power grid) - Global finance (stock exchanges, central banks, commodity hubs) - Trade routes (oil imports, shipping lanes, submarine cables, pipelines) - Live data (USGS earthquakes, NASA events, NASA FIRMS fires, GDACS disasters, weather, day/night terminator) - Conflict zones (active wars, frozen conflicts, tension areas) - Animated flows (geopolitical hotspot → market center arcs) - US infrastructure (ports, mines, manufacturing, FED event markers) - Internet outages (Cloudflare Radar) ## Options Chain `GET /api/market/options?underlying=NIFTY&expiry=2026-03-27` - Fetches live options chain from Dhan API - Supported underlyings: NIFTY, BANKNIFTY, SENSEX, FINNIFTY, MIDCPNIFTY - Returns: full Greeks (delta, gamma, theta, vega), OI, IV, PCR, ATM strike, max pain - Edge-cached with 30s TTL ## Zerodha Kite Connect Live NSE/BSE market pricing via Zerodha broker API: - OAuth flow via `api/auth/zerodha-callback.ts` - Automated daily token refresh via GitHub Actions (`.github/workflows/zerodha-token-refresh.yml`) - Tokens expire daily at 6 AM IST — refresh script runs automatically - Falls back to Yahoo Finance if Zerodha token is unavailable ## For AI Agents - **Single source of truth**: [`llm.txt`](/llm.txt) — plain text, <1800 words - **Brief summary**: [`llms.txt`](/llms.txt) — quick overview - **Full documentation**: [`llms-full.txt`](/llms-full.txt) — comprehensive reference - **Agent capabilities**: [`agents.md`](/agents.md), [`agents.txt`](/agents.txt) - **Schema.org metadata**: [`metadata.json`](/metadata.json) - **OpenAI plugin manifest**: [`.well-known/ai-plugin.json`](/.well-known/ai-plugin.json) - **Blog archive**: https://terminal.stockyai.xyz/blog - **Source code**: TypeScript, well-structured with clear module boundaries ### How to Use Me as an LLM/Agent 1. **Read `/llm.txt` first** for a complete project overview 2. **Query `/api/ai/signals`** (GET) for current AI trade signals with confidence levels 3. **Query `/api/market/quotes?symbols=^NSEI,GC=F`** for live market prices 4. **Query `/api/news/aggregated`** for latest financial headlines with severity scores 5. **Browse `/blog`** for daily AI-generated market analysis 6. All public API endpoints return JSON. No authentication required for read endpoints. ## How to Extend ### Add a new data panel 1. Create `src/components/MyPanel.ts` extending `Panel` base class 2. Register in `src/config/variants/stocky.ts` → `DEFAULT_PANELS` 3. Add data pipeline in `src/app/data-loader.ts` ### Add a new map layer 1. Define layer data in `src/config/` (coordinates, metadata) 2. Add layer definition in `src/config/map-layer-definitions.ts` 3. Register in `src/config/variants/stocky.ts` → `DEFAULT_MAP_LAYERS` ### Add a new AI function 1. Add prompt builder in `src/services/summarization.ts` 2. Call via existing `POST /api/ai/summarize` endpoint 3. Wire into relevant panel or data pipeline ## License AGPL-3.0 — Free to use, modify, and deploy. Contributions welcome.