finnhub-skill

# Finnhub Skill Use Finnhub as a **read-only market data source**. ## Core Rules 1. Treat this skill as **data retrieval only**. 2. Never place trades or modify accounts through this skill. 3. Require a valid `FINNHUB_API_KEY` before making live requests. 4. If the API key is missing, explain how to configure it instead of guessing. 5. Prefer concise outputs: summary first, raw fields second. ## Supported Use Cases - Real-time quote lookup - K-line / candle retrieval - Company profile lookup - Symbol/company news lookup - Earnings calendar / earnings history lookup - Economic calendar lookup - Crypto and forex reference data (if supported by the user plan) - Structured daily stock news report (price + news + trader-style interpretation) ## Configuration Expect the user to provide: ```bash export FINNHUB_API_KEY=your_api_key ``` Optional base URL override is supported only for the official Finnhub domain: ```bash export FINNHUB_BASE_URL=https://finnhub.io/api/v1 ``` Default base URL: ```text https://finnhub.io/api/v1 ``` Security rule: - Only allow `https://finnhub.io/...` - Do not point this skill to arbitrary hosts or proxies that could capture the API key ## Execution Layer Use the bundled script: ```bash python3 scripts/finnhub.py <command> [flags] ``` Supported commands: - `quote --symbol AAPL [--raw]` - `candles --symbol AAPL --resolution D --from-ts 1711584000 --to-ts 1712188800 [--raw]` - `profile --symbol AAPL [--raw]` - `company-news --symbol AAPL --date-from 2026-03-01 --date-to 2026-03-30 [--raw]` - `market-news --category general [--raw]` - `earnings --date-from 2026-03-30 --date-to 2026-04-06 [--symbol AAPL] [--raw]` - `economic --date-from 2026-03-30 --date-to 2026-04-06 [--raw]` Default output is human-readable. Use `--raw` when the user explicitly wants JSON. ## Recommended Request Pattern Use the bundled Python script for live calls instead of rebuilding requests from scratch. When constructing requests: - URL-encode symbol and other parameters - Validate time range inputs before sending - Keep requests read-only - If the user asks for a very broad request, narrow the scope first ## Output Style ### Quote Return: - symbol - current price - absolute change - percent change - high / low / open / previous close - timestamp if available ### Candles Summarize: - symbol - resolution - start/end window - number of candles returned - latest OHLCV row Only dump the full array when the user explicitly asks. ### Company Profile Return: - company name - ticker - exchange - currency - country - market cap - industry / IPO date if available - website ### News Return: - headline - source - published time - URL - short summary if available Prefer 3-5 most relevant items unless the user asks for more. ## Common Tasks ### 1. Real-time quote Use Finnhub quote endpoint for stocks or supported symbols. If the user gives a bare ticker like `AAPL`, use it directly. If the user gives crypto/forex, confirm Finnhub symbol format if needed. ### 2. Candles / K-lines Ask for or infer: - symbol - resolution (`1`, `5`, `15`, `30`, `60`, `D`, `W`, `M`) - from timestamp - to timestamp If the user asks loosely (e.g. “last week”), convert it into a concrete range. ### 3. Company profile Use the company profile endpoint when the user asks “what is this company”, “profile”, “market cap”, “which exchange”, etc. ### 4. News Use company or market news endpoints depending on the request: - company-specific → company news - broad market / macro → market news ### 5. Earnings / calendar Use earnings calendar for upcoming results and earnings history if the user asks what already happened. ### 6. Daily stock report When the user asks for a daily report like: - “发我 TSLA 昨天的新闻总结” - “做一个 NVDA 昨日新闻日报” - “给我 AAPL 的价格+新闻日报” Build the report in this order: 1. quote / price summary first 2. most important 3-5 news items 3. market narrative and trader interpretation 4. final rating For the report format, read: - `references/daily-report-template.md` If candle/volume endpoints are unavailable due to Finnhub plan limits: - still produce the report - explicitly say that detailed candles/volume are unavailable under current access - avoid inventing volume comparison or trend detail ## Error Handling If Finnhub returns auth or quota errors: - State the likely cause clearly - Do not fabricate fallback data - Suggest checking API key, plan limits, or symbol format If symbol format is ambiguous: - Ask one clarifying question - Do not assume unsupported exchange suffixes ## Reference File For endpoint patterns and parameter hints, read: - `references/api.md`