# Stocky Terminal — Full Documentation for LLMs

> Open-source Bloomberg Terminal alternative — an India stock market intelligence platform with AI-powered trade signals, daily AI market briefs, geopolitical OSINT, and a 27-layer deck.gl interactive map. Installable PWA with push notifications.

URL: https://terminal.stockyai.xyz
Blog: https://terminal.stockyai.xyz/blog
Source: https://github.com/SirCharan/stocky-terminal
License: AGPL-3.0

Single source of truth: /llm.txt | Agent guide: /agents.txt | Schema: /metadata.json

---

## Overview

Stocky Terminal is a free, open-source, browser-based NSE BSE MCX real-time terminal that combines live market data, geopolitical intelligence, natural disaster tracking, and AI analysis into a single dashboard. It publishes automated daily market briefs and delivers them via email to 70+ subscribers. Available as an installable Progressive Web App with offline support and push notifications. Designed as an alternative to Bloomberg Terminal for retail traders, analysts, and OSINT researchers.

## Data Panels (12+ total)

1. Market Ticker — scrolling real-time price ticker with volatility-adjusted speed
2. NSE/MCX Live Prices — Indian equity and commodity markets (Nifty 50, Sensex, Bank Nifty, Gift Nifty, sector indices, top 25 equities)
3. Market Headlines — aggregated from 30+ RSS news feeds with severity badges
4. AI Market Insights — Groq-powered market summaries with social sharing
5. High-Impact Signals — AI-generated trade signals with confidence scores and affected assets
6. India Commodity Risk — composite risk gauge (0-100) for Indian commodities
7. Monsoon Impact — weather impact analysis on Indian agriculture and markets
8. Supply Chain Intel — global supply chain monitoring and chokepoint alerts
9. Event History — historical event log with search and filtering
10. Crypto Panel — 25 cryptocurrency assets with live prices in INR + USD
11. X/Twitter Feed — embedded social feed for market sentiment with FED/MCX/WAR filters
12. Market Video Feeds — YouTube market analysis videos (5 channels)

## Map Layers (27+ interactive layers)

India-specific: Indian Ports, Refineries, Mining Clusters, Monsoon Data, Oil Import Routes, Power Grid, LAC Hotspots
Finance: Stock Exchanges, Financial Centers, Central Banks, Commodity Hubs
Trade: Trade Routes, Undersea Cables, Pipelines, Economic Zones, Waterways
Live data: Weather, Natural Events (NASA EONET), Earthquakes (USGS), Active Fires (NASA FIRMS), Day/Night Terminator
Geopolitical: War Countries, Conflict Hotspots (ACLED), Chokepoints
US infrastructure: US Ports, US Mines, US Manufacturing, US Trade Routes, US Fires
Advanced: GDACS Disaster Alerts, Internet Outages (Cloudflare Radar), Animated Effects (particle flows, arc animations)

## Daily Market Brief & Blog

Automated AI-generated market briefs published twice daily (Mon-Fri):
- Morning brief at 8:00 AM IST (2:30 AM UTC) — covers previous day close, pre-market indicators, overnight global moves
- Evening brief at 8:00 PM IST (2:30 PM UTC) — covers today's market action, closing prices, after-hours analysis

Each brief includes:
- Indian indices: Nifty 50, Sensex, Bank Nifty, Nifty IT, Nifty Pharma, Nifty Auto, Nifty FMCG, Nifty Metal, Nifty Realty, Nifty Energy
- Pre-market: Gift Nifty (SGX Nifty futures via NSE India derivatives API)
- Global indices: S&P 500, NASDAQ, Dow Jones, FTSE 100, DAX, Nikkei 225, Hang Seng, Shanghai Composite
- Commodities: Gold, Silver, Crude Oil, Natural Gas, Copper
- Forex: USD/INR, EUR/USD, GBP/USD, USD/JPY, AUD/USD
- Crypto: BTC, ETH, SOL, XRP, BNB
- Top news headlines with AI analysis
- AI market outlook and trade signals with confidence levels

Blog listing: https://terminal.stockyai.xyz/blog
Individual briefs: https://terminal.stockyai.xyz/blog/{slug}

## Email Delivery System

- 70+ subscribers receive each brief via Resend API
- Personalized emails with blog link, WhatsApp community link, and 1-10 rating buttons
- Ratings stored in Redis (per-subscriber, per-brief tracking)
- Rate-limited delivery: 2 emails/second (Resend free tier)

## Pre-Cached AI Insights

- Cron job runs every 15 minutes
- Fetches high-severity headlines from aggregated news
- Generates batch AI insights via Groq (Llama 3.3 70B Versatile) with chain-of-thought reasoning
- Live market prices injected into prompts for context-aware analysis
- Signal confidence levels: high, medium, low per affected asset
- Nifty-aware coherence: if Nifty is bearish, bullish stock signals are suppressed
- Macro asset signals: commodities, currencies, and crypto alongside equity signals
- Cached in Redis, served via /api/ai/signals and /api/ai/insight

## Signal Aggregation

- Cron job runs every hour at :30 (`api/cron/aggregate-signals.ts`)
- Re-aggregates cached AI insights into top-5 signals
- Time-weighted sentiment scoring (12h lookback, exponential decay)
- Correlation-aware amplification (21 asset pairs)
- Nifty coherence filtering
- Does NOT call the LLM — uses pre-cached insights from generate-insights cron

## Signal Validation

- Cron job runs every 2 hours
- Validates AI signals against live market prices
- Signals contradicted by >0.5% price move are removed
- Signals contradicted by >1.5% strong move are flipped (direction reversed, confidence reduced)
- Original updatedAt timestamp preserved so UI reflects generation time

## Data Sources

- Yahoo Finance — equities, indices, commodities, forex (NSE, BSE, global)
- NSE India — Gift Nifty / SGX Nifty futures (derivatives API with session cookies)
- CoinGecko — 25 cryptocurrency assets (BTC, ETH, SOL, XRP, BNB, WRX, ADA, DOGE, etc.)
- Finnhub — US market data, company profiles
- Frankfurter — ECB exchange rates
- CurrencyFreaks — forex rates (20+ pairs)
- ACLED — Armed Conflict Location & Event Data
- USGS — real-time earthquake data (magnitude 5+)
- NASA EONET — natural events (wildfires, storms, volcanoes)
- NASA FIRMS — active fire detection (global satellite fire data)
- GDACS — Global Disaster Alert and Coordination System
- Cloudflare Radar — internet outage monitoring
- Open-Meteo — weather and monsoon forecasting
- Forex Factory — Global economic calendar (rate decisions, CPI, GDP, employment data via Fair Economy mirror)
- FRED — Federal Reserve Economic Data
- EIA — US Energy Information Administration
- 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
- 30+ RSS feeds: Reuters, Bloomberg, CNBC, BBC, Al Jazeera, Economic Times, Moneycontrol, LiveMint, Business Standard, Nikkei Asia, SCMP, Kitco, OilPrice, India Today, and more

## AI Features

- Powered by Groq API (Llama 3.3 70B Versatile) with Ollama local fallback
- 6 specialized AI functions: market brief, trade signals, FED impact, X sentiment, symbol analysis, search summary
- Chain-of-thought structured reasoning with market correlation rules
- Live market price injection into prompts for context-aware analysis
- Signal confidence levels (high/medium/low) per affected asset
- Nifty-aware signal coherence filtering
- Macro asset class signal analysis
- Article content fetching for deeper analysis
- JSON mode enforcement for reliable parsing
- Pre-cached insights refreshed every 15 minutes
- Signal validation every 2 hours against live prices
- AI-generated daily market briefs with comprehensive analysis

## PWA & Push Notifications

- Installable Progressive Web App with standalone mode
- Service Worker caching for offline access (app shell, tiles, market data)
- Web Push API notifications for high-impact signals and daily briefs
- Smart install prompt for Chrome/Edge and iOS Safari
- Offline indicator showing connection status

## 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

## Zerodha Kite Connect

- Live NSE/BSE market prices via Zerodha broker API
- OAuth flow via `/api/auth/zerodha-callback`
- Automated daily token refresh via GitHub Actions
- Tokens expire daily at 6 AM IST — refresh runs automatically
- Falls back to Yahoo Finance if Zerodha token is unavailable

## 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

## User Interface

- Dark terminal aesthetic (neon orange-red accent, monospace typography)
- Command Palette (Cmd/Ctrl+K) for universal search with AI summaries
- Region selector: India, Global, Asia, MENA, Europe, Americas, USA
- 5 sidebar tabs: Video Feeds, Markets, Intelligence, Risk & History, US Events
- Chart detail modal with interactive SVG sparklines and AI analysis
- PDF download button on all blog posts (with print-optimized styles)
- 3-tier audio alert system (oscillator-based)
- Browser and push notifications for high-impact events
- Social sharing to WhatsApp, Telegram, LinkedIn, X

## Technical Architecture

- Frontend: TypeScript + Vite (zero frameworks, vanilla DOM manipulation)
- Maps: deck.gl + MapLibre GL JS with custom layer rendering
- Charts: Custom SVG sparklines with hover crosshair
- Styling: CSS Custom Properties (dark terminal theme)
- API: Vercel Edge Functions (25+ serverless endpoints)
- AI: Groq API (Llama 3.3 70B Versatile) with chain-of-thought reasoning
- Blog: Server-rendered HTML stored in Upstash Redis
- Email: Resend API with batched delivery (2 req/s)
- Cache: Upstash Redis (blog storage, AI insight cache, ratings)
- Cron: Vercel Cron (5 scheduled jobs: morning brief, evening brief, insight generation, signal validation, signal aggregation)
- Storage: IndexedDB (event store) + localStorage (user preferences)
- Audio: Web Audio API (oscillator-based, no external audio files)
- PWA: Service Worker + Web Push API (offline mode, push notifications)
- Deployment: Vercel with edge caching across IAD, SIN, BOM regions

## API Endpoints (30+)

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, FINNifty) 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 |

## 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.

## Regions Supported

- India (NSE, BSE, MCX focus)
- Global (worldwide view)
- Asia (Nikkei, SCMP, Straits Times feeds)
- MENA (Middle East & North Africa)
- Europe
- Americas
- USA (S&P 500, Dow Jones, NASDAQ, US infrastructure layers)

## Pricing

Free and open-source (AGPL-3.0 license). No subscription required.

## More Details

- Single source of truth: /llm.txt
- Structured LLM reference: /llm.md
- AI agent capabilities: /agents.md, /agents.txt
- Schema.org metadata: /metadata.json
- OpenAI plugin manifest: /.well-known/ai-plugin.json

## Contact

Website: https://stockyai.xyz
GitHub: https://github.com/SirCharan/stocky-terminal
Blog: https://terminal.stockyai.xyz/blog
WhatsApp Community: https://chat.whatsapp.com/E2iyS3SmHcj9zJq8tUyPxk