> For the complete documentation index, see [llms.txt](https://docs.baas.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.baas.sh/baas-sdk/blockchain/units.md).

# Unit conversion

On-chain values are expressed in their smallest unit: **wei** for native ETH (`1 ETH = 10¹⁸ wei`), or a token's base unit for ERC-20s. The `Units` helper converts between those raw values and human-readable amounts, so you never compute `1000000000000000` by hand. It's opt-in: a raw wei `string` or `bigint` still works anywhere a `value` is accepted.

```ts
import { Units } from '@baas/sdk';
```

## Convert ETH

ETH always has 18 decimals, so `fromEth` and `toEth` take no extra argument.

```ts
const wei = Units.fromEth(0.001); // → 1000000000000000n
const eth = Units.toEth(wei);     // → "0.001"
```

## Convert tokens

For ERC-20s, pass the token's `decimals` alongside the amount.

```ts
const decimals = 6; // the token's decimals() value

const base    = Units.fromToken('25.5', decimals); // → 25500000n
const display = Units.toToken(base, decimals);     // → "25.5"
```

If you don't already know it, read `decimals` from the contract once and reuse it:

```ts
const decimals = Number(
  await baas.contract('ERC20').address('0x…').function('decimals').read(),
);
```

## Methods

| Method                                          | Converts                 | Returns  |
| ----------------------------------------------- | ------------------------ | -------- |
| `fromEth(amount: string \| number)`             | human ETH → wei          | `bigint` |
| `toEth(value: bigint \| string)`                | wei → human ETH          | `string` |
| `fromToken(amount: string \| number, decimals)` | human token → base units | `bigint` |
| `toToken(value: bigint \| string, decimals)`    | base units → human token | `string` |

{% hint style="info" %}
**Pass large amounts as strings.** `from*` accepts `string | number`, so `Units.fromEth(0.001)` is fine. Beyond \~17 significant digits, pass a string (`Units.fromEth('123456789.123456789')`) to keep full precision. `to*` accepts `bigint | string` (not `number`), so the precise values from `getBalance()` and `read<string>()` flow through unchanged.
{% endhint %}

{% hint style="info" %}
**Rounding and errors.** When a fraction has more digits than the unit allows, `Units` rounds half up instead of truncating. Malformed input (for example `Units.fromEth('abc')`) throws viem's `InvalidDecimalNumberError`, which is not a `BaasError`.
{% endhint %}

## Next

* [Wallet operations](/baas-sdk/blockchain/wallet.md) — send transactions and read balances that use these amounts.
* [Smart contracts](/baas-sdk/blockchain/smart-contracts.md) — pass a converted `value` to payable functions.
* [Exported types](/baas-sdk/resources/exported-types.md) — import `Units` and the rest of the SDK surface.


---

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

```
GET https://docs.baas.sh/baas-sdk/blockchain/units.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.