finnhub

Kind	kit
Capabilities	net
Categories	finance web data
Keywords	finance stocks finnhub market-data

Finnhub Stock API client for Kit — real-time quotes, historical candles, company profiles, earnings, dividends, splits, recommendations, and basic financials

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic-quote.kit`	Example: fetch a real-time stock quote
`examples/company-profile.kit`	Example: get company profile information
`examples/dataframe-integration.kit`	Example: Finnhub data with kit-dataframe
`examples/fundamentals.kit`	Example: earnings, dividends, splits, and financials
`examples/historical-candles.kit`	Example: fetch historical OHLCV candle data
`examples/plot-integration.kit`	Example: Finnhub data with kit-plot
`examples/search-symbols.kit`	Example: search for stock symbols
`examples/ta-lib-integration.kit`	Example: Finnhub data with kit-ta-lib
`kit.toml`	Package manifest with metadata and dependencies
`src/errors.kit`	Error types for Finnhub API operations
`src/finnhub.kit`	kit-finnhub: Finnhub Stock API client
`src/types.kit`	Type definitions for Finnhub API responses
`tests/errors.test.kit`	Tests for error types
`tests/types.test.kit`	Tests for response types

Dependencies

kit-curl - HTTP client via libcurl

Capabilities

This package requires the net capability for making HTTP requests to the Finnhub API.

kit run --allow=net examples/basic-quote.kit
kit build --allow=net examples/basic-quote.kit -o basic-quote

Installation

kit add gitlab.com/kit-lang/packages/kit-finnhub.git

Usage

import Kit.Finnhub as Finnhub

main =
  api-key = Env.get "FINNHUB_API_KEY" ?? ""

  # Real-time stock quote
  match Finnhub.get-quote api-key "AAPL"
    | Ok quote -> println "AAPL: $${Float.to-string quote.current} (${Float.to-string quote.change-percent}%)"
    | Err e -> println "Error: ${show e}"

  # Company profile
  match Finnhub.get-profile api-key "AAPL"
    | Ok profile -> println "Company: ${profile.name}, Industry: ${profile.finnhub-industry}"
    | Err e -> println "Error: ${show e}"

  # Symbol search
  match Finnhub.search api-key "apple"
    | Ok results -> println "Found ${Int.to-string (List.length results)} results"
    | Err e -> println "Error: ${show e}"

  # Historical candles (daily, one year)
  match Finnhub.get-candles api-key "AAPL" "D" 1672531200 1704067200
    | Ok candles -> println "Got ${Int.to-string (List.length candles)} daily candles"
    | Err e -> println "Error: ${show e}"

main

API Reference

Quotes

Function	Signature	Description
`get-quote`	`String -> String -> Result Quote FinnhubError`	Get a real-time stock quote
`get-market-status`	`String -> String -> Result {exchange: String, is-open: Bool} FinnhubError`	Get market status for an exchange

Historical Data

Function	Signature	Description
`get-candles`	`String -> String -> String -> Int -> Int -> Result (List Candle) FinnhubError`	Get historical OHLCV candle data

Search & Profile

Function	Signature	Description
`search`	`String -> String -> Result (List SearchResult) FinnhubError`	Search for stock symbols
`get-profile`	`String -> String -> Result CompanyProfile FinnhubError`	Get a company profile

Fundamentals

Function	Signature	Description
`get-earnings`	`String -> String -> Result (List EarningsItem) FinnhubError`	Get earnings data for a stock
`get-dividends`	`String -> String -> String -> String -> Result (List Dividend) FinnhubError`	Get dividend history
`get-splits`	`String -> String -> String -> String -> Result (List Split) FinnhubError`	Get stock split history
`get-recommendations`	`String -> String -> Result (List Recommendation) FinnhubError`	Get analyst recommendation trends
`get-basic-financials`	`String -> String -> Result BasicFinancials FinnhubError`	Get basic financial metrics

Types

Type	Description
`Quote`	Real-time quote with current, high, low, open, previous-close, change, change-percent
`Candle`	OHLCV candle bar with timestamp, open, high, low, close, volume
`SearchResult`	Symbol search result with description, display-symbol, symbol, result-type
`CompanyProfile`	Company profile with name, ticker, exchange, market-cap, industry
`EarningsItem`	Earnings data with actual, estimate, surprise, period, quarter, year
`Dividend`	Dividend event with date, amount, adjusted-amount, pay-date, currency
`Split`	Stock split event with date, from-factor, to-factor
`Recommendation`	Analyst recommendations with buy, hold, sell, strong-buy, strong-sell counts
`BasicFinancials`	Key financial metrics: P/E, P/B, EPS, beta, margins, ratios
`FinnhubError`	Error ADT: InvalidAPIKey, RateLimitExceeded, SymbolNotFound, NetworkError, ParseError, APIError

Development

Running Examples

Run examples with the interpreter:

kit run --allow=net examples/basic-quote.kit

Compile examples to a native binary:

kit build --allow=net examples/basic-quote.kit -o basic-quote && ./basic-quote

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/finnhub/, making it available for import as Kit.Finnhub in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`FinnhubError`

Finnhub API error types.

Variants: - InvalidAPIKey: API key is missing or invalid (HTTP 401/403) - RateLimitExceeded: Too many requests (HTTP 429) - SymbolNotFound: No data returned for the requested symbol - NetworkError: HTTP request failed - ParseError: JSON parsing or field extraction failed - APIError: Non-success HTTP status code

Variants

InvalidAPIKey {message}

RateLimitExceeded {message}

SymbolNotFound {symbol}

NetworkError {message}

ParseError {message}

APIError {status, message}

`get-quote`

Get a real-time stock quote.

String -> String -> Result Quote FinnhubError

match Finnhub.get-quote api-key "AAPL"
  | Ok quote -> println "Price: $${Float.to-string quote.current}"
  | Err e -> println "Error: ${show e}"

`get-candles`

Get historical OHLCV candle data.

Parameters:

String -> String -> String -> Int -> Int -> Result (List Candle) FinnhubError

match Finnhub.get-candles api-key "AAPL" "D" 1672531200 1704067200
  | Ok candles -> println "Got ${Int.to-string (List.length candles)} candles"
  | Err e -> println "Error: ${show e}"

`search`

Search for stock symbols.

String -> String -> Result (List SearchResult) FinnhubError

match Finnhub.search api-key "apple"
  | Ok results -> println "Found ${Int.to-string (List.length results)} results"
  | Err e -> println "Error: ${show e}"

`get-profile`

Get a company profile.

String -> String -> Result CompanyProfile FinnhubError

match Finnhub.get-profile api-key "AAPL"
  | Ok profile -> println "Company: ${profile.name}"
  | Err e -> println "Error: ${show e}"

`get-earnings`

Get earnings data for a stock.

String -> String -> Result (List EarningsItem) FinnhubError

match Finnhub.get-earnings api-key "AAPL"
  | Ok items -> println "Got ${Int.to-string (List.length items)} earnings records"
  | Err e -> println "Error: ${show e}"

`get-dividends`

Get dividend history for a stock.

Parameters:

String -> String -> String -> String -> Result (List Dividend) FinnhubError

match Finnhub.get-dividends api-key "AAPL" "2023-01-01" "2024-01-01"
  | Ok divs -> println "Got ${Int.to-string (List.length divs)} dividends"
  | Err e -> println "Error: ${show e}"

`get-splits`

Get stock split history.

Parameters:

String -> String -> String -> String -> Result (List Split) FinnhubError

match Finnhub.get-splits api-key "AAPL" "2019-01-01" "2024-01-01"
  | Ok splits -> println "Got ${Int.to-string (List.length splits)} splits"
  | Err e -> println "Error: ${show e}"

`get-recommendations`

Get analyst recommendation trends.

String -> String -> Result (List Recommendation) FinnhubError

match Finnhub.get-recommendations api-key "AAPL"
  | Ok recs -> println "Got ${Int.to-string (List.length recs)} recommendation periods"
  | Err e -> println "Error: ${show e}"

`get-basic-financials`

Get basic financial metrics for a stock.

String -> String -> Result BasicFinancials FinnhubError

match Finnhub.get-basic-financials api-key "AAPL"
  | Ok fin -> println "P/E: ${show fin.pe}"
  | Err e -> println "Error: ${show e}"

`get-market-status`

Get market status for an exchange.

String -> String -> Result {exchange: String, is-open: Bool} FinnhubError

match Finnhub.get-market-status api-key "US"
  | Ok status -> println "Exchange: ${status.exchange}, Open: ${show status.is-open}"
  | Err e -> println "Error: ${show e}"

`Quote`

Quote type

Variants

Quote

`Candle`

Candle type

Variants

Candle

`SearchResult`

SearchResult type

Variants

SearchResult

`CompanyProfile`

CompanyProfile type

Variants

CompanyProfile

`EarningsItem`

EarningsItem type

Variants

EarningsItem

`Dividend`

Dividend type

Variants

Dividend

`Split`

Split type

Variants

Split

`Recommendation`

Recommendation type

Variants

Recommendation

`BasicFinancials`

BasicFinancials type

Variants

BasicFinancials

`FinnhubError`

FinnhubError type

Variants

FinnhubError

`Quote`

Real-time stock quote from the /quote endpoint.

Fields: - current: Current price - high: High price of the day - low: Low price of the day - open: Open price of the day - previous-close: Previous closing price - timestamp: Unix timestamp - change: Price change - change-percent: Percentage change

Variants

Quote {current, high, low, open, previous-close, timestamp, change, change-percent}

`Candle`

OHLCV candle bar from the /stock/candle endpoint.

Fields: - timestamp: Unix timestamp in seconds - open, high, low, close: Price data - volume: Trading volume

Variants

Candle {timestamp, open, high, low, close, volume}

`SearchResult`

Symbol search result from the /search endpoint.

Variants

SearchResult {description, display-symbol, symbol, result-type}

`CompanyProfile`

Company profile from the /stock/profile2 endpoint.

Variants

CompanyProfile {name, ticker, exchange, ipo, market-cap, share-outstanding, logo, phone, weburl, finnhub-industry, country, currency}

`EarningsItem`

Earnings data from the /stock/earnings endpoint.

Variants

EarningsItem {actual, estimate, period, quarter, surprise, surprise-percent, symbol, year}

`Dividend`

Dividend event from the /stock/dividend endpoint.

Variants

Dividend {symbol, date, amount, adjusted-amount, pay-date, record-date, declaration-date, currency}

`Split`

Stock split event from the /stock/split endpoint.

Variants

Split {symbol, date, from-factor, to-factor}

`Recommendation`

Analyst recommendation summary from the /stock/recommendation endpoint.

Variants

Recommendation {buy, hold, sell, strong-buy, strong-sell, period, symbol}

`BasicFinancials`

Basic financial metrics from the /stock/metric endpoint.

Fields include key valuation, profitability, and trading metrics.

Variants

BasicFinancials {symbol, pe, pb, ps, eps, dividend-yield, beta, week-52-high, week-52-low, market-cap, avg-volume-10d, avg-volume-3m, revenue-per-share, net-profit-margin, operating-margin, roe, roi, current-ratio, debt-equity, free-cash-flow-per-share}