FAQ — Frequently Asked Questions

Realized P/L

The realized column now tracks cash returned to you over the entire life of the investment up to the selected as_of date. We aggregate dividends, distributions, rent, staking income, company-level attributions, return of capital entries, and (when applicable) sale proceeds derived from trades or closing prices.

Because the number represents cumulative cash, it can grow even while the investment remains open. Fees, taxes, and other outflows still reduce performance metrics via the invested side, but they do not appear in the realized cash total.

For LP/GP investments without price quotes we continue to treat every inflow as cash returned. Once inflows exceed deployed capital (plus any additional fees/costs), the surplus keeps growing in the realized column even if the deal stays open — making it easy to see how much money has come back to you so far.

Remaining capital

Remaining capital tells you how much money is still exposed in the investment at the selected as_of date. For market-priced assets (stocks, crypto, ETFs) we continue to show mark-to-market change: (current_price - purchase_price) × units plus any signed cashflows up to the date.

For LP/GP or other illiquid deals without price quotes we treat the column strictly as the outstanding commitment: it starts at the initial commitment and only decreases when you record Return-of-Capital (ROC) entries. Costs, fees, taxes, and profit distributions never change this balance. After all capital has been marked as returned the balance is floored at zero while the realized column continues to grow with new payouts.

IRR and AAR use this same remaining-capital figure as the "valuation" term when no market price exists, so Excel-style IRR comparisons are possible even before the investment is formally closed.

Balance

Balance answers a simple question: "How far am I from breaking even (or how much profit is already locked in)?" It takes the lifetime realized cash (always treated as positive) and adds the remaining capital as a negative number. When remaining capital is unavailable we fall back to the initial investment so the invested side is still counted.

In formula form: Balance = Realized cash + (-abs(remaining capital or initial investment)). As long as you still have money deployed, Balance will stay negative. Once the cash you have received exceeds the outstanding amount, Balance turns positive to signal that you are playing with profits. For LP/GP deals this uses the outstanding commitment; for market-priced assets it uses the same mark-to-market value from the Remaining capital column, so gains and drawdowns are reflected automatically.

Use the Balance column on the overview page to spot which deals are close to breakeven or already "house money" so you can prioritize redeploying capital or celebrating realized wins.

Invested metric — how it's calculated

The Invested metric shows the market value of position-based assets (for example, stocks and cryptocurrencies) at the end of each reporting period. The value for a period is computed as:

market_value(period) = cumulative_units_at_period_end × period_price

Where cumulative_units_at_period_end is the net units held after applying all trades that occurred on or before the period end (BUYS and TRANSFERS increase units, SELLS decrease units). Holdings are floored at zero so market value will not be negative even if trades temporarily reduce units below zero.

Determining period_price follows this precedence (first available is used):

1. Weighted period average computed from that period's buy trades: sum(unit_price × units) / sum(units). This reflects the actual unit-weighted cost for buys that occurred inside the period.
2. Database-annotated average of unit_price (when a weighted average is not present). This is used for stability when on-period buys are absent or the two averages are nearly identical.
3. Latest PriceQuote on or before the period end (price_on_or_before). Useful when there are no buys in the period but an authoritative market quote exists.
4. Carry-forward of the last known price when neither period averages nor a PriceQuote exist. The first carry-forward seed is taken from any available PriceQuote on or before the first returned period end.
5. As a final fallback, the investment's purchase price is used if no other source is available.

Notes:

• This metric is intentionally unit-based (units × price) for position-like assets; it differs from legacy monetary aggregates which summed money flows. The unit-based approach produces correct unrealized valuations when holdings change over time.
• Transfers are treated as positive unit adjustments (like BUYs) for the purpose of computing holdings.
• If you have a large history, computing the starting cumulative units for an arbitrary displayed window requires scanning older trades. For very large datasets consider using a precomputed snapshot (a stored 'current status') as an optimization; the snapshot can seed the starting units and avoid scanning the full trade history.

Charts and analytics views

The analytics area exposes several charts and data views; this section describes the most commonly used charts, why you would use them, and what to read from each chart so you can interpret the numbers in the UI.

Invested

Shows per-period market value for position-like assets (stocks, crypto) and aggregated totals for other investment types. Calculated as described in the "Invested metric" section above.

Why use it: a quick view of the portfolio's mark-to-market exposure over time. Use it to identify trends in total invested value, such as sustained growth, drawdowns, or step-changes caused by buys/sells.

What to read:

• Rising series means growing market value due to price appreciation or additional purchases.
• Sudden drops usually indicate realized sales or rapid price declines—check cashflows and realized P/L for context.
• Compare invested chart across companies or asset classes to see concentration risk.

Monthly income (cashflows + realized P/L)

Displays cashflows (dividends, rents, distributions, fees) for each period combined with realized trade P/L (profit/loss realized when positions are sold). Cashflows are signed (positive for inflows, negative for outflows) and the chart shows the net contribution for each period.

Why use it: monitor recurring income and the contribution of realized trading to your period returns. It helps separate cash yield from mark-to-market changes.

What to read:

• Consistent positive bars indicate reliable cash yield streams (dividends, rent, distributions).
• Large positive bars combined with a reduction in invested value may indicate asset sale proceeds.
• Negative bars can appear due to fees, costs, or capital returned to the company; investigate large outflows.

Company series

Company-level aggregation groups investments by the company they belong to and sums per-period values (invested or cashflows). Useful when you want to see how a single company contributes to your portfolio across all its linked investments.

Why use it: to assess company-specific risk and to see the net contribution of a company to your portfolio performance and cashflows. Especially helpful for private equity / multi-investment relationships.

What to read:

• High company totals suggest concentration—consider diversification if a single company dominates exposure.
• Company cashflow spikes often indicate distributions; tie them to dates and investments for reconciliation.

Outstanding / Company-outstanding

Outstanding shows remaining capital outstanding for non-position investments (LP/GP) computed as initial purchase amount minus cumulative signed cashflows. Company-outstanding additionally applies company-level cashflow attribution so the company's distributions and costs are reflected appropriately in each investment's outstanding balance.

Why use it: to track the remaining capital exposure in private/illiquid investments and to see how distributions reduce outstanding capital over time.

What to read:

• Declining outstanding balances indicate capital being returned to investors (distributions or repayments).
• Flat outstanding may mean no distributions; investigate expected liquidity events if you expected returns.

Transactions / Transaction fragments

Several analytics pages use per-investment JSON fragments with paginated trade cards. These fragments are rendered server-side and available as a non-JS fallback (HTML list) as well as via JSON endpoints used by the client for AJAX pagination. The ListView endpoint is retained for analytics and testing flows.

Why use it: to drill into the underlying trades and cashflows behind chart points; use the paginated fragments to inspect individual buys, sells, transfers, fees, and corporate cashflows that produce the aggregated numbers.

What to read:

• Match a chart spike to specific transactions (large buy/sell or distribution) using the transaction fragment list.
• Use the per-card JSON endpoints for fast client-side pagination when reviewing long histories.

User flows: adding and managing data

This section explains the typical user flows for creating and managing companies, investments and transactions inside the Portfolio UI. The UI provides inline forms and modals to keep workflows fast.

Add a company

1. Click the + button in the "Your companies" pane.
2. Fill in the company name and optional metadata in the inline form.
3. Click Create to save. The new company appears in the list and you can immediately add investments to it.

Add an investment

1. In the "Your investments" pane or inside a company card click the + button next to the heading.
2. Select the investment type (Stock / Crypto / LP / GP / Other), enter a name, purchase date and purchase price.
3. Complete any investment-specific fields the form shows and click Create investment.

Edit or delete an item

• To edit a company or investment, click the ✎ edit button on its card, update fields in the inline form and save.
• To delete, click the 🗑 delete button and confirm the action in the prompt. Deleting a company does not automatically delete linked investments — follow the prompt guidance shown in the UI.

Add a transaction (cashflow or trade)

1. Open the investment's card and click Add transaction (or use the global add button).
2. Choose between cashflow or trade fields: for STOCK/CRYPTO the trade form is shown; for other investments the cashflow form is shown.
3. Enter date, amount/units, unit price, trade type (BUY/SELL/TRANSFER) and optional fee/description.
4. Click Add transaction. The transaction appears in the investment's recent transactions and contributes to analytics.

CSV import

Use the CSV import for bulk adding transactions. Click the upload CSV button on a company card or the portfolio toolbar and follow the importer UI. The importer previews parsed rows and lets you confirm or discard them before applying.

Import tips:

• Include a header row with recognizable column names (see CSV layout below).
• Use ISO date format (YYYY-MM-DD) for dates to avoid locale parsing issues.
• Preview the import and correct any mismatches before applying to your portfolio.

Backup / Export

The portfolio page provides an export button to download backup CSVs of your companies, investments and transactions. Use this to create local backups or to migrate data between accounts.

CSV file layout and fields

The export contains a small set of CSV files (one per entity type). Column names are included in the header row. The important fields are described below.

companies.csv

• id — internal id (useful for reconciling imports)
• name — company name
• slug — URL slug
• owner_id — user id of the owner

investments.csv

• id — internal id
• company_id — id of the company (empty if none)
• name, slug
• investment_type — STOCK, CRYPTO, LP, GP, OTHER
• purchase_date, purchase_price, currency

transactions.csv

Transactions include both cashflows and trades. Required columns:

• investment_id — id linking to investments.csv
• date — ISO date (YYYY-MM-DD)
• flow_type — for cashflows: DISTRIBUTION, FEE, COST, etc. Leave empty for trade rows.
• trade_type — BUY, SELL, TRANSFER (for trade rows)
• units — numeric units for trades
• unit_price — per-unit price for trades
• amount — monetary amount for cashflows (use for non-trade rows)
• fee — optional numeric
• description — optional text

When importing, the CSV importer maps columns by name where possible; ensure column headers match the names above or use the importer UI to map them manually during the preview step.