Finnhub Skill

Read-only market data skill for Finnhub. Use when the user wants stock, forex, crypto, company profile, candles/K-lines, news, earnings, or economic calendar...

Security Scan

The skill appears to be a straightforward read-only Finnhub client, but the registry metadata omits the required FINNHUB_API_KEY and primary credential info — an incoherence that you should resolve before trusting it.

Purpose & Capability

The skill's name/description claim read-only Finnhub access which matches the code and SKILL.md. However, the registry metadata declares no required environment variables or primary credential while SKILL.md and scripts clearly require FINNHUB_API_KEY (and optionally FINNHUB_BASE_URL). The missing declared credential is an inconsistency.

Instruction Scope

SKILL.md instructs the agent to use the bundled Python script for read-only queries, to require FINNHUB_API_KEY, and to restrict the base URL to the official Finnhub domain. The instructions do not ask for unrelated files, secrets, or external endpoints and explicitly forbid non-Finnhub hosts.

Install Mechanism

There is no install spec (instruction-only behavior) and the included Python script is bundled in the repo. No external downloads or package installs are required, which keeps install risk low.

Credentials

The code and SKILL.md require FINNHUB_API_KEY (and optionally FINNHUB_BASE_URL) but the skill metadata lists no required env vars or primary credential — this mismatch is suspicious because it hides that a secret is required. The script sends the API key as a query parameter (standard for this API) and attempts to redact query tokens from error text, but the redact implementation only looks for 'token=...' patterns and might not catch other exposures (e.g., token in JSON or nonstandard error formats).

Persistence & Privilege

always is false and the skill does not request persistent system privileges or modify other skills. It can be invoked autonomously (default platform behavior), which is normal but worth noting since it will be able to make live Finnhub requests when given an API key.

What to consider before installing

This skill's behavior (read-only Finnhub access) and included Python client are consistent, but the registry metadata failing to declare FINNHUB_API_KEY and a primary credential is a red flag. Before installing: 1) confirm you are comfortable supplying your Finnhub API key to this skill and that the key has only the necessary permissions; 2) ask the publisher or update the metadata so FINNHUB_API_KEY is listed as the primary credential; 3) review the bundled scripts yourself (they are small) to ensure no hidden endpoints; 4) do not set FINNHUB_BASE_URL to an arbitrary host — only use the official Finnhub domain; 5) be aware the skill can be invoked autonomously by agents (default) — if you do not want that, disable autonomous invocation. These steps will reduce the risk of accidental credential exposure or unexpected network calls.

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:

export FINNHUB_API_KEY=your_api_key

Optional base URL override is supported only for the official Finnhub domain:

export FINNHUB_BASE_URL=https://finnhub.io/api/v1

Default base URL:

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:

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