Dividends

Per-FY dividend table, total-return-index chart, inline upcoming book closures — plus the global cross-symbol calendar

The dividends package owns two endpoints — the per-symbol dividend history and the global cross-symbol upcoming-book-closures feed. Both share the UpcomingBookCloseRow shape so FE can render the same row in either context.

Method	Path	Cache TTL
`GET`	`/api/nepse/companies/{symbol}/fundamentals/dividends`	30 min
`GET`	`/api/nepse/upcoming-book-closes`	1 hr

GET `/companies/{symbol}/fundamentals/dividends`

Per-symbol dividend history + total-return-index chart + inline upcoming preview.

Query parameters

Param	Default	Range
`years`	5	1 – 20
`upcomingDays`	30	1 – 180

Response

{
  "message": "ok",
  "data": {
    "symbol": "NABIL",
    "years": 5,
    "rows": [
      {
        "fiscalYearBs": "2080/2081",
        "fiscalYearAd": "2023/2024",
        "bonusPercent": 5,
        "cashPercent": 15,
        "totalDistributionPercent": 20,
        "bookCloseDate":    { "ad": "2024-08-15", "bs": "2081-04-30" },
        "distributionDate": { "ad": "2024-09-10", "bs": "2081-05-25" },
        "dividendYield":    { "value": 2.78, "source": "computed", "status": "valid" },
        "rightsRatio": ""
      }
    ],
    "totalReturnIndex": [
      { "date": "2020-01-15", "indexValue": 100.0,  "type": "start" },
      { "date": "2024-08-20", "indexValue": 123.5,  "type": "dividend", "fiscalYearBs": "2080/2081" },
      { "date": "2026-05-22", "indexValue": 145.2,  "type": "latest" }
    ],
    "upcomingBookCloses": [
      {
        "symbol": "NABIL",
        "companyName": "Nabil Bank Limited",
        "kind": "dividend",
        "bookCloseDate": { "ad": "2026-06-15", "bs": "2083-03-01" },
        "fiscalYearBs": "2081/2082",
        "bonusPercent": 7,
        "cashPercent": 18
      }
    ],
    "methodology": "tr_index_reinvested_split_adjusted",
    "dataAsOf": "2026-05-23T00:00:00+05:45",
    "servedAt": "2026-05-23T14:56:30+05:45"
  }
}

Rows

rows[] merges dividend events and rights events on fiscalYearBs. A single fiscal year may have both — the row carries the dividend numbers and attaches rightsRatio when a rights offering occurred that year. Rights-only fiscal years (no dividend declared) append their own row with zero bonus/cash and dividendYield.status: upstream_missing.

Rows sort ascending by book-closure AD date — top of the table is the oldest event in the window.

Field	Type	Notes
`bonusPercent` / `cashPercent`	float	0–100 scale, % of par value (NEPSE par = 100 NPR)
`totalDistributionPercent`	float	`bonus + cash` (preferred over the stored column when non-zero)
`bookCloseDate` / `distributionDate`	`{ad, bs}`	Whole object omitted when both calendar values blank
`dividendYield`	MetricFloat64	`cash% × 100 / closeAtBookClose × 100`; null when no price covers the date
`rightsRatio`	string	Empty when no rights offering occurred that FY

Total return index

A sparse, event-anchored chart series that quotes "every NPR 100 invested at the start" as the running total return — bonus splits multiply the share count, cash dividends reinvest at the next-day open.

indexValue(t) = shares(t) × price(t) / startPrice × 100

start point   : { type: "start",    indexValue: 100,    date: <first AD price> }
each dividend : { type: "dividend", indexValue: …,      date: <next-day open AD>, fiscalYearBs }
latest point  : { type: "latest",   indexValue: …,      date: <most recent close AD> }

The methodology constant tr_index_reinvested_split_adjusted rides on the response so FE can show it under the chart legend.

Returns null when either the startOpenPrice or latestClosePrice is missing from the anchor query (the series degenerates without anchor points).

Inline upcoming book closes

upcomingBookCloses[] is the per-symbol slice of the global feed, scoped to upcomingDays. Use this when rendering the dividend page's "next book closure" banner without a second fetch.

GET /upcoming-book-closes (global)

Cross-symbol calendar of upcoming book closures (dividends + AGMs) within the window. Lives at the root /api/nepse/ scope, not under /companies/.

Query parameters

Param	Default	Range
`days`	30	1 – 180
`limit`	50	1 – 200

Response

{
  "message": "ok",
  "data": {
    "days": 30,
    "rows": [
      {
        "symbol": "NABIL",
        "companyName": "Nabil Bank Limited",
        "kind": "dividend",
        "bookCloseDate": { "ad": "2026-06-15", "bs": "2083-03-01" },
        "fiscalYearBs": "2081/2082",
        "bonusPercent": 7,
        "cashPercent": 18
      },
      {
        "symbol": "NIBL",
        "companyName": "Nepal Investment Bank Limited",
        "kind": "agm",
        "bookCloseDate": { "ad": "2026-06-22", "bs": "2083-03-08" },
        "fiscalYearBs": "2081/2082",
        "meetingType": "AGM"
      }
    ],
    "dataAsOf": "2026-05-23T14:56:30+05:45",
    "servedAt": "2026-05-23T14:56:30+05:45"
  }
}

Row kinds

`kind`	Source	Distinguishing fields
`dividend`	`nepse_corporate_dividends`	`bonusPercent`, `cashPercent`
`agm`	`nepse_corporate_agms`	`meetingType` (AGM / EGM / SGM)

Rows sort ascending by book-close date. limit caps the row count — at the cap, additional matches in the window are silently truncated.

The per-symbol dividends.upcomingBookCloses array and the global /upcoming-book-closes.rows array share the same UpcomingBookCloseRow shape. FE components that render one can render the other unchanged.

Caching

Key	TTL
`nepse:fundamentals:dividends:{SYMBOL}:y{years}:d{upcomingDays}`	30 min
`nepse:fundamentals:upcoming-book-closes:d{days}:l{limit}`	1 hr

Errors

Code	Reason
`200`	OK
`404`	Per-symbol: symbol not in `nepse_companies`. Global: never.
`500`	DB error

Dividends

On this page