Documentation Index
Fetch the complete documentation index at: https://tradewatch.io/docs/llms.txt
Use this file to discover all available pages before exploring further.
Ratios and health scores translate raw financial statement data into normalized metrics that make companies comparable. Ratios answer “how does this company look on a given dimension?”; health scores answer “is this company financially sound?” using established academic and practitioner models.
Endpoints
| Endpoint | Summary | Key use case |
|---|
GET /stocks/{symbol}/ratios | Financial ratios | Valuation, profitability, liquidity, leverage, TTM, DuPont |
GET /stocks/{symbol}/scores | Health scores | Piotroski F-Score, Altman Z-Score, Beneish M-Score |
Financial Ratios
Endpoint: GET /stocks/{symbol}/ratios
Returns pre-computed financial ratios organized into groups. Use the group parameter to fetch one category at a time, or supply name to retrieve a single specific ratio by key (overrides group). Omit both to receive all available ratios.
Ratio groups
| Group | What it covers | Example ratios |
|---|
valuation | How expensive is the stock relative to fundamentals? | P/E, EV/EBITDA, P/B, P/S |
profitability | How efficiently does the company earn returns? | ROE, ROA, net margin, gross margin |
liquidity | Can it meet short-term obligations? | Current ratio, quick ratio, cash ratio |
leverage | How much debt risk does it carry? | Debt/equity, interest coverage, debt/assets |
ttm | Trailing twelve months version of key ratios | Rolling P/E, rolling ROE |
dupont | Decomposition of ROE into its three drivers | Net margin × asset turnover × equity multiplier |
- Screening stocks by valuation (e.g. filtering for P/E below a threshold)
- Comparing profitability metrics between companies in the same sector
- Monitoring leverage trends across quarterly
ttm data
- Understanding why a company’s ROE changed using DuPont decomposition (was it margin expansion, or increased leverage?)
Example
# Get valuation ratios for AAPL
curl "https://api.tradewatch.io/stocks/AAPL/ratios?group=valuation" \
-H "api-key: YOUR_API_KEY"
# Get a single specific ratio
curl "https://api.tradewatch.io/stocks/AAPL/ratios?name=pe_ratio" \
-H "api-key: YOUR_API_KEY"
Health Scores
Endpoint: GET /stocks/{symbol}/scores
Computes one or more quantitative scoring models derived from financial statement data. Use the name parameter to request a specific model. Omit name (or pass all) to receive all three scores in a single response.
Piotroski F-Score
A nine-point scoring system that measures earnings quality and overall financial strength. Each of nine binary criteria contributes 1 point if met. The criteria span three dimensions:
- Profitability: Positive ROA, positive operating cash flow, improving ROA, cash-based earnings exceeding accruals
- Leverage & liquidity: Decreasing long-term debt ratio, improving current ratio, no new share dilution
- Operating efficiency: Improving gross margin, improving asset turnover
Interpretation
| Score | Signal |
|---|
| 8–9 | Strong financial position |
| 5–7 | Average |
| 0–2 | Financially weak |
Altman Z-Score
Predicts the probability of corporate bankruptcy within two years using a weighted combination of five financial ratios. Originally calibrated on public manufacturing companies; results for financial companies, utilities, or firms outside the US may be less reliable.
Interpretation
| Z-Score | Zone |
|---|
| > 2.99 | Safe zone — low bankruptcy risk |
| 1.81 – 2.99 | Grey zone — monitor closely |
| < 1.81 | Distress zone — elevated bankruptcy risk |
Beneish M-Score
Detects the likelihood of earnings manipulation using eight financial statement variables. Developed by Messod Beneish (1999) based on SEC enforcement actions.
Interpretation
| M-Score | Signal |
|---|
| > −2.22 | Possible earnings manipulation |
| ≤ −2.22 | Unlikely manipulator |
Notes on using health scores
- Scores are computed from the most recently available financial statement data. Compare scores across multiple reporting periods to identify trends rather than relying on a single data point.
- These models are screening tools, not definitive judgments. A safe-zone Altman Z-Score does not guarantee financial health; a low Beneish M-Score does not clear a company of manipulation.
- Scores are most meaningful when benchmarked against peers in the same industry and business cycle stage.
Example
# All three scores for TSLA in one call
curl "https://api.tradewatch.io/stocks/TSLA/scores" \
-H "api-key: YOUR_API_KEY"
# Piotroski F-Score only
curl "https://api.tradewatch.io/stocks/TSLA/scores?name=piotroski" \
-H "api-key: YOUR_API_KEY"
# Altman Z-Score
curl "https://api.tradewatch.io/stocks/TSLA/scores?name=altman-z" \
-H "api-key: YOUR_API_KEY"
# Beneish M-Score
curl "https://api.tradewatch.io/stocks/TSLA/scores?name=beneish-m" \
-H "api-key: YOUR_API_KEY"
