Shares

The Quarzo API represents each share count as a JSON object with two fields:

{
  "quantity": 1234567,
  "scale": 5
}

This value represents 12.34567 shares.

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

Fields

Field	Type	Rule
quantity	integer	The share quantity without a decimal point. A JSON number from -9007199254740991 to 9007199254740991.
scale	integer	The number of decimal places of quantity. A JSON number from 0 to 15.

Use this rule to read a Shares value:

decimal value = quantity / 10^scale

quantity	scale	Value
1234567	5	12.34567 shares
1500000	5	15 shares
1	5	0.00001 share
0	5	0 share

Scale

The scale field is the share decimalization of the instrument. Each share count of one instrument uses the same scale.

Quarzo does not remove trailing zeros. At scale 5, 15 shares are:

{
  "quantity": 1500000,
  "scale": 5
}

Limits

The largest quantity is 9007199254740991 (2^53 − 1). The largest scale is 15.

For example, this is the largest value at scale 5:

{
  "quantity": 9007199254740991,
  "scale": 5
}

This value represents 90071992547.40991 shares.

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

Sign

A quantity can be negative only when the documentation of the field allows a negative value, for example a share delta. A balance and a transfer leg are zero or more.

Rules for a client

• Read scale from each value. Do not keep one scale for each instrument, because the share decimalization of an instrument can change.
• Read quantity as an integer. Do not divide it with floating-point arithmetic before a comparison or a sum.
• Two share counts of the same instrument are equal when their quantity and their scale are equal. If the scales are different, change the two values to the larger scale before you compare them.

Values that are not valid

The API never returns these values, and it rejects them in a request:

Value	Problem
{ "quantity": "1234567", "scale": 5 }	quantity is a string.
"12.34567"	The value is a decimal string.
{ "quantity": 12.34567, "scale": 5 }	quantity has a decimal point.
{ "quantity": 1234567 }	The scale field is missing.
{ "quantity": 1234567, "scale": 16 }	scale is larger than 15.
{ "quantity": 1234567, "scale": 5, "currency": "EUR" }	A share count is not a Money value and not a NAV. It has no other field.