Documentation Index
Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt
Use this file to discover all available pages before exploring further.
Finper provides two modules for tracking long-term investments outside your day-to-day accounts: Pensions for recording periodic snapshots of your pension plan, and Stocks for logging individual portfolio movements and computing an aggregated portfolio summary at runtime.
Pensions
A Pension entry is a monthly snapshot of your pension plan — not a record of an individual contribution. Each entry captures the state of the plan at a point in time, including the number of units held by both employee and employer, the per-unit value, and the monetary amounts contributed by each party.
Fields
| Field | Type | Required | Description |
|---|
date | number | ✅ | Unix timestamp (ms) — the date of the snapshot |
employeeAmount | number | ✅ | Total monetary amount contributed by the employee |
employeeUnits | number | ✅ | Number of plan units held by the employee |
companyAmount | number | ✅ | Total monetary amount contributed by the employer |
companyUnits | number | ✅ | Number of plan units held by the employer |
value | number | ✅ | Unit value at the time of the snapshot |
Endpoints
| Method | Route | Description |
|---|
POST | /api/pensions | Create a new monthly snapshot |
GET | /api/pensions | List all snapshots (chronological) |
PUT | /api/pensions/:id | Replace a snapshot record |
There is no DELETE endpoint for pension snapshots. If you need to remove an incorrect entry, use PUT /api/pensions/:id to overwrite it with corrected values.
Example: Create a pension snapshot
curl -X POST http://localhost:3008/api/pensions \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"date": 1717200000000,
"employeeAmount": 1200.50,
"employeeUnits": 42.35,
"companyAmount": 600.25,
"companyUnits": 21.10,
"value": 28.35
}'
Stocks
A Stock entry represents a single portfolio movement — a buy, sell, or dividend reinvestment. There is no persisted aggregation; the portfolio summary is computed at runtime from all recorded movements each time GET /api/stocks/summary is called.
Stock types
| Type | Description |
|---|
buy | Purchase of shares. Increases position size and total cost. |
sell | Sale of shares. Reduces position size proportionally (weighted-average cost basis). |
dividend | Dividend reinvested as additional shares. Counted separately as dividendShares. |
Endpoints
| Method | Route | Description |
|---|
GET | /api/stocks/summary | Aggregated portfolio summary (calculated at runtime) |
GET | /api/stocks | List all stock movement records |
POST | /api/stocks | Create a new stock movement |
DELETE | /api/stocks/:id | Delete a stock movement |
There is no PUT endpoint for stock entries. To correct a movement, delete it with DELETE /api/stocks/:id and recreate it with POST /api/stocks.
Stock movement fields
| Field | Type | Required | Description |
|---|
ticker | string | ✅ | Ticker symbol (automatically uppercased) |
name | string | ✅ | Human-readable company name |
shares | number | ✅ | Number of shares (positive) |
price | number | ✅ | Price per share at the time of the movement |
type | buy | sell | dividend | ✅ | Type of movement |
date | number | ✅ | Unix timestamp (ms) of the movement |
platform | string | ✅ | Broker or platform name (e.g. "DEGIRO", "Interactive Brokers") |
Portfolio summary
GET /api/stocks/summary returns a calculated object with the following shape:
{
"totalCost": 4850.00,
"totalValue": 5320.00
}
totalValue may be null if the current market price could not be fetched for one or more tickers. Individual position details — including avgCost, gainLoss, gainLossPct, and a purchases array — are available from GET /api/stocks.
Example: Record a stock purchase
curl -X POST http://localhost:3008/api/stocks \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"ticker": "MSFT",
"name": "Microsoft Corporation",
"shares": 5,
"price": 415.50,
"type": "buy",
"date": 1718000000000,
"platform": "DEGIRO"
}'
Example: Get portfolio summary
curl http://localhost:3008/api/stocks/summary \
-H 'token: <your-jwt>'
{
"totalCost": 2077.50,
"totalValue": 2189.40
}
