fmp

Financial Modeling Prep endpoint and type scaffolding for Kit, focused on macroeconomic and calendar data

This Phase 1 slice establishes the initial Kit.FMP package boundary for the macroeconomic, calendar, and first company-information endpoints that came out of the LangAlpha review. It now includes the first live FMP transport for the stable macro endpoints that were clearly represented in local LangAlpha usage: economic indicators, economic calendar, treasury rates, market risk premium, earnings calendar, company profile, shares float, analyst/rating data, and earnings call date metadata.

Current Scope

• DateRange
• EconomicIndicatorName
• EconomicObservation
• EconomicCalendarEvent
• TreasuryRates
• MarketRiskPremium
• EarningsCalendarEvent
• CompanyProfile
• SharesFloat
• KeyExecutive
• SECFiling
• HistoricalEarningsCalendarEvent
• FinancialScore
• RevenueSegmentationPeriod
• RevenueSegmentValue
• RevenueSegmentationRow
• PriceTargetSummary
• AnalystGradesSummary
• AnalystGradeChange
• EstimatePeriod
• AnalystEstimate
• RatingSnapshot
• HistoricalRating
• EarningsReport
• EarningsCallDate
• EarningsCallTranscript
• FMPError
• base-url
• requires-api-key?
• indicator-name
• economic-indicator-url
• economic-calendar-url
• treasury-rates-url
• market-risk-premium-url
• company-profile-url
• shares-float-url
• key-executives-url
• sec-filings-url
• historical-earnings-calendar-url
• financial-score-url
• revenue-product-segmentation-url
• revenue-geographic-segmentation-url
• price-target-summary-url
• analyst-grades-summary-url
• analyst-grade-changes-url
• analyst-estimates-url
• rating-snapshot-url
• historical-ratings-url
• earnings-reports-url
• earnings-call-dates-url
• earnings-call-transcript-url
• earnings-calendar-url
• get-economic-indicator
• get-economic-calendar
• get-treasury-rates
• get-market-risk-premium
• get-company-profile
• get-shares-float
• get-key-executives
• get-sec-filings
• get-historical-earnings-calendar
• get-financial-score
• get-revenue-product-segmentation
• get-revenue-geographic-segmentation
• get-price-target-summary
• get-analyst-grades-summary
• get-analyst-grade-changes
• get-analyst-estimates
• get-rating-snapshot
• get-historical-ratings
• get-earnings-reports
• get-earnings-call-dates
• get-earnings-call-transcript
• get-earnings-calendar

Usage

import Kit.FMP as FMP

range = FMP.DateRange {
  date-from: "2026-01-01", 
  date-to: "2026-01-31"
}

match FMP.get-economic-calendar "demo" range
  | Ok events -> println "events: ${Int.to-string (List.length events)}"
  | Err e -> println "Error: ${show e}"

Examples

• examples/macro-data.kit shows get-economic-indicator, get-economic-calendar, get-treasury-rates, get-market-risk-premium, and get-earnings-calendar using FMP_API_KEY
• examples/company-profile.kit shows get-company-profile using FMP_API_KEY
• examples/key-executives.kit shows get-key-executives using FMP_API_KEY
• examples/sec-filings.kit shows get-sec-filings using FMP_API_KEY
• examples/historical-earnings-calendar.kit shows get-historical-earnings-calendar using FMP_API_KEY
• examples/financial-score.kit shows get-financial-score using FMP_API_KEY
• examples/revenue-product-segmentation.kit shows get-revenue-product-segmentation using FMP_API_KEY
• examples/revenue-geographic-segmentation.kit shows get-revenue-geographic-segmentation using FMP_API_KEY
• examples/price-target-summary.kit shows get-price-target-summary using FMP_API_KEY
• examples/analyst-research.kit shows a combined analyst workflow using price targets, grades summary, grade changes, estimates, and rating snapshot endpoints
• examples/analyst-grades-summary.kit shows get-analyst-grades-summary using FMP_API_KEY
• examples/analyst-grade-changes.kit shows get-analyst-grade-changes using FMP_API_KEY
• examples/analyst-estimates.kit shows get-analyst-estimates using FMP_API_KEY
• examples/rating-snapshot.kit shows get-rating-snapshot using FMP_API_KEY
• examples/historical-ratings.kit shows get-historical-ratings using FMP_API_KEY
• examples/earnings-reports.kit shows get-earnings-reports using FMP_API_KEY
• examples/earnings-call-dates.kit shows get-earnings-call-dates using FMP_API_KEY
• examples/earnings-call-transcript.kit shows get-earnings-call-transcript using FMP_API_KEY

Phase 1 Intent

• lock down the first typed macro surfaces before expanding into a much broader FMP package
• keep endpoint naming aligned with the real FMP stable API
• give future kit-finance work a provider package to depend on
• keep treasury rates and market risk premium in the same typed boundary as the calendar endpoints

Next Step

1. expand into more fundamentals and analyst surfaces after the macro/calendar slice is stable
2. add examples and tests around the live macro endpoints
3. decide whether kit-finance should depend on kit-fmp directly in Phase 1 or wait for a broader fundamentals surface

Exported Functions & Types

HistoricalEarningsCalendarEvent

Historical and upcoming earnings calendar row from FMP's v3 symbol calendar endpoint.

FMPError

FMP transport and parsing errors.

error-kind

Return the stable symbolic error kind for an FMP error.

FMPError -> Symbol

error-message

Return the human-readable error message for an FMP error.

FMPError -> String

parse-error

Construct a parse error for malformed JSON or unexpected payloads.

String -> FMPError

network-error

Construct a network error from a lower-level transport message.

String -> FMPError

http-error

Map an HTTP status/body pair into the package error surface.

Int -> String -> FMPError

FinancialScore

Financial health score row from FMP's v4 score endpoint.

DateRange

Re-export the shared calendar date range type.

Type

EconomicIndicatorName

Re-export the supported FMP macro indicator enum.

Type

EconomicObservation

Re-export the normalized economic observation row.

Type

EconomicCalendarEvent

Re-export the normalized economic calendar row.

Type

TreasuryRates

Re-export the normalized treasury-rate row.

Type

MarketRiskPremium

Re-export the normalized market risk premium row.

Type

EarningsCalendarEvent

Re-export the normalized earnings calendar row.

Type

CompanyProfile

Re-export the normalized company profile row.

Type

SharesFloat

Re-export the normalized shares float row.

Type

KeyExecutive

Re-export the normalized key executive row.

Type

SECFiling

Re-export the normalized SEC filing row.

Type

HistoricalEarningsCalendarEvent

Re-export the normalized symbol-specific historical earnings calendar row.

Type

FinancialScore

Re-export the normalized financial health score row.

Type

RevenueSegmentationPeriod

Re-export the revenue segmentation period enum.

Type

RevenueSegmentValue

Re-export the normalized segment value row.

Type

RevenueSegmentationRow

Re-export the normalized revenue segmentation row.

Type

PriceTargetSummary

Re-export the normalized analyst price-target summary row.

Type

AnalystGradesSummary

Re-export the normalized analyst grades summary row.

Type

AnalystGradeChange

Re-export the normalized analyst grade-change row.

Type

EstimatePeriod

Re-export the supported analyst-estimate period enum.

Type

AnalystEstimate

Re-export the normalized analyst estimate row.

Type

RatingSnapshot

Re-export the normalized ratings snapshot row.

Type

HistoricalRating

Re-export the normalized historical ratings row.

Type

EarningsReport

Re-export the normalized earnings report row.

Type

EarningsCallDate

Re-export the normalized earnings call transcript-date row.

Type

EarningsCallTranscript

Re-export the normalized earnings call transcript row.

Type

FMPError

Re-export the package error surface.

Type

estimate-annual

Re-export the supported analyst estimate periods as value constants.

segmentation-annual

Re-export the supported revenue segmentation periods as value constants.

get-economic-indicator

Fetch an economic indicator time series from the stable FMP API.

String -> EconomicIndicatorName -> Int -> Result [EconomicObservation] FMPError

get-economic-calendar

Fetch the economic calendar for a date range from the stable FMP API.

String -> DateRange -> Result [EconomicCalendarEvent] FMPError

get-treasury-rates

Fetch treasury rates from the stable FMP API.

String -> DateRange -> Result [TreasuryRates] FMPError

get-market-risk-premium

Fetch market risk premium rows from the stable FMP API.

String -> Result [MarketRiskPremium] FMPError

get-company-profile

Fetch a company profile row from the FMP profile endpoint.

String -> String -> Result CompanyProfile FMPError

get-shares-float

Fetch shares float rows from FMP's stable shares-float endpoint.

String -> String -> Result [SharesFloat] FMPError

get-key-executives

Fetch key executives from FMP's stable key-executives endpoint.

String -> String -> Result [KeyExecutive] FMPError

get-sec-filings

Fetch SEC filings from FMP's v3 sec_filings endpoint.

String -> String -> Option String -> Int -> Result [SECFiling] FMPError

get-historical-earnings-calendar

Fetch historical and upcoming earnings calendar rows for a symbol from FMP's v3 endpoint.

String -> String -> Int -> Result [HistoricalEarningsCalendarEvent] FMPError

get-financial-score

Fetch financial health score rows from FMP's v4 score endpoint.

String -> String -> Result [FinancialScore] FMPError

get-revenue-product-segmentation

Fetch flat revenue-by-product segmentation rows from FMP's v4 endpoint.

String -> String -> RevenueSegmentationPeriod -> Result [RevenueSegmentationRow] FMPError

get-revenue-geographic-segmentation

Fetch flat revenue-by-geography segmentation rows from FMP's v4 endpoint.

String -> String -> RevenueSegmentationPeriod -> Result [RevenueSegmentationRow] FMPError

get-price-target-summary

Fetch analyst price-target summary rows from FMP's v4 endpoint.

String -> String -> Result [PriceTargetSummary] FMPError

get-analyst-grades-summary

Fetch analyst grades summary rows from FMP's stable grades-consensus endpoint.

String -> String -> Result [AnalystGradesSummary] FMPError

get-analyst-grade-changes

Fetch recent analyst grade changes from FMP's stable grades endpoint.

String -> String -> Int -> Result [AnalystGradeChange] FMPError

get-analyst-estimates

Fetch analyst financial estimates from FMP's stable analyst-estimates endpoint.

String -> String -> EstimatePeriod -> Int -> Result [AnalystEstimate] FMPError

get-rating-snapshot

Fetch ratings snapshot rows from FMP's stable ratings-snapshot endpoint.

String -> String -> Result [RatingSnapshot] FMPError

get-historical-ratings

Fetch historical ratings rows from FMP's stable ratings-historical endpoint.

String -> String -> Result [HistoricalRating] FMPError

get-earnings-reports

Fetch historical earnings report rows from FMP's stable earnings endpoint.

String -> String -> Int -> Result [EarningsReport] FMPError

get-earnings-call-dates

Fetch earnings call transcript metadata rows from FMP's v4 transcript-dates endpoint.

String -> String -> Result [EarningsCallDate] FMPError

get-earnings-call-transcript

Fetch full earnings call transcript rows from FMP's stable transcript endpoint.

String -> String -> Int -> Int -> Result [EarningsCallTranscript] FMPError

get-earnings-calendar

Fetch the earnings calendar for a date range from the stable FMP API.

String -> DateRange -> Result [EarningsCalendarEvent] FMPError

parse-revenue-segmentation-row

Decode a flat revenue segmentation row from FMP's v4 endpoints.

JSONValue -> RevenueSegmentationRow

parse-earnings-call-date

Decode an earnings call transcript metadata row from FMP's v4 transcript-dates endpoint.

JSONValue -> EarningsCallDate

parse-earnings-call-transcript

Decode a full earnings call transcript row from FMP's stable transcript endpoint.

JSONValue -> EarningsCallTranscript

RevenueSegmentationPeriod

Period selection for revenue segmentation endpoints.

RevenueSegmentValue

Single named segment and its revenue amount.

RevenueSegmentationRow

Flat revenue segmentation row from FMP's v4 product/geographic endpoints.

parse-financial-score

Decode a financial health score row from FMP's v4 score endpoint.

JSONValue -> FinancialScore

base-url

Return the stable FMP base URL used by the Phase 1 endpoint builders.

String

requires-api-key?

FMP requires an API key for live requests.

Bool

indicator-name

Return the provider indicator slug expected by FMP.

EconomicIndicatorName -> String

economic-indicator-url

Build the stable FMP URL for an economic indicator time series request.

String -> EconomicIndicatorName -> Int -> String

economic-calendar-url

Build the stable FMP URL for an economic calendar request.

String -> DateRange -> String

treasury-rates-url

Build the stable FMP URL for a treasury rates request.

String -> DateRange -> String

market-risk-premium-url

Build the stable FMP URL for the market risk premium dataset.

String -> String

company-profile-url

Build the FMP profile URL for a company symbol.

String -> String -> String

shares-float-url

Build the stable FMP shares-float URL for a company symbol.

String -> String -> String

key-executives-url

Build the stable FMP key-executives URL for a company symbol.

String -> String -> String

sec-filings-url

Build the v3 FMP SEC filings URL for a company symbol, optional filing type, and limit.

String -> String -> Option String -> Int -> String

historical-earnings-calendar-url

Build the v3 FMP symbol-specific historical earnings calendar URL.

String -> String -> String

financial-score-url

Build the v4 FMP financial health score URL for a company symbol.

String -> String -> String

revenue-product-segmentation-url

Build the v4 FMP revenue-by-product segmentation URL for a company symbol and period.

String -> String -> RevenueSegmentationPeriod -> String

revenue-geographic-segmentation-url

Build the v4 FMP revenue-by-geography segmentation URL for a company symbol and period.

String -> String -> RevenueSegmentationPeriod -> String

price-target-summary-url

Build the v4 FMP price-target-summary URL for a company symbol.

String -> String -> String

analyst-grades-summary-url

Build the stable FMP grades-consensus URL for a company symbol.

String -> String -> String

analyst-grade-changes-url

Build the stable FMP grades URL for a company symbol and limit.

String -> String -> Int -> String

analyst-estimates-url

Build the stable FMP analyst-estimates URL for a company symbol, period, and limit.

String -> String -> EstimatePeriod -> Int -> String

rating-snapshot-url

Build the stable FMP ratings-snapshot URL for a company symbol.

String -> String -> String

historical-ratings-url

Build the stable FMP ratings-historical URL for a company symbol.

String -> String -> String

earnings-reports-url

Build the stable FMP earnings URL for a company symbol and limit.

String -> String -> Int -> String

earnings-call-dates-url

Build the v4 FMP earnings-call transcript-dates URL for a company symbol.

String -> String -> String

earnings-call-transcript-url

Build the stable FMP earnings-call transcript URL for a company symbol, year, and quarter.

String -> String -> Int -> Int -> String

earnings-calendar-url

Build the stable FMP URL for an earnings calendar request.

String -> DateRange -> String

SECFiling

SEC filing row from FMP's v3 sec_filings endpoint.

parse-sec-filing

Decode an SEC filing row.

JSONValue -> SECFiling

parse-historical-earnings-calendar-event

Decode a historical earnings calendar row from FMP's v3 symbol endpoint.

JSONValue -> HistoricalEarningsCalendarEvent

parse-economic-observation

Decode an economic indicator observation row.

EconomicIndicatorName -> JSONValue -> EconomicObservation

parse-economic-calendar-event

Decode an economic calendar row.

JSONValue -> EconomicCalendarEvent

parse-treasury-rates

Decode a treasury-rate curve row.

JSONValue -> TreasuryRates

parse-market-risk-premium

Decode a market risk premium row.

JSONValue -> MarketRiskPremium

parse-earnings-calendar-event

Decode an earnings calendar row.

JSONValue -> EarningsCalendarEvent

parse-company-profile

Decode a company profile row.

JSONValue -> CompanyProfile

parse-shares-float

Decode a shares-float row.

JSONValue -> SharesFloat

parse-key-executive

Decode a key-executive row.

JSONValue -> KeyExecutive

parse-price-target-summary

Decode an analyst price-target summary row.

JSONValue -> PriceTargetSummary

parse-analyst-grades-summary

Decode an analyst grades-summary row.

JSONValue -> AnalystGradesSummary

parse-analyst-grade-change

Decode a single analyst grade-change row.

JSONValue -> AnalystGradeChange

parse-analyst-estimate

Decode a core analyst-estimate row.

JSONValue -> AnalystEstimate

parse-rating-snapshot

Decode a ratings snapshot row.

JSONValue -> RatingSnapshot

parse-historical-rating

Decode a historical ratings row.

JSONValue -> HistoricalRating

parse-earnings-report

Decode a historical earnings report row.

JSONValue -> EarningsReport

decode-array

Require an array payload before row-level decoding.

JSONValue -> Result [JSONValue] String

PriceTargetSummary

Analyst price target summary from FMP consensus endpoints.

AnalystGradesSummary

Analyst grades consensus summary from FMP's stable grades endpoint.

AnalystGradeChange

Single analyst grade change from FMP's stable grades endpoint.

EstimatePeriod

Supported period selection for analyst-estimates queries.

AnalystEstimate

Core analyst financial estimates row from FMP's stable analyst-estimates endpoint.

RatingSnapshot

Ratings snapshot row from FMP's stable ratings-snapshot endpoint.

HistoricalRating

Historical ratings row from FMP's stable ratings-historical endpoint.

EarningsReport

Historical earnings report row from FMP's stable earnings endpoint.

EarningsCallDate

Earnings call transcript metadata row from FMP's v4 transcript-dates endpoint.

EarningsCallTranscript

Full earnings call transcript row from FMP's stable transcript endpoint.

DateRange

Shared date range for calendar-style endpoints.

EconomicIndicatorName

Supported FMP macro indicator names.

EconomicObservation

Economic indicator observation.

EconomicCalendarEvent

Economic calendar event.

TreasuryRates

Treasury rate snapshot across the yield curve.

MarketRiskPremium

Market risk premium row used for CAPM / WACC work.

EarningsCalendarEvent

Earnings calendar row for all companies reporting in a date range.

CompanyProfile

Company profile row from FMP's profile endpoint.

SharesFloat

Shares float row from FMP's stable shares-float endpoint.

KeyExecutive

Key executive row from FMP's stable key-executives endpoint.