> ## 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.

# Financial Ratios & Health Scores

> Pre-computed financial ratios and quantitative health scoring models for fundamental stock analysis.

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 |

**When to use**

* 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**

```bash theme={null}
# 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**

```bash theme={null}
# 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"
```