---
url: /topics/shares.md
---
# Shares

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

```json
{
  "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:

```text
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:

```json
{
  "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`:

```json
{
  "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](/topics/money) value and not a [NAV](/topics/nav). It has no other field. |