Reporting standard

Edition 1.6.6 (18 August 2026)

Contact: mkv@trackrecords.si

The standard is the file (or API payload) TrackRecords uses to load a book, recalculate TWR/MWR, run contribution and attribution, and apply limits and risk. It is aimed at asset managers, insurers, banks, funds, brokers and teams that already keep a back office and want the same data in the terminal.

Field names are English. You can send JSON (preferred in production) or XLSX (convenient while testing). The same payload can be posted through the snapshot API or the transaction API.

A file may contain any combination of sections. Holdings plus results are enough to inspect composition and the manager’s own figures. Transactions and prices are required to recalculate return and contribution on any date in the period.

Typical combinations:

• meta + portfolio + results: inspect holdings and the manager’s reported performance. You cannot recalculate return or run contribution.
• meta + portfolio + instruments + transactions + prices: rebuild the book, recalculate TWR/MWR, contribution and attribution, and apply limits and risk.
• Add nav if you also want portfolio-level TWR/MWR from an official NAV series.

Encoding: UTF-8. Large files may be uploaded as ZIP.

JSON shape (any section may be omitted):

1
2
3
4
5
6
7
8
9

{
  "meta": { },
  "portfolio": [ ],
  "instruments": [ ],
  "transactions": [ ],
  "prices": [ ],
  "results": [ ],
  "nav": [ ]
}

In XLSX each section is a sheet with the same column names.

Version history

TR-Validator

A Windows desktop checker (TR-Validator) can open JSON or XLSX offline, list every table, export a table to Excel, and report validation errors. It does not need an internet connection.

Requirements: Windows 10 or later, 64-bit. Unpack the archive (including certificates) into one folder and run tr_validator.exe.

Ask mkv@trackrecords.si for the current build.

meta

Identifies the book, the reporting currency and the period. start_date is the start of the reporting window (usually the previous year-end). reported_date is the date the report is built for.

* Required

portfolio (holdings on a date)

Holdings support structure, risk and stress. They do not by themselves produce a time-weighted return.

Minimum dates: period start and period end. Period start is usually the previous year-end (2024-12-31), not 2025-01-01, because year-to-date performance is measured from that NAV. Monthly month-end snapshots in the period are recommended.

Identity (rule 11): value_in_portfolio_currency = quantity × price_dirty × currency_rate, rounded to 2 decimal places (Excel stores numbers as float64).

Cash rows (asset_class_id 12, 13, 23) must use code_type = CASH, a non-empty account_number, and code equal to the account currency (ISO 4217). Payables (asset_class_id 20, 28, 30) must have price_dirty ≤ 0 and value_in_portfolio_currency ≤ 0.

If you value lots separately, send a prices row for each partition_id.

Asset classes

Names and ids are a closed list. Leading and trailing spaces in asset_class are ignored.

Listed equities, bonds and funds are resolved from the TrackRecords reference database by ISIN (or another public code). Everything else belongs in instruments: non-traded lines that are in holdings at the start or end of the period, or that appear in transactions.

Receivables vs other receivables (and the same split for payables): either class is valid. Use Receivables / Payables by default. Use the “other” class only if you need a second bucket.

Manager remuneration (37) and Administrative and other expenses (36) are special classes. In portfolio they hold only the receivable or payable outstanding on the report date (the amount already in official NAV). Accruals and cash payments belong in transactions (debt / fee). See FAQ.

instruments

* Required. Deposits and repo (asset_class_id 11, 38, 19, 20) must also fill start_date, maturity_date, nominal, yield_or_dividend_rate, yield_or_dividend_freq.

Do not repeat the same (stated_at, instrument_code) pair. Codes are trimmed of leading and trailing spaces.

results

Optional. Lets you compare the manager’s own income, TWR/MWR and fees with TrackRecords for any period and currency.

nav

TWR and MWR at portfolio level, and the effect of external flows. Prefer a point on every day of the period. Minimum: start, end, and every external-flow date.

On dates where nav and portfolio both exist, NAV must match the holdings total in the same currency (rule 27, rounded to 2 dp).

transactions

One table for cash, securities and debt. A transaction is any change in those balances: not only a trade. Think of it as a movement report for securities, cash and receivables/payables, each with a plus or minus.

The table is required if you want transaction-based performance and contribution.

Sign convention: securities, money and debt are balance changes, not the position after the event. Minus = outflow / disposal. Plus = inflow. A share sale has negative securities and positive money. Direction is carried by the sign, so there is no separate buy/sell field.

Uniqueness inside a portfolio: code_type + transaction_type + transaction_id + account_number + fee_category + partition_id.

One account_number has one currency when money ≠ 0. For multi-currency accounts use a composite code, for example 1010101010USD and 1010101010EUR. Cash code must be ISO 4217. Deposits and deposit interest use code_type = INSTRUMENT, not ISIN.

transaction_type

Which legs are required:

• securities must be non-zero for trade and transfers when code_type ≠ CASH.
• money must be non-zero for coupon, dividend, interest, amortisation, deposit, margin, forex, fee, other, repo_l1, repo_l2.
• debt must be non-zero for debt.
• Cash rows (code_type = CASH) use only forex, transfer_internal, transfer_external, cash_interest or fee.

How to book common events

Buy and sell securities

Buy: positive securities, negative money. Do not send a trade price: it is money / securities. Accrued interest sits in the dirty cash amount or in a separate row, so you do not have to choose clean vs dirty as a trade-price type.

A sale swaps the signs.

Futures

Register the contract in instruments (for example code Si-12.25), book a trade, and send prices for that code.

Opening balances

When you do not have a full history, seed positions with transfer_external. Cash is the account-currency amount. Securities are quantities only; valuation comes from prices. If lots have different prices, send a price per partition_id.

Receivables and payables

Type debt. Accrue with a positive debt for receivables (negative for payables), reverse on settlement.

Use code_type = INSTRUMENT for non-listed claims, and ISIN (or another public code) when the claim belongs to a listed security.

Accrue 1,000,000 of receivable, then write it off:

A payable uses the opposite signs: first -1000000, then +1000000 to close.

Coupon already due but not yet paid, booked on the bond itself:

Keep instrument-level claims on that instrument’s code. If you park accrued coupon or dividend on a generic instrument (accint_debits), portfolio NAV is still correct, but instrument income will miss that cash. Do not confuse this receivable with accrued interest inside prices.

If a payable is accrued and settled inside the same reporting year, still send both debt movements. See FAQ.

Repo

Two legs, repo_l1 / repo_l2, linked by connected_transaction_id. Treat repo as cash plus interest, not as a security transfer: code_type = INSTRUMENT (not the collateral ISIN). securities is +1 / -1. Terms (rate, maturity) live on instruments. Each leg has its cash amount in money.

Reverse repo (cash out, collateral in economically, booked as a receivable):

Direct repo swaps the signs (cash in on the first leg, securities = -1).

Deposits

deposit with code_type = INSTRUMENT. Terms live on instruments. Open: negative money, securities = 1. Close: opposite. Accrued interest is interest on the same code.

FX

Two forex cash rows (code_type = CASH). Actual delivery: one account is debited, another is credited. Do not send the FX rate; TrackRecords infers it from the two money amounts. securities is empty. The file must contain an even number of forex rows (rule 37).

USD sold for EUR:

Security conversion / substitution

Two trade rows, typically at 100% of face so P&L is locked on the old line and the new line starts clean. Cash nets to zero.

Internal transfers

Two transfer_internal rows with different account_number. Securities: code and quantity only. Cash: currency code and amount. The source side is negative, the destination side is positive.

Manager fees

Prefer a dedicated instrument in class Manager remuneration (37). Accrue with debt, pay with fee. fee_category distinguishes management, success, brokerage, and so on. Accrual and cash then net in analysis instead of living as two unrelated stories.

Year-end fee true-up: if advances already paid exceed the final fee, portfolio on 31 December shows a receivable in class 37 (price_dirty positive). Do not put analytical fee accruals into holdings; only the amount that is in official NAV.

Dividends

From ex-date (record date), accrue debt on the share’s code. On pay date, reverse debt and book dividend money. NAV then includes the receivable before cash arrives.

Deal fees vs administrative fees

A fee on a trade is booked on the security ISIN:

A typed cost (auditor, account keeping) uses an instrument in class Administrative and other expenses (36), which must exist in instruments:

prices

Prices under the client accounting policy, used to value the book on any date in the period. Send a quote for every asset on every day it was in the book. Dirty price is required and must include accrued interest. Currency of price_dirty should match the asset currency on the nearest portfolio row.

Required when you send transactions and want TrackRecords to recalculate return. Market (non-cash, non-user-instrument) codes in transactions or portfolio need prices covering meta.start_date through meta.reported_date (rule 28).

If price_clean, facevalue or accint is filled, the matching *_currency field is required.

Quote currency, face and accrued interest can differ. Some venues quote a USD bond with accrued interest in another currency. NAV uses price_dirty / price_dirty_currency; FX conversion is applied automatically.

For equities, funds and depositary receipts fill only price_dirty and price_dirty_currency. Leave clean price, face and accrued interest empty.

On the same code and stated_at, portfolio.price_dirty must equal prices.price_dirty (rule 36). Debt classes are excluded from that check.

Validation rules

TR-Validator and the import pipeline apply the same checks. Relative tolerance for rules 11, 27 and 36 is configurable in the validator.

FAQ

When do I use Receivables vs Other receivables? Either class is fine. Default to Receivables (18). Use Other receivables (17) only if you need a second bucket. The same rule applies to Payables (28) vs Other payables (30).

What is Manager remuneration? Class 37 marks fee claims in portfolio (outstanding payable or receivable on the report date) and fee activity in transactions (debt for accrual, fee for cash). Holdings show only the NAV-relevant balance, not the full analytical history.

What is Administrative and other expenses? Class 36 is the same pattern for auditor, account-keeping and similar costs: outstanding claim in portfolio, accrual/cash in transactions.

Do holdings show monthly fee advances and the annual true-up? Holdings show only the payable or receivable that is in official NAV on that date. Accruals and payments stay in transactions. If year-end true-up means advances exceed the final fee, book a receivable in class 37 on 31 December.

Which dates belong in portfolio? At least period start and period end. Start is usually the previous year-end, not 1 January. Month-ends in the period are recommended.

A payable was accrued and settled in the same year. Do I still send both legs? Yes: one debt to open, one debt to close (and fee or cash if you pay it).

Load the same payload through the snapshot API or the transaction API.