NAV

A NAV (net asset value) is the price of one share of an instrument. The Quarzo API represents each NAV as a JSON object with three fields:

{
  "value": 1034571,
  "scale": 4,
  "currency": "EUR"
}

This value represents 103.4571 EUR for each share.

The API, the SDK and the MCP tools use this format.

Fields

Field	Type	Rule
value	integer	The price without a decimal point. A JSON number from 0 to 9007199254740991.
scale	integer	The number of decimal places of value. A JSON number from 0 to 15.
currency	string	The ISO 4217 code of the currency of the price, in uppercase: EUR or USD.

Use this rule to read a NAV:

decimal value = value / 10^scale

value	scale	currency	Value
1034571	4	EUR	103.4571 EUR
122600	4	EUR	12.26 EUR
1050	2	USD	10.50 USD
0	4	EUR	0 EUR

A NAV is not a Money value

A Money value is an amount in the minor unit of its currency: it has no scale field, and EUR has 2 decimal places. A NAV can have more decimal places than its currency: 103.4571 EUR has 4. For this reason, a NAV has its own format, with a scale field.

A NAV is not a Shares value: a share count has no currency.

Value	Format	Example
An amount of money	Money	{ "amount": "126225", "currency": "EUR" }
A number of shares	Shares	{ "quantity": 1220000, "scale": 5 }
The price of one share	NAV	{ "value": 1034571, "scale": 4, "currency": "EUR" }

Scale

The scale field is the number of decimal places of the NAV of the instrument. Quarzo does not remove trailing zeros. At scale 4, a NAV of 12.26 EUR is:

{
  "value": 122600,
  "scale": 4,
  "currency": "EUR"
}

Limits

The largest value is 9007199254740991 (2^53 − 1). The largest scale is 15. A NAV is zero or more.

With these limits, a JSON parser that reads a number as a 64-bit float or as a 64-bit integer reads each value exactly. Do not read value as a 32-bit number.

Rules for a client

• Read scale from each value. Do not keep one scale for each instrument, because the number of decimal places of the NAV of an instrument can change.
• Read value as an integer. Do not divide it with floating-point arithmetic before a comparison or a calculation.
• To calculate what a number of shares is worth, multiply the two integers: quantity × value. The result has shares scale + NAV scale decimal places. Round it to the minor unit of the currency with the rule of your business.
• Two NAVs are equal when their currency is the same and their decimal values are equal. If the scales are different, change the two values to the larger scale before you compare them.

For example, 12.2 shares at a NAV of 103.4571 EUR:

quantity = 1220000 (scale 5)
value    = 1034571 (scale 4)
product  = 1262176620000 (scale 9) = 1262.17662 EUR

Values that are not valid

The API never returns these values:

Value	Problem
{ "value": "1034571", "scale": 4, "currency": "EUR" }	value is a string.
"103.4571"	The value is a decimal string.
{ "value": 103.4571, "scale": 4, "currency": "EUR" }	value has a decimal point.
{ "value": 1034571, "currency": "EUR" }	The scale field is missing.
{ "value": 1034571, "scale": 16, "currency": "EUR" }	scale is larger than 15.
{ "value": 1034571, "scale": 4 }	The currency field is missing.
{ "amount": "10345", "currency": "EUR" }	A NAV is not a Money value.