> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/finance-and-protocols/credits-subscriptions-and-decimals.md).

# Atomic Units, Decimals & Lamports

Exact amount handling across SOL lamports, SONIC Token-2022 atomics, stablecoins, subscriptions and financial ledgers.

SONIC uses **integer atomic units plus explicit decimals** for every precision-sensitive financial amount. JavaScript floating-point values are display inputs only, never canonical settlement values.

## Unit vocabulary

| Asset/domain           | Atomic unit            |        Decimals | Rule                                            |
| ---------------------- | ---------------------- | --------------: | ----------------------------------------------- |
| SOL                    | **lamport**            |           **9** | `1 SOL = 1,000,000,000 lamports`                |
| SONIC                  | token atomic/base unit |           **9** | `1 SONIC = 1,000,000,000 atomic units`          |
| SPL / Token-2022 token | token atomic/base unit |    mint-defined | read/verify decimals from trusted registry/mint |
| SaaS currency          | minor/atomic unit      | catalog-defined | persist price snapshot decimals                 |
| AI Credits             | integer ledger units   |  policy-defined | never render as a crypto balance                |

{% hint style="warning" %}
**Lamport is the atomic unit of SOL only.** Do not call SONIC or another SPL token's atomic units “lamports”, even when that token also uses 9 decimals.
{% endhint %}

## Canonical amount envelope

```ts
type AtomicAmount = {
  asset: string;
  network?: "solana" | "sui" | "offchain";
  amountAtomic: string;
  decimals: number;
  unit: "lamport" | "token-atomic" | "ledger-atomic";
};
```

Public JSON uses decimal-safe strings for atomics. Application/database logic converts to `bigint`, `Decimal`, database numeric types or another arbitrary-precision representation.

## Parsing requirements

Decimal-to-atomic conversion must:

1. accept a decimal string rather than a floating-point `number`;
2. reject negative values when the domain disallows them;
3. reject more fractional digits than the asset supports;
4. reject scientific notation unless the parser explicitly normalizes it safely;
5. return an integer atomic value;
6. never silently round a user-authorized amount.

```
"1.25" SOL  → 1_250_000_000 lamports
"1.25" SONIC → 1_250_000_000 SONIC atomic units
```

The integer values may look equal because both currently use 9 decimals; their **units and assets are not interchangeable**.

## Solana transaction handling

Network and priority fees are denominated in lamports. Token transfer/service fees are denominated in the affected token or quote asset according to their policy.

```
payment amount        token/SOL atomic units
Token-2022 fee        SONIC atomic units when applicable
Marketplace fee       quote/settlement asset atomic units
network fee           lamports
priority fee          lamports
```

A UI must not add unlike units before converting through an explicit quote/exchange-rate contract.

## SONIC near-u64 boundary

At 9 decimals the intended initial maximum is:

```
18,446,000,000 SONIC
= 18,446,000,000,000,000,000 atomic units
```

This fits within unsigned 64-bit range but is close to its upper bound. Rust/on-chain multiplication and fee calculations should therefore use checked arithmetic and wider intermediates such as `u128`, then checked conversion to the target field type.

## Subscription and ledger snapshots

Historical pricing keeps `amountAtomic`, `currency`, `decimals`, interval and catalog version. Rendering later must use the stored decimals rather than a mutable current default.

## Invariants

* no canonical money/token amount in JavaScript `number`;
* no cross-asset addition without an explicit conversion contract;
* no implied decimals from a symbol alone;
* no use of `lamports` for SPL token units;
* no silent rounding at authorization or settlement boundaries;
* provider/chain observations are reconciled against the frozen atomic intent.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/finance-and-protocols/credits-subscriptions-and-decimals.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.