# finance-query
Generated TypeScript client for **Finance Query v2** (3.0.0), bundling the server it talks to — there is nothing to deploy and no endpoint to configure.
```bash
npm install finance-query
```
```ts
import { Client } from "finance-query";
const client = new Client();
const result = await client.getAnalysis(...);
```
Errors throw subclasses of `ApiError`; rate limits retry automatically, honoring `Retry-After`. Model properties use the wire names the API sends, so a decoded response needs no translation step.
## Embedded server
The first request starts the bundled `finance-query-server` on a port it picks itself, and the process is reaped when yours exits. Two environment variables change that:
- `FINANCE_QUERY_BASE_URL` — talk to an already-running instance and spawn nothing.
- `FINANCE_QUERY_SERVER_BIN` — use a different server binary.
`stopEmbeddedServers()` shuts it down early; `EmbeddedServer.start()` manages one by hand.
Pass `DEFAULT_BASE_URL` (`https://finance-query.com`) to use the hosted deployment instead.
### Configuring it
The server reads the same environment a deployment sets it with. `serverEnv` supplies that per client:
```ts
const client = new Client(undefined, {
serverEnv: { REDIS_URL: "...", EDGAR_EMAIL: "..." },
});
```
Those values win over the ambient environment; anything left out falls back to what this process — or a `.env` file the server itself reads — already provides. Clients asking for different `serverEnv` get their own server process. The `ServerEnv` interface spells every knob:
| `PORT` | `8000` | Server Configuration |
| `HOST` | `0.0.0.0` | Bind address. 0.0.0.0 serves every interface; an SDK-spawned server sets 127.0.0.1 so nothing off the machine can reach it |
| `LOG_LEVEL` | `INFO` | Logging Options: DEBUG, INFO, WARNING, ERROR |
| `LOG_FORMAT` | `json` | Options: json, text |
| `REDIS_URL` | _unset_ | Redis Cache (optional) |
| `RATE_LIMIT_PER_MINUTE` | `600` | Rate Limiting Requests per minute, applied independently per client IP (default: 600 = 10 req/sec) |
| `DEFAULT_INTERVAL` | `1d` | API Defaults Options: 1m, 5m, 15m, 30m, 1h, 1d, 1wk, 1mo, 3mo |
| `DEFAULT_RANGE` | `1mo` | Options: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max |
| `RECOMMENDATIONS_LIMIT` | `5` | Default Query Limits |
| `SEARCH_HITS` | `10` | |
| `SCREENERS_COUNT` | `25` | |
| `EDGAR_EMAIL` | _unset_ | SEC EDGAR Integration (optional) Contact email required by SEC - included in User-Agent header Leave commented out to disable EDGAR endpoints |
| `FRED_API_KEY` | _unset_ | FRED API Integration (optional) Free API key from https://fred.stlouisfed.org/docs/api/api_key.html Leave commented out to disable /v2/fred/* endpoints Note: If running a public server, your terms of use must state that users are bound by the FRED API Terms of Use: https://fred.stlouisfed.org/docs/api/terms_of_use.html |
| `POLYGON_API_KEY` | _unset_ | Polygon.io - https://polygon.io/dashboard/api-keys |
| `FMP_API_KEY` | _unset_ | Financial Modeling Prep - https://site.financialmodelingprep.com/developer/docs |
| `ALPHAVANTAGE_API_KEY` | _unset_ | Alpha Vantage - https://www.alphavantage.co/support/#api-key |
| `BLS_API_KEY` | _unset_ | US Bureau of Labor Statistics - https://data.bls.gov/registrationEngine/ Raises the request quota; the BLS API also works unregistered |
| `OPENFIGI_API_KEY` | _unset_ | OpenFIGI - https://www.openfigi.com/api Raises the rate limit on symbol lookups; works unregistered |
Requires Node 18+.
## Methods
- `getAnalysis` — `GET /v2/analysis/{symbol}/{type}`: Get analysis data
- `getBatchCapitalGains` — `GET /v2/capital-gains`: Get batch capital gains history
- `getBatchCharts` — `GET /v2/charts`: Get batch historical chart data
- `getBatchDividends` — `GET /v2/dividends`: Get batch dividend history
- `getBatchFinancials` — `GET /v2/financials`: Get batch financial statements
- `getBatchIndicators` — `GET /v2/indicators`: Get batch technical indicators
- `getBatchOptions` — `GET /v2/options`: Get batch options chains
- `getBatchRecommendations` — `GET /v2/recommendations`: Get batch stock recommendations
- `getBatchSplits` — `GET /v2/splits`: Get batch stock split history
- `getCalendar` — `GET /v2/calendar`: Get upcoming financial event calendar
- `getCapitalGains` — `GET /v2/capital-gains/{symbol}`: Get capital gains distribution history
- `getChart` — `GET /v2/chart/{symbol}`: Get historical chart data
- `getCommitmentsOfTraders` — `GET /v2/cftc/cot/{symbol}`: Weekly CFTC Commitments of Traders positioning (keyless)
- `getCommodity` — `GET /v2/commodities/{symbol}`: Get a commodity's current quote
- `getCompanyProfile` — `GET /v2/company-profile/{symbol}`: Get company profile
- `getCongressionalTrades` — `GET /v2/filings/{symbol}/congressional-trades`: Congressional trading disclosures for a symbol
- `getCryptoCoin` — `GET /v2/crypto/coins/{id}`: Single coin by CoinGecko ID
- `getCryptoCoins` — `GET /v2/crypto/coins`: Top coins by market cap
- `getCryptoGlobal` — `GET /v2/crypto/global`: Aggregate global cryptocurrency market statistics
- `getCryptoNews` — `GET /v2/crypto/news`: Market-wide crypto news
- `getCryptoSearch` — `GET /v2/crypto/search`: Search CoinGecko's coin universe by free-text query
- `getCryptoTrending` — `GET /v2/crypto/trending`: Coins trending on CoinGecko over the last 24h
- `getCurrencies` — `GET /v2/currencies`: Get available currencies
- `getDividends` — `GET /v2/dividends/{symbol}`: Get dividend history and analytics
- `getEarningsSurprises` — `GET /v2/earnings-surprises/{symbol}`: Get earnings-surprise history
- `getEarningsTranscript` — `GET /v2/earnings-transcript/{symbol}`: Get earnings call transcript
- `getEdgarCik` — `GET /v2/edgar/cik/{symbol}`: Resolve ticker to CIK
- `getEdgarFacts` — `GET /v2/edgar/facts/{symbol}`: Get XBRL financial data
- `getEdgarSearch` — `GET /v2/edgar/search`: Search SEC filings
- `getEdgarSubmissions` — `GET /v2/edgar/submissions/{symbol}`: Get SEC filing history
- `getEtfProfile` — `GET /v2/etf-profile/{symbol}`: Get ETF profile and holdings
- `getExchanges` — `GET /v2/exchanges`: Get supported exchanges
- `getExecutiveCompensation` — `GET /v2/executive-compensation/{symbol}`: Disclosed executive compensation by year.
- `getFailsToDeliver` — `GET /v2/filings/{symbol}/fails-to-deliver`: Fails-to-deliver records for a symbol
- `getFearAndGreed` — `GET /v2/fear-and-greed`: Fear & Greed Index
- `getFeeds` — `GET /v2/feeds`: RSS/Atom news feeds
- `getFilingSections` — `GET /v2/filings/{symbol}/sections`: Get sectioned text of one SEC filing
- `getFinancials` — `GET /v2/financials/{symbol}/{statement}`: Get financial statements
- `getForex` — `GET /v2/forex/{from}/{to}`: Get a currency pair's current exchange rate
- `getForexNews` — `GET /v2/forex/news`: Market-wide forex news
- `getFredSeries` — `GET /v2/fred/series/{id}`: FRED time series
- `getFredTreasuryYields` — `GET /v2/fred/treasury-yields`: US Treasury yield curve
- `getFutures` — `GET /v2/futures/{symbol}`: Get a futures contract's current quote
- `getGdeltNews` — `GET /v2/gdelt/news/{symbol}`: Worldwide news mentioning a symbol (GDELT, keyless)
- `getGeneralNews` — `GET /v2/news`: Get general market news
- `getGradingActions` — `GET /v2/grading-actions/{symbol}`: Provider-routed analyst upgrades and downgrades.
- `getHolders` — `GET /v2/holders/{symbol}/{type}`: Get holder data
- `getHours` — `GET /v2/hours`: Get market hours
- `getIndexConstituentChanges` — `GET /v2/indices/{symbol}/constituent-changes`: Additions and removals from an index's constituent list.
- `getIndexConstituents` — `GET /v2/index-constituents/{symbol}`: Get an index's current constituent list
- `getIndicators` — `GET /v2/indicators/{symbol}`: Get technical indicators
- `getIndices` — `GET /v2/indices`: Get world market indices
- `getIndustry` — `GET /v2/industries/{industry}`: Get industry data
- `getKeyMetricsTtm` — `GET /v2/key-metrics-ttm/{symbol}`: Trailing-twelve-month key metrics.
- `getMarketCalendar` — `GET /v2/market-calendar`: Get a market-wide event calendar
- `getMarketSummary` — `GET /v2/market-summary`: Get market summary
- `getMetrics` — `GET /v2/metrics`: Prometheus metrics
- `getNews` — `GET /v2/news/{symbol}`: Get news for a symbol
- `getOptions` — `GET /v2/options/{symbol}`: Get options chain
- `getPressReleases` — `GET /v2/press-releases/{symbol}`: Get a company's own press releases
- `getPriceTargetConsensus` — `GET /v2/price-target-consensus/{symbol}`: Get consensus analyst price target
- `getPriceTargetSummary` — `GET /v2/price-target-summary/{symbol}`: Analyst price-target counts and averages per window.
- `getProtocolTvl` — `GET /v2/crypto/coins/{id}/tvl`: A DeFi protocol's total value locked (DefiLlama, keyless).
- `getProtocolTvlHistory` — `GET /v2/crypto/coins/{id}/tvl-history`: A protocol's TVL history, oldest first.
- `getQuote` — `GET /v2/quote/{symbol}`: Get quote for a symbol
- `getQuoteType` — `GET /v2/quote-type/{symbol}`: Get quote type
- `getQuotes` — `GET /v2/quotes`: Get quotes for multiple symbols
- `getRatingConsensus` — `GET /v2/rating-consensus/{symbol}`: Get consensus rating rollup
- `getRatiosTtm` — `GET /v2/ratios-ttm/{symbol}`: Trailing-twelve-month financial ratios.
- `getRecommendations` — `GET /v2/recommendations/{symbol}`: Get similar stock recommendations
- `getRisk` — `GET /v2/risk/{symbol}`: Risk analytics
- `getRiskFactors` — `GET /v2/filings/{symbol}/risk-factors`: Get risk factors extracted from SEC filings
- `getScreeners` — `GET /v2/screeners/{screener}`: Get screener results
- `getSector` — `GET /v2/sectors/{sector}`: Get sector data
- `getSectorPe` — `GET /v2/sector-pe`: Get price/earnings ratios by sector
- `getSectorPerformance` — `GET /v2/sector-performance`: Get aggregate performance for every sector
- `getSectorPerformanceHistory` — `GET /v2/sector-performance/history`: Sector performance per session.
- `getShortVolume` — `GET /v2/short-volume/{symbol}`: Daily FINRA short-sale volume for a symbol (keyless).
- `getSpark` — `GET /v2/spark`: Get batch sparkline data
- `getSplits` — `GET /v2/splits/{symbol}`: Get stock split history
- `getSymbolDetails` — `GET /v2/symbol-details/{symbol}`: Reference detail for one symbol.
- `getTranscript` — `GET /v2/transcripts/{symbol}`: Get earnings transcript
- `getTranscripts` — `GET /v2/transcripts/{symbol}/all`: Get all earnings transcripts
- `getTrending` — `GET /v2/trending`: Get trending tickers
- `healthCheck` — `GET /v2/health`: Health check
- `lookup` — `GET /v2/lookup`: Look up symbols by type
- `ping` — `GET /v2/ping`: Ping endpoint
- `postBacktest` — `POST /v2/backtest/{symbol}`: Run a strategy backtest
- `postCustomScreener` — `POST /v2/screeners/custom`: Custom screener query
- `search` — `GET /v2/search`: Search symbols and companies