Shares

The Quarzo API represents each complete share count with two fields:

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

This value represents 12.34567 shares.

Fields

Field	Type	Description
quantity	integer	The share quantity without a decimal point.
scale	integer	The number of fractional digits in quantity.

Use this rule to read a Shares value:

decimal value = quantity / 10^scale

For quantity = 1234567 and scale = 5, the result is 12.34567.

The scale field is the instrument share decimalization. Do not look up the scale from another record.

Safe limits

The API accepts only safe integer values for quantity and scale.

The safe quantity range is:

-Number.MAX_SAFE_INTEGER <= quantity <= Number.MAX_SAFE_INTEGER

Number.MAX_SAFE_INTEGER is 9007199254740991.

The safe scale range is:

0 <= scale <= Number.MAX_SAFE_INTEGER

For example, this is the largest safe quantity at scale 5:

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

This value represents 90071992547.40991 shares.

The API rejects an unsafe quantity or scale.

Negative quantities are valid for share deltas. A position balance can apply its own non-negative balance rule.

Common mistakes

Do not store shares as a decimal string when the value crosses an API or event boundary.

Do not store shares as Money with a fabricated currency.

Do not omit scale:

{
  "quantity": 1234567
}

Use a complete value instead:

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