API reference

Portfolio

get/v1/portfolio

Get the portfolio

portfolio.getread tokenidempotent

The investment portfolio's value, cost and gain, today's move, and how it splits: by asset class, security type, account and tax treatment, with its concentration. Accounts left out of the ledger's totals are left out here too.

Parameters

X-Organization-Id

string | null · header

Returns 200 · Portfolio

accounts array of PortfolioAccount · required	The accounts holding it, largest first.
allocation array of Slice · required	By security type (`equity`, `etf`, `mutual fund`, …); largest first.
alternatives_value Money · required	Documented alternative investments (private equity, collectibles, …).
as_of date \| null · required	The latest date an institution priced any holding.
asset_classes array of Slice · required	`stocks`, `fixed_income`, `cash`, `crypto`, `alternatives`; largest first.
combined_value Money · required	`total_value` + `alternatives_value`.
currency string · required	The ledger's base currency; every amount is in it.
day_return Money \| null · required	Today's move, summed over the positions the market feed prices. Null until the feed has a previous close for one of them.
diversification Diversification · required
tax_treatments array of Slice · required	By tax treatment of the account; largest first.
total_cost_basis Money · required
total_value Money · required	What the securities are worth.
unrealized_gain Money · required	Value less cost, over the positions that carry a cost basis.
unrealized_gain_percent string · required	Pattern: `^-?\d+(\.\d+)?$`.

Example

curl -X GET "https://api.lumaledger.app/v1/portfolio" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/portfolio/accounts/{account_id}

Get an account's holdings

portfolio.account_holdingsread tokenidempotent

What one account holds, position by position, valued in the account's own currency and weighted within it. An account that holds nothing (a checking account, most of the time) answers with no positions, not a 404. Ids come from accounts.list.

Parameters

account_id integer · path · required
X-Organization-Id string \| null · header

Returns 200 · AccountHoldings

account_id integer · required
as_of date \| null · required	The latest date the institution priced a holding.
currency string · required	The account's currency; every amount is in it.
day_return Money \| null · required
positions array of Position · required	Largest first.
total_cost_basis Money \| null · required	Null when no position carries a cost basis.
total_value Money · required
unrealized_gain Money \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/portfolio/accounts/{account_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/portfolio/activity

List investment activity

investment_activity.listread tokenidempotent

The buys, sells, dividends, contributions, fees and transfers inside the investment accounts, newest first: the history behind the holdings. Cancelled trades are left out.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
account_id integer \| null · query	Only this investment account. Ids from `accounts.list`.
since date \| null · query	On or after this date.
until date \| null · query	On or before this date.
X-Organization-Id string \| null · header

Returns 200 · InvestmentActivityList

data array of InvestmentActivity · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/portfolio/activity" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/portfolio/positions

List positions

positions.listread tokenidempotent

Every security the portfolio holds, summed across accounts and valued in the ledger's base currency, with its weight in the whole.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
X-Organization-Id string \| null · header

Returns 200 · PositionList

data array of Position · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/portfolio/positions" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/portfolio/positions/{symbol}

Get a position

positions.getread tokenidempotent

One position by ticker: how much the ledger holds, in which accounts, its cost and gain, the latest quote and a year of daily closes. Only a ticker the ledger holds is found; this is not a market-data lookup.

Parameters

symbol string · path · required
X-Organization-Id string \| null · header

Returns 200 · PositionDetail

accounts array of PositionAccount · required	Where it is held, largest first.
average_cost UnitPrice \| null · required	Cost basis per share.
cost_basis Money \| null · required
currency string · required	The ledger's base currency; the position's amounts are in it.
day_return Money \| null · required
gain Money \| null · required
gain_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
history array of PricePoint · required	A year of daily closes, oldest first.
is_estimate boolean · required
name string · required
quantity string · required	Pattern: `^-?\d+(\.\d+)?$`.
quote Quote · required
security_type string · required
stats Stats · required
symbol string · required
value Money · required
weight string · required	Share of the whole portfolio, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

Example

curl -X GET "https://api.lumaledger.app/v1/portfolio/positions/{symbol}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

AccountHoldings

What one account holds, valued in the account's own currency and weighted within the account.

Fields

account_id integer · required
as_of date \| null · required	The latest date the institution priced a holding.
currency string · required	The account's currency; every amount is in it.
day_return Money \| null · required
positions array of Position · required	Largest first.
total_cost_basis Money \| null · required	Null when no position carries a cost basis.
total_value Money · required
unrealized_gain Money \| null · required

Diversification

Fields

effective_holdings string · required	1 / `hhi`: how many equal positions it behaves like. Pattern: `^-?\d+(\.\d+)?$`.
hhi string · required	Herfindahl–Hirschman index of the position weights, 0–1: higher is more concentrated. Pattern: `^-?\d+(\.\d+)?$`.
positions integer · required
top5_share string · required	The five largest positions' weight, 0–1. Pattern: `^-?\d+(\.\d+)?$`.
top_share string · required	The largest position's weight, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

InvestmentActivity

A trade or cash event inside an investment account.

Fields

account_id integer · required
cash Money · required	Cash into the account (positive) or out of it (negative).
date date · required
fees Money \| null · required
id integer · required
name string · required
price UnitPrice \| null · required
quantity string · required	Shares or units; 0 for a cash event. Pattern: `^-?\d+(\.\d+)?$`.
subtype string \| null · required	As the institution refines it (`dividend`, `contribution`, …).
symbol string \| null · required
type string · required	`buy`, `sell`, `cash`, `fee` or `transfer`.

InvestmentActivityList

A page of investment activity, newest first.

Fields

data array of InvestmentActivity · required
has_more boolean · required
next_cursor string \| null · required

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount string · required	Pattern: `^-?\d+\.\d{2}$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

Portfolio

The investment portfolio as a whole, valued in the ledger's base currency. Positions are listed by positions.list.

Fields

accounts array of PortfolioAccount · required	The accounts holding it, largest first.
allocation array of Slice · required	By security type (`equity`, `etf`, `mutual fund`, …); largest first.
alternatives_value Money · required	Documented alternative investments (private equity, collectibles, …).
as_of date \| null · required	The latest date an institution priced any holding.
asset_classes array of Slice · required	`stocks`, `fixed_income`, `cash`, `crypto`, `alternatives`; largest first.
combined_value Money · required	`total_value` + `alternatives_value`.
currency string · required	The ledger's base currency; every amount is in it.
day_return Money \| null · required	Today's move, summed over the positions the market feed prices. Null until the feed has a previous close for one of them.
diversification Diversification · required
tax_treatments array of Slice · required	By tax treatment of the account; largest first.
total_cost_basis Money · required
total_value Money · required	What the securities are worth.
unrealized_gain Money · required	Value less cost, over the positions that carry a cost basis.
unrealized_gain_percent string · required	Pattern: `^-?\d+(\.\d+)?$`.

PortfolioAccount

Fields

account_id integer · required
name string · required
role string \| null · required	`brokerage`, `ira`, `roth_ira`, `401k`, `hsa`, …
share string · required	Share of the holdings' value, 0–1. Pattern: `^-?\d+(\.\d+)?$`.
tax_treatment string · required	`taxable`, `tax_deferred` or `tax_free`.
value Money · required

Position

A security held, summed across the accounts that hold it.

Fields

cost_basis Money \| null · required	Null when an institution did not report one.
day_change_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
day_return Money \| null · required	What today's move did to the position.
gain Money \| null · required	`value` − `cost_basis`.
gain_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
is_estimate boolean · required	The value is the cost basis standing in for a market value.
last_price UnitPrice \| null · required	The feed's latest daily close.
last_price_date date \| null · required
name string · required
previous_close UnitPrice \| null · required
quantity string · required	Shares or units held. Pattern: `^-?\d+(\.\d+)?$`.
security_type string · required	`equity`, `etf`, `mutual fund`, `fixed income`, `cash`, `cryptocurrency`, …
symbol string · required	The ticker, as `positions.get` takes it.
value Money · required
weight string · required	Share of the list's total value, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

PositionAccount

Fields

account_id integer · required
mask string \| null · required
name string · required
quantity string · required	Pattern: `^-?\d+(\.\d+)?$`.
share string · required	This account's share of the position, 0–1. Pattern: `^-?\d+(\.\d+)?$`.
value Money · required

PositionDetail

One position: what the ledger holds of it, where, and what the market did to it over the past year.

Fields

accounts array of PositionAccount · required	Where it is held, largest first.
average_cost UnitPrice \| null · required	Cost basis per share.
cost_basis Money \| null · required
currency string · required	The ledger's base currency; the position's amounts are in it.
day_return Money \| null · required
gain Money \| null · required
gain_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
history array of PricePoint · required	A year of daily closes, oldest first.
is_estimate boolean · required
name string · required
quantity string · required	Pattern: `^-?\d+(\.\d+)?$`.
quote Quote · required
security_type string · required
stats Stats · required
symbol string · required
value Money · required
weight string · required	Share of the whole portfolio, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

PositionList

A page of positions, in symbol order.

Fields

data array of Position · required
has_more boolean · required
next_cursor string \| null · required

PricePoint

Fields

date date · required
value UnitPrice · required	The day's close.

Quote

Fields

day_change UnitPrice \| null · required	Per share.
day_change_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
last_price UnitPrice \| null · required
last_price_date date \| null · required
previous_close UnitPrice \| null · required

Slice

One slice of the portfolio's value.

Fields

key string · required
share string · required	Share of the whole, 0–1. Pattern: `^-?\d+(\.\d+)?$`.
value Money · required

Stats

The latest session's figures, and what a year of closes says.

Fields

average_volume integer \| null · required
fifty_two_week_high UnitPrice \| null · required
fifty_two_week_low UnitPrice \| null · required
high UnitPrice \| null · required
low UnitPrice \| null · required
open UnitPrice \| null · required
volume integer \| null · required

UnitPrice

A price per share or per unit. Unlike `Money` it keeps the precision the institution quoted (up to 8 places): a coin or a penny stock is not priced in whole cents.

Fields

amount string · required	Pattern: `^-?\d+(\.\d+)?$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

day_change UnitPrice \| null · required	Per share.
day_change_percent string \| null · required	Pattern: `^-?\d+(\.\d+)?$`.
last_price UnitPrice \| null · required
last_price_date date \| null · required
previous_close UnitPrice \| null · required

average_volume integer \| null · required
fifty_two_week_high UnitPrice \| null · required
fifty_two_week_low UnitPrice \| null · required
high UnitPrice \| null · required
low UnitPrice \| null · required
open UnitPrice \| null · required
volume integer \| null · required