# Denomination

## When Does Redenomination Occur?

Redenomination is triggered when the available supply (total supply + debt supply - endowment pool) drops below a protocol-defined threshold. This happens as the endowment pool grows to cover long-term storage costs.

Redenomination is not imminent and may never happen. It is a safety mechanism to keep the base unit practical if the endowment pool absorbs a large share of the supply.

When triggered, the redenomination is scheduled 100 blocks (\~200 minutes) in the future. At the scheduled height, each unit becomes 1,000 units in the new denomination and the block `denomination` field increments by 1.

## Use Explicit Denomination in Transactions

Transactions have a single `denomination` field that applies to both the `reward` and `quantity` amounts. We recommend always setting it explicitly rather than leaving it at 0 (implicit/legacy).

* `denomination = 0` — uses the current block's denomination implicitly.
* `denomination >= 1` — explicitly declares the denomination.

When `denomination >= 1`, the value is included in the transaction's signed payload, so a transaction signed with an explicit denomination cannot be reinterpreted at a different denomination after a redenomination event.

To determine the current denomination, read the `denomination` field from the latest block via `GET /block/current`.

In the blocks leading up to a redenomination event (when `height` <= `redenomination_height`), transactions with `denomination = 0` are rejected (see Transition Period below). Services that always set explicit denomination will be unaffected.

## Fee Estimation

Use `/price2/` or `/optimistic_price/` endpoints for fee estimation. They return the denomination alongside the fee:

* `GET /price2/{bytes}` — estimated fee, no new wallet fee
* `GET /price2/{bytes}/{address}` — estimated fee, includes new wallet fee if the address is not in the account tree
* `GET /optimistic_price/{bytes}` — optimistic (lower) fee estimate
* `GET /optimistic_price/{bytes}/{address}` — optimistic fee with new wallet fee check

Response format:

```json
{
  "fee": "5000000",
  "denomination": 1
}
```

Note that `fee` is a JSON string (to preserve precision for large integers) while `denomination` is a JSON number. By contrast, the `denomination` field inside block JSON is a string (e.g. `"1"`).

Use the returned `fee` for the transaction `reward` field and the returned `denomination` for the transaction `denomination` field. The `quantity` field on the same transaction is interpreted in that same denomination.

The legacy `GET /price/{bytes}` endpoints return a plain integer without denomination. Migrate to `/price2/` or `/optimistic_price/`.

## Account Balances

* `GET /wallet/{address}/balance` — current balance as a plain integer, in the current denomination
* `GET /block/height/{height}/wallet/{address}/balance` — balance at a specific height, in that block's denomination

These endpoints do not include denomination in the response. Read the `denomination` field from the corresponding block to interpret the value.

When comparing balances across different block heights, normalize using each block's `denomination` field.

## Transition Period

When redenomination is scheduled, there is a transition window of up to 100 blocks (\~200 minutes) during which transactions with `denomination = 0` are rejected. This prevents ambiguity about which denomination a transaction intends.

* While the current block height is at or below `redenomination_height`, transactions with `denomination = 0` are rejected. The rejection is lifted in the block immediately after `redenomination_height`.
* Transactions with explicit denomination (`1 <= denomination <= current block denomination`) pass the denomination check throughout.

Services that always set explicit denomination experience no disruption.

## Monitoring

Monitor the `redenomination_height` field in block headers via `GET /block/current`, comparing it to the current block's `height`:

* `redenomination_height = 0` — no redenomination has ever been scheduled.
* `redenomination_height > height` — a redenomination is scheduled at that height; \~100 blocks to prepare.
* `redenomination_height > 0` and `redenomination_height <= height` — the redenomination at that height has already taken effect. In theory, multiple redenominations may occur over very long time horizons; each adds 1 to denomination and multiplies amounts by 1,000.


---

# Agent Instructions: 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:

```
GET https://docs.arweave.org/developers/development/overview/denomination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.