# Dividend & Valuation API
> Stock dividend and valuation fundamentals as an API, computed locally and deterministically — the per-share ratios value and income investors screen on. The dividend endpoint takes a share price and an annual dividend (per share, or total dividends ÷ shares) and returns the dividend yield, and with earnings per share the payout ratio (dividend ÷ EPS), the dividend coverage (EPS ÷ dividend) and the retention ratio — a $2 dividend on a $50 share yields 4 %, and on $4 EPS is a 50 % payout covered twice. The valuation endpoint computes the price-to-earnings ratio, earnings yield, the PEG ratio against a growth rate, the price-to-book ratio and the Graham number √(22.5 · EPS · book value) — Benjamin Graham's rough fair-value ceiling. The ddm endpoint runs the Gordon Growth dividend discount model, fair value = D1 ÷ (r − g) from next year's dividend, the required return and the perpetual growth rate, and against a market price flags whether the share looks under- or over-valued and the implied cost of equity. Everything is computed locally and deterministically, so it is instant and private. Ideal for investing, brokerage, robo-advisor, dividend-screener and fintech app developers, stock-valuation and income-portfolio tools, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. These are valuation ratios from your inputs; for live quotes use a market-data API and for project DCF/NPV an investment-appraisal API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/dividend-api/..."
```

## Pricing
- **Free** (Free) — 3,850 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 40,000 calls/Mo, 6 req/s
- **Pro** ($19/Mo) — 191,000 calls/Mo, 15 req/s
- **Mega** ($56/Mo) — 1,090,000 calls/Mo, 40 req/s

## Endpoints

### Dividend

#### `GET /v1/ddm` — Gordon Growth model

**Parameters:**
- `current_dividend` (query, optional, string) — Current dividend D0 (or next_dividend) Example: `2`
- `next_dividend` (query, optional, string) — Next dividend D1
- `growth_rate` (query, optional, string) — Perpetual growth % Example: `5`
- `required_return` (query, required, string) — Required return % Example: `10`
- `price` (query, optional, string) — Market price (for under/over)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dividend-api/v1/ddm?current_dividend=2&growth_rate=5&required_return=10"
```

**Response:**
```json
{
    "data": {
        "note": "Gordon Growth model: fair value = D1 / (r − g), where D1 is next year's dividend, r the required return and g the perpetual growth rate (all as fractions). Requires r > g.",
        "inputs": {
            "growth_rate": 5,
            "next_dividend": 2.1,
            "required_return": 10,
            "current_dividend": 2
        },
        "intrinsic_value": 42
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.105Z",
        "request_id": "cd7f9153-d530-4778-af41-d64ea761379d"
    },
    "status": "ok",
    "message": "Dividend discount model",
    "success": true
}
```

#### `GET /v1/dividend` — Yield, payout & coverage

**Parameters:**
- `price` (query, required, string) — Share price Example: `50`
- `annual_dividend` (query, optional, string) — Annual dividend per share Example: `2`
- `total_dividends` (query, optional, string) — Total dividends (with shares)
- `shares` (query, optional, string) — Shares outstanding
- `eps` (query, optional, string) — Earnings per share (for payout) Example: `4`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dividend-api/v1/dividend?price=50&annual_dividend=2&eps=4"
```

**Response:**
```json
{
    "data": {
        "eps": 4,
        "note": "Dividend yield = annual dividend / price. Payout ratio = dividend / EPS (how much of earnings is paid out); coverage = EPS / dividend (how many times earnings cover it).",
        "inputs": {
            "price": 50,
            "annual_dividend": 2
        },
        "dividend_coverage": 2,
        "payout_ratio_percent": 50,
        "dividend_yield_percent": 4,
        "retention_ratio_percent": 50,
        "annual_dividend_per_share": 2
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.196Z",
        "request_id": "3ab5bd22-b590-449f-a785-5ee0c80b5978"
    },
    "status": "ok",
    "message": "Dividend metrics",
    "success": true
}
```

#### `GET /v1/valuation` — P/E, PEG, P/B, Graham

**Parameters:**
- `price` (query, required, string) — Share price Example: `50`
- `eps` (query, required, string) — Earnings per share Example: `4`
- `growth_rate` (query, optional, string) — Annual growth % (for PEG) Example: `10`
- `book_value_per_share` (query, optional, string) — Book value per share Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dividend-api/v1/valuation?price=50&eps=4&growth_rate=10&book_value_per_share=20"
```

**Response:**
```json
{
    "data": {
        "note": "P/E = price / EPS; earnings yield = EPS / price. PEG = P/E ÷ growth%; under 1 is often called cheap-for-growth. Graham number = √(22.5 · EPS · book value) — a rough fair-value ceiling.",
        "inputs": {
            "eps": 4,
            "price": 50
        },
        "pb_ratio": 2.5,
        "pe_ratio": 12.5,
        "peg_ratio": 1.25,
        "growth_rate": 10,
        "graham_number": 42.4264,
        "book_value_per_share": 20,
        "earnings_yield_percent": 8
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.283Z",
        "request_id": "92e12145-098b-4560-95de-a69f85716800"
    },
    "status": "ok",
    "message": "Valuation ratios",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dividend-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Per-share figures in one consistent currency; rates as percentages (10 = 10%). These are valuation ratios from your inputs — for live quotes use a market-data API and for DCF/NPV an investment-appraisal API.",
        "service": "dividend-api",
        "endpoints": {
            "GET /v1/ddm": "Gordon Growth intrinsic value and implied required return.",
            "GET /v1/meta": "This document.",
            "GET /v1/dividend": "Dividend yield, payout ratio and coverage from price, dividend and EPS.",
            "GET /v1/valuation": "P/E, PEG, P/B, earnings yield and Graham number."
        },
        "description": "Stock dividend & valuation fundamentals: yield/payout/coverage, P/E, PEG, P/B, earnings yield, Graham number and the Gordon Growth dividend discount model."
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.376Z",
        "request_id": "7a31eef8-4f4a-4d33-8e18-3379710b02c9"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/dividend-api
OpenAPI spec: https://www.oanor.com/api/dividend-api/openapi.json