# Finterm

Finterm is a financial-data API. Every response is the two-key envelope:
`finterm` (meta header) and `data` (the published result contract), or
`finterm` + `error` on failure.
Authenticate with a bearer token (`finterm auth login`, or FINTERM_API_KEY from the
dashboard). The surface is paid: every authenticated DATA/TOOL call requires Finterm
Pro (3-day free trial, card required). Without Pro the API returns 402
`SUBSCRIPTION_REQUIRED` with `error.upgrade_url`; upgrade at https://app.finterm.ai/pricing,
then retry, and access activates automatically after checkout. Two account-level
endpoints work with any authenticated key, Pro or not: GET /api/v1/account (plan
state) and POST /api/v1/feedback (bugs, questions, feature requests).

- OpenAPI: https://api.finterm.ai/api/v1/openapi.json
- Catalog: https://api.finterm.ai/api/v1/catalog
- Docs: https://docs.finterm.ai
- Setup guide and examples: https://finterm.ai/llms.txt

## Tools

- `stock_prices_current`: Latest available price for one or more stock symbols, delayed by up to 15 minutes. (POST /api/v1/prices/current)
  - example: `finterm tool stock_prices_current NVDA AAPL`
- `technical_indicators`: Standard momentum and trend indicators (RSI, MACD, SMA) for a symbol. (POST /api/v1/technical-indicators)
  - example: `finterm tool technical_indicators AAPL --as-of-date 2024-01-16`
- `sec_filings_search`: Search SEC EDGAR filings for a company by ticker and form type. (POST /api/v1/sec/search)
  - example: `finterm tool sec_filings_search AAPL --form-type 10-K --as-of-date 2024-12-31`
- `sec_filing_fetch`: Fetch narrative sections from a company’s SEC filing by fiscal year and period. (POST /api/v1/sec/fetch)
  - example: `finterm tool sec_filing_fetch AAPL --year 2024 --period FY --sections risk_factors,mda`
- `sec_filing_diff`: Compare two of a company’s SEC filings and report section-level changes. (POST /api/v1/sec/diff)
  - example: `finterm tool sec_filing_diff AAPL --base 2023:FY --compare 2024:FY --sections risk_factors --mode summary`
- `options_sentiment`: Put/call options sentiment for a symbol on a specific date, with a sample-quality verdict. (POST /api/v1/options/sentiment)
  - example: `finterm tool options_sentiment AAPL --as-of-date 2024-01-15`
- `options_overview`: A live one-call options overview: implied vs realized volatility with rank, today's flow, the positioning book, expected moves, and probability bands. (POST /api/v1/options/overview)
  - example: `finterm tool options_overview TSLA`
- `financial_statements`: Reported balance sheet, income statement, or cash flow for a company. (POST /api/v1/fundamentals/financials)
  - example: `finterm tool financial_statements AAPL --statement-type income_statement --as-of-date 2024-12-01 --timeframe quarterly`
- `insider_trades`: SEC Form 4 insider transactions with a trailing 90-day open-market summary. (POST /api/v1/ownership/insider-trades)
  - example: `finterm tool insider_trades AAPL --as-of-date 2024-03-15`
- `institutional_holdings`: SEC Form 13F institutional holders for a stock or the portfolio of one manager. (POST /api/v1/ownership/institutional-holdings)
  - example: `finterm tool institutional_holdings AAPL --as-of-date 2024-03-15`
- `ticker_sentiment`: A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker's own year, grouped trend / flow / positioning. (POST /api/v1/ticker-sentiment)
  - example: `finterm tool ticker_sentiment AAPL`
- `ticker_data`: The full ticker snapshot: earnings, guidance, the price reaction window, ratios, options sentiment, short pressure, technicals, financial statements, and pre-earnings market context, in one call. (POST /api/v1/bundles/ticker_data/runs)
  - example: `finterm bundle run ticker_data AAPL`

## Account and Feedback

- `account`: the authenticated whoami/plan-state read; works without Pro (GET /api/v1/account)
- `feedback`: submit a bug, question, or feature request; works without Pro (POST /api/v1/feedback)
  - example: `finterm feedback bug "One-line summary" --body "Expected vs. actual"`