# format_ether

Human-readable helper for wei balances. Equivalent to format_units(amount, 18). Returns VARCHAR without introducing floating point conversion.

Canonical HTML: <https://determica.com/docs/functions/format_ether>

- Kind: scalar function
- Category: [EVM utilities](/docs/category/evm-utilities.md)
- Tags: Types, EVM

Human-readable helper for wei balances. Equivalent to format_units(amount, 18). Returns VARCHAR without introducing floating point conversion.

## Overload 1: format_ether(UINT256)

```sql
format_ether(UINT256)
```

Formats a UINT256 wei value using the fixed 18-decimal Ether scale.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `wei` (UINT256; required; positional) — Raw wei amount to display using 18 decimals.

### Returns

Ether amount string

Returns a VARCHAR decimal Ether representation without floating point conversion.

- `eth` (VARCHAR)

Ether amount string. Returns a VARCHAR decimal Ether representation without floating point conversion.

### Examples

_Local SQL · Local_

```sql
-- Display a raw wei balance as ETH
SELECT format_ether(420000000000000000::UINT256) AS eth;
-- => [{"eth":"0.42"}]
```

## Overload 2: format_ether(INT256)

```sql
format_ether(INT256)
```

Formats a signed INT256 wei delta using the fixed 18-decimal Ether scale.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `wei` (INT256; required; positional) — Raw wei amount to display using 18 decimals.

### Returns

Ether amount string

Returns a VARCHAR decimal Ether representation without floating point conversion.

- `eth` (VARCHAR)

Ether amount string. Returns a VARCHAR decimal Ether representation without floating point conversion.

### Examples

_Local SQL · Local_

```sql
SELECT format_ether((-420000000000000000)::INT256) AS eth;
```

## Guidance

### Display wei values

format_ether is format_units with decimals fixed at 18. Use it when a raw ETH or WETH balance should be shown to a human.

- The returned VARCHAR is for display; keep UINT256 wei values for calldata, simulation, and comparisons.
- Use parse_ether when converting a human ETH string back to wei.

```sql
SELECT format_ether(parse_ether('1.25')) AS eth;
```

## Related functions

- [format_units](/docs/functions/format_units.md) — Alternative
- [parse_ether](/docs/functions/parse_ether.md) — Alternative