> ## Documentation Index
> Fetch the complete documentation index at: https://docs.floris3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Units and Decimals

> How to convert human-readable token amounts to smallest-unit strings for API requests and responses.

Token units in the Simply Tokenized API are expressed in the **smallest unit** — an integer string with no decimal point. The number of decimal places comes from the offering's `decimals` field.

## Quick rule

To order **10 tokens** on an offering with **`decimals: 8`**:

```
10 × 10^8 = 10000000000
```

Send `"units": "10000000000"` — **not** `"10"` or `"10.0"`.

<Note>
  Always read `decimals` from the offering before creating an order or interpreting `units`, `balance`, or transaction amounts. Decimals can differ per offering.
</Note>

## Fields

| Field      | Type   | Where it appears                                                             | Meaning                                              |
| ---------- | ------ | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
| `decimals` | number | Offering, order `offering`, wallet balance, transaction                      | Number of fractional digits for the token (e.g. `8`) |
| `units`    | string | Create order (request), orders (response), transactions (response), webhooks | Token amount in smallest unit                        |
| `balance`  | string | Wallet balances                                                              | Wallet balance in smallest unit                      |

Currency amounts such as `total_amount`, `paid_amount`, and webhook `amount` are **not** smallest-unit values — they are normal currency numbers.

## Conversion

### Human amount → API `units`

```
units = human_amount × 10^decimals
```

| Human amount | `decimals` | `units` to send |
| ------------ | ---------- | --------------- |
| 1 token      | 8          | `"100000000"`   |
| 5 tokens     | 8          | `"500000000"`   |
| 10 tokens    | 8          | `"10000000000"` |
| 987 tokens   | 8          | `"98700000000"` |
| 1.5 tokens   | 8          | `"150000000"`   |

### API `units` → human amount

```
human_amount = units ÷ 10^decimals
```

Example: `"500000000"` with `decimals: 8` → **5** tokens.

## Create order example

First, get the offering and note its `decimals`:

```bash theme={null}
curl "https://dev.go.simplytokenized.com/_api/offerings/{offeringId}?lang=en" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

If the offering has `decimals: 8` and you want to order **10 tokens**:

```bash theme={null}
curl -X POST "https://dev.go.simplytokenized.com/_api/offerings/{offeringId}/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-create-abc123" \
  -d '{
    "account_id": "dabc6029-db0e-422e-a151-007cda958bf6",
    "units": "10000000000"
  }'
```

## Code examples

<CodeGroup>
  ```javascript Node.js theme={null}
  function toUnits(humanAmount, decimals) {
    const [whole, fraction = ""] = String(humanAmount).split(".");
    const paddedFraction = fraction.padEnd(decimals, "0").slice(0, decimals);
    return `${whole}${paddedFraction}`.replace(/^0+/, "") || "0";
  }

  // 10 tokens with 8 decimals
  toUnits("10", 8); // "10000000000"

  function fromUnits(units, decimals) {
    const value = units.padStart(decimals + 1, "0");
    const whole = value.slice(0, -decimals) || "0";
    const fraction = value.slice(-decimals).replace(/0+$/, "");
    return fraction ? `${whole}.${fraction}` : whole;
  }

  fromUnits("500000000", 8); // "5"
  ```

  ```python Python theme={null}
  from decimal import Decimal

  def to_units(human_amount: str, decimals: int) -> str:
      amount = Decimal(human_amount)
      factor = Decimal(10) ** decimals
      return str(int(amount * factor))

  # 10 tokens with 8 decimals
  to_units("10", 8)  # "10000000000"

  def from_units(units: str, decimals: int) -> str:
      amount = Decimal(units) / (Decimal(10) ** decimals)
      return format(amount.normalize(), "f")

  from_units("500000000", 8)  # "5"
  ```
</CodeGroup>

## Where this applies

| API                                                                | Field     | Direction                    |
| ------------------------------------------------------------------ | --------- | ---------------------------- |
| [Create order](/api-reference/endpoint/createOrder)                | `units`   | Request — send smallest unit |
| [List offering orders](/api-reference/endpoint/listOfferingOrders) | `units`   | Response                     |
| [Get offering order](/api-reference/endpoint/getOfferingOrder)     | `units`   | Response                     |
| [List account orders](/api-reference/endpoint/listAccountOrders)   | `units`   | Response                     |
| [Get wallet balances](/api-reference/endpoint/getWalletBalances)   | `balance` | Response                     |
| [List transactions](/api-reference/endpoint/getTransactions)       | `units`   | Response                     |
| [Webhook events](/webhooks/events)                                 | `units`   | Event payload                |

## Common mistakes

| Mistake                                        | Result                                                         |
| ---------------------------------------------- | -------------------------------------------------------------- |
| Sending `"units": "10"` when `decimals` is `8` | Orders **0.00000010** tokens instead of 10                     |
| Using a float like `10000000000.0`             | Validation error — `units` must be a string                    |
| Assuming all offerings use 8 decimals          | Wrong amount — always read `decimals` from the offering        |
| Confusing `units` with `total_amount`          | `total_amount` is currency (e.g. USD), not token smallest unit |