Portfolio Overview

The Bullhouse NEPSE API exposes a fully authenticated Portfolio surface at /api/v1/portfolios/*. Customers create portfolios, log trades, record dividends and corporate actions, and the server recomputes their FIFO lots, holdings, and valuation series on every write — delivering live P&L, cost basis, and sector distribution back to the client without any client-side bookkeeping.

What this module owns

• 23 HTTP endpoints across 5 Swagger tags — see Reference.
• Portfolio aggregate — a portfolio is a tree: the portfolio row, its trades, its corporate actions, its dividends, and the derived projection of holdings + FIFO lots + lot consumptions.
• FIFO holdings engine — holdings.Rebuild(ctx, qtx, portfolioID, companyID) deletes the existing lots/consumptions and re-derives the entire position from the source events (trades + actions). This runs inside every trade/action mutation.
• Valuation event-replay — core.buildValuation walks all trades + actions chronologically against bulk daily prices to produce a [{d, v, cb}] time-series for charting, parameterised by range (1M, 3M, 6M, 1Y, YTD, ALL).
• Day P&L — splits intraday gains across overnight-held units, intraday-bought units, and intraday-sold units (holdings.DayPnL).
• Cache invalidation pipeline — shared.TxRunner.Run(ctx, portfolioID, scope, fn) wraps pool.Begin → fn(qtx) → Commit, then busts the appropriate cache keys post-commit. Forgetting cache invalidation requires explicitly passing CacheScopeNone.
• Trade fee model — broker rate brackets, SEBON fee, DP charge, CGT (capital gains tax) all auto-computed against the user's submitted total; mismatches raise a 400.
• Trading-day warnings — back-dated trades on non-trading days produce a soft warning rather than a hard reject.

What this module does not own

• Live market prices — those live in nepse_live_prices / nepse_intraday_prices and are populated by the scheduler/poller. Portfolio reads them but never writes them.
• The customer record — nepse_customers is owned by auth.
• Company master — nepse_companies is owned by the NEPSE catalog module.
• Watchlists — separate module with its own surface.
• Index / sub-index level data — only stocks (status = 'A') participate in portfolios.

Endpoint summary

Total: 23 endpoints. Full path table in Reference.

Sub-package layout

The module is decomposed into vertical slices, one per Swagger tag, plus two cross-cutting infrastructure packages:

internal/modules/portfolio/
├── portfolio.go          # Module + NewModule + RegisterRoutes
├── shared/               # plumbing: TxRunner, Invalidator, FindPortfolio guard, parsers
├── holdings/             # domain: Rebuild (FIFO replay) + DayPnL + HoldingResponse
├── core/                 # tag: Portfolio (CRUD + Summary + Valuation)
├── companies/            # tag: Portfolio Companies (read-side)
├── trades/               # tag: Portfolio Trades
├── dividends/            # tag: Portfolio Dividends
├── actions/              # tag: Portfolio Corporate Actions
└── smoke_db_test.go      # integration test against NewModule

8 packages exactly. Each tag-named package has its own store.go, types.go, mappers.go, service.go, handler.go. See Architecture.

Data model

• nepse_portfolio_trades, nepse_portfolio_dividends, nepse_portfolio_corporate_actions are source-of-truth event tables (CRUD by the user).
• nepse_portfolio_holdings, nepse_portfolio_lots, nepse_portfolio_lot_consumptions are a projection maintained by holdings.Rebuild. They are deleted and re-derived end-to-end on every relevant write.

Soft-delete columns (deleted_at) on the source tables; hard delete + re-create on the projection tables.

Quick start

BASE="https://api.ranjanyadav.com.np/api/v1"
JWT="..."
auth="-H Authorization: Bearer $JWT"

# Create the portfolio (first one becomes default)
PID=$(curl -s -X POST $auth -H "Content-Type: application/json" \
  -d '{"name":"Long-term"}' \
  "$BASE/portfolios" | jq -r '.data.id')

# Look up the NABIL company id (from the catalog)
CID=$(curl -s "$BASE/nepse/companies/NABIL" | jq -r '.data.id')

# Buy 100 NABIL @ 1250 — let the server compute fees from the user-supplied total
curl -s -X POST $auth -H "Content-Type: application/json" \
  -d "{
    \"companyId\":\"$CID\",
    \"type\":\"BUY\",
    \"quantity\":100,
    \"pricePerUnit\":1250.00,
    \"totalAmount\":125461.19,
    \"tradedAt\":\"2026-03-15T00:00:00.000Z\"
  }" \
  "$BASE/portfolios/$PID/trades"

# Top-level summary numbers — derives from FindDetail
curl -s $auth "$BASE/portfolios/$PID/summary" | jq .

# Bundled dashboard payload — summary, distribution, positions[]
curl -s $auth "$BASE/portfolios/$PID" | jq .data.positions

# Paginated, filterable, sortable holdings table (the dashboard table source)
curl -s $auth "$BASE/portfolios/$PID/holdings?q=bank&sort=dayPnl&order=desc&page=1&size=20" | jq .

# Sector distribution (by invested + by current value)
curl -s $auth "$BASE/portfolios/$PID/distribution" | jq .

# One-company drill-down — live price, FIFO lots, full timeline
curl -s $auth "$BASE/portfolios/$PID/companies/NABIL?lots=true" | jq .

# Time-series of value + cost basis. range ∈ {1M,3M,6M,1Y,YTD,ALL}, default 3M.
curl -s $auth "$BASE/portfolios/$PID/valuation?range=1Y" | jq '.data.series | length'

NEPSE-specific decisions

Where to go next

• Architecture — sub-package layout, request lifecycle, middleware stack.
• Data flow — write path, replay, cache invalidation.
• Holdings engine — deep dive into FIFO replay, day P&L, and valuation event-replay.
• Reference — every endpoint at a glance.