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

# primitives/TokenBalance

> Auto-generated API documentation

[**@tevm/voltaire**](../index.mdx)

***

[@tevm/voltaire](../index.mdx) / primitives/TokenBalance

# primitives/TokenBalance

## Classes

### InvalidTokenBalanceError

Defined in: [src/primitives/TokenBalance/errors.ts:23](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L23)

Base validation error

#### Example

```typescript theme={null}
throw new ValidationError('Invalid value', {
  value: '0x123',
  expected: '20 bytes',
  code: 'VALIDATION_ERROR',
  docsPath: '/primitives/address/from-hex#error-handling',
  cause: originalError
})
```

#### Extends

* [`ValidationError`](../index/index.mdx#validationerror)

#### Constructors

##### Constructor

> **new InvalidTokenBalanceError**(`message`, `options?`): [`InvalidTokenBalanceError`](#invalidtokenbalanceerror)

Defined in: [src/primitives/TokenBalance/errors.ts:24](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L24)

###### Parameters

###### message

`string`

###### options?

###### cause?

`Error`

###### code?

`string`

###### context?

`Record`\<`string`, `unknown`>

###### docsPath?

`string`

###### expected?

`string`

###### value?

`unknown`

###### Returns

[`InvalidTokenBalanceError`](#invalidtokenbalanceerror)

###### Overrides

[`ValidationError`](../index/index.mdx#validationerror).[`constructor`](../index/index.mdx#constructor-20)

#### Properties

##### cause?

> `optional` **cause**: `Error`

Defined in: [src/primitives/errors/AbstractError.ts:56](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L56)

Root cause of this error (for error chaining)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`cause`](../index/index.mdx#cause-19)

##### code

> **code**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:39](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L39)

Machine-readable error code for programmatic handling

###### Example

```ts theme={null}
'INVALID_FORMAT', 'INVALID_LENGTH'
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`code`](../index/index.mdx#code-19)

##### context?

> `optional` **context**: `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:45](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L45)

Additional context metadata for debugging

###### Example

```ts theme={null}
{ value: '0x123', expected: '20 bytes' }
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`context`](../index/index.mdx#context-19)

##### docsPath?

> `optional` **docsPath**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:51](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L51)

Path to documentation for this error

###### Example

```ts theme={null}
'/primitives/address/from-hex#error-handling'
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`docsPath`](../index/index.mdx#docspath-19)

##### expected

> **expected**: `string`

Defined in: [src/primitives/errors/ValidationError.ts:19](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/ValidationError.ts#L19)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`expected`](../index/index.mdx#expected-7)

##### value

> **value**: `unknown`

Defined in: [src/primitives/errors/ValidationError.ts:18](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/ValidationError.ts#L18)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`value`](../index/index.mdx#value-7)

#### Methods

##### getErrorChain()

> **getErrorChain**(): `string`

Defined in: [src/primitives/errors/AbstractError.ts:94](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L94)

Get full error chain as string for logging

###### Returns

`string`

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`getErrorChain`](../index/index.mdx#geterrorchain-38)

##### toJSON()

> **toJSON**(): `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:110](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L110)

Serialize error to JSON for logging/telemetry

###### Returns

`Record`\<`string`, `unknown`>

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`toJSON`](../index/index.mdx#tojson-38)

***

### TokenBalanceError

Defined in: [src/primitives/TokenBalance/errors.ts:3](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L3)

Base error for all primitive-related errors

#### Example

```typescript theme={null}
throw new PrimitiveError('Invalid primitive value', {
  code: 'INVALID_PRIMITIVE',
  context: { value: '0x123' },
  docsPath: '/primitives/overview#errors'
})
```

#### Extends

* [`PrimitiveError`](../index/index.mdx#primitiveerror)

#### Constructors

##### Constructor

> **new TokenBalanceError**(`message`, `options?`): [`TokenBalanceError`](#tokenbalanceerror)

Defined in: [src/primitives/TokenBalance/errors.ts:4](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L4)

###### Parameters

###### message

`string`

###### options?

###### cause?

`Error`

###### code?

`string`

###### context?

`Record`\<`string`, `unknown`>

###### docsPath?

`string`

###### Returns

[`TokenBalanceError`](#tokenbalanceerror)

###### Overrides

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`constructor`](../index/index.mdx#constructor-16)

#### Properties

##### cause?

> `optional` **cause**: `Error`

Defined in: [src/primitives/errors/AbstractError.ts:56](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L56)

Root cause of this error (for error chaining)

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`cause`](../index/index.mdx#cause-16)

##### code

> **code**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:39](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L39)

Machine-readable error code for programmatic handling

###### Example

```ts theme={null}
'INVALID_FORMAT', 'INVALID_LENGTH'
```

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`code`](../index/index.mdx#code-16)

##### context?

> `optional` **context**: `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:45](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L45)

Additional context metadata for debugging

###### Example

```ts theme={null}
{ value: '0x123', expected: '20 bytes' }
```

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`context`](../index/index.mdx#context-16)

##### docsPath?

> `optional` **docsPath**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:51](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L51)

Path to documentation for this error

###### Example

```ts theme={null}
'/primitives/address/from-hex#error-handling'
```

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`docsPath`](../index/index.mdx#docspath-16)

#### Methods

##### getErrorChain()

> **getErrorChain**(): `string`

Defined in: [src/primitives/errors/AbstractError.ts:94](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L94)

Get full error chain as string for logging

###### Returns

`string`

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`getErrorChain`](../index/index.mdx#geterrorchain-32)

##### toJSON()

> **toJSON**(): `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:110](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L110)

Serialize error to JSON for logging/telemetry

###### Returns

`Record`\<`string`, `unknown`>

###### Inherited from

[`PrimitiveError`](../index/index.mdx#primitiveerror).[`toJSON`](../index/index.mdx#tojson-32)

***

### TokenBalanceOverflowError

Defined in: [src/primitives/TokenBalance/errors.ts:47](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L47)

Base validation error

#### Example

```typescript theme={null}
throw new ValidationError('Invalid value', {
  value: '0x123',
  expected: '20 bytes',
  code: 'VALIDATION_ERROR',
  docsPath: '/primitives/address/from-hex#error-handling',
  cause: originalError
})
```

#### Extends

* [`ValidationError`](../index/index.mdx#validationerror)

#### Constructors

##### Constructor

> **new TokenBalanceOverflowError**(`message`, `options?`): [`TokenBalanceOverflowError`](#tokenbalanceoverflowerror)

Defined in: [src/primitives/TokenBalance/errors.ts:48](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/errors.ts#L48)

###### Parameters

###### message

`string`

###### options?

###### cause?

`Error`

###### code?

`string`

###### context?

`Record`\<`string`, `unknown`>

###### docsPath?

`string`

###### expected?

`string`

###### value?

`unknown`

###### Returns

[`TokenBalanceOverflowError`](#tokenbalanceoverflowerror)

###### Overrides

[`ValidationError`](../index/index.mdx#validationerror).[`constructor`](../index/index.mdx#constructor-20)

#### Properties

##### cause?

> `optional` **cause**: `Error`

Defined in: [src/primitives/errors/AbstractError.ts:56](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L56)

Root cause of this error (for error chaining)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`cause`](../index/index.mdx#cause-19)

##### code

> **code**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:39](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L39)

Machine-readable error code for programmatic handling

###### Example

```ts theme={null}
'INVALID_FORMAT', 'INVALID_LENGTH'
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`code`](../index/index.mdx#code-19)

##### context?

> `optional` **context**: `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:45](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L45)

Additional context metadata for debugging

###### Example

```ts theme={null}
{ value: '0x123', expected: '20 bytes' }
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`context`](../index/index.mdx#context-19)

##### docsPath?

> `optional` **docsPath**: `string`

Defined in: [src/primitives/errors/AbstractError.ts:51](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L51)

Path to documentation for this error

###### Example

```ts theme={null}
'/primitives/address/from-hex#error-handling'
```

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`docsPath`](../index/index.mdx#docspath-19)

##### expected

> **expected**: `string`

Defined in: [src/primitives/errors/ValidationError.ts:19](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/ValidationError.ts#L19)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`expected`](../index/index.mdx#expected-7)

##### value

> **value**: `unknown`

Defined in: [src/primitives/errors/ValidationError.ts:18](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/ValidationError.ts#L18)

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`value`](../index/index.mdx#value-7)

#### Methods

##### getErrorChain()

> **getErrorChain**(): `string`

Defined in: [src/primitives/errors/AbstractError.ts:94](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L94)

Get full error chain as string for logging

###### Returns

`string`

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`getErrorChain`](../index/index.mdx#geterrorchain-38)

##### toJSON()

> **toJSON**(): `Record`\<`string`, `unknown`>

Defined in: [src/primitives/errors/AbstractError.ts:110](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/errors/AbstractError.ts#L110)

Serialize error to JSON for logging/telemetry

###### Returns

`Record`\<`string`, `unknown`>

###### Inherited from

[`ValidationError`](../index/index.mdx#validationerror).[`toJSON`](../index/index.mdx#tojson-38)

## Type Aliases

### TokenBalanceType

> **TokenBalanceType** = `bigint` & `object`

Defined in: [src/primitives/TokenBalance/TokenBalanceType.ts:10](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/TokenBalanceType.ts#L10)

TokenBalance type - ERC-20 token balance

#### Type Declaration

##### \[brand]

> `readonly` **\[brand]**: `"TokenBalance"`

#### See

* [https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation
* [https://eips.ethereum.org/EIPS/eip-20](https://eips.ethereum.org/EIPS/eip-20) for ERC-20 specification

#### Since

0.0.0

## Variables

### compare()

> `const` **compare**: (`a`, `b`) => `number` = `_compare`

Defined in: [src/primitives/TokenBalance/index.ts:34](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L34)

Compare two TokenBalance values

#### Parameters

##### a

[`TokenBalanceType`](#tokenbalancetype)

First TokenBalance

##### b

[`TokenBalanceType`](#tokenbalancetype)

Second TokenBalance

#### Returns

`number`

-1 if a \< b, 0 if a === b, 1 if a > b

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
const result = TokenBalance.compare(a, b); // -1
```

***

### constants

> `const` **constants**: `object`

Defined in: [src/primitives/TokenBalance/index.ts:40](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L40)

#### Type Declaration

##### DECIMALS

> **DECIMALS**: `object`

Common decimal counts for ERC-20 tokens

###### DECIMALS.DAI

> **DAI**: `number` = `18`

###### DECIMALS.ETH

> **ETH**: `number` = `18`

###### DECIMALS.USDC

> **USDC**: `number` = `6`

###### DECIMALS.USDT

> **USDT**: `number` = `6`

###### DECIMALS.WBTC

> **WBTC**: `number` = `8`

###### DECIMALS.WETH

> **WETH**: `number` = `18`

##### MAX

> **MAX**: `bigint`

Maximum TokenBalance value (2^256 - 1)

##### MIN

> **MIN**: `bigint`

Minimum TokenBalance value (0)

***

### equals()

> `const` **equals**: (`a`, `b`) => `boolean` = `_equals`

Defined in: [src/primitives/TokenBalance/index.ts:33](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L33)

Check if two TokenBalance values are equal

#### Parameters

##### a

[`TokenBalanceType`](#tokenbalancetype)

First TokenBalance

##### b

[`TokenBalanceType`](#tokenbalancetype)

Second TokenBalance

#### Returns

`boolean`

true if equal

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(100n);
const result = TokenBalance.equals(a, b); // true
```

***

### ERC20\_SELECTORS

> `const` **ERC20\_SELECTORS**: `object`

Defined in: [src/primitives/TokenBalance/index.ts:47](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L47)

#### Type Declaration

##### allowance

> `readonly` **allowance**: `"0xdd62ed3e"` = `"0xdd62ed3e"`

##### approve

> `readonly` **approve**: `"0x095ea7b3"` = `"0x095ea7b3"`

##### balanceOf

> `readonly` **balanceOf**: `"0x70a08231"` = `"0x70a08231"`

##### totalSupply

> `readonly` **totalSupply**: `"0x18160ddd"` = `"0x18160ddd"`

##### transfer

> `readonly` **transfer**: `"0xa9059cbb"` = `"0xa9059cbb"`

##### transferFrom

> `readonly` **transferFrom**: `"0x23b872dd"` = `"0x23b872dd"`

***

### format()

> `const` **format**: (`balance`, `decimals`, `maxDecimals?`) => `string` = `_format`

Defined in: [src/primitives/TokenBalance/index.ts:35](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L35)

Format TokenBalance for display with decimals

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

##### decimals

`number`

Number of decimal places (e.g., 18 for ETH, 6 for USDC)

##### maxDecimals?

`number`

Maximum decimal places to display (for rounding)

#### Returns

`string`

Formatted string (e.g., "1.234567")

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1234567890123456789n);
const formatted = TokenBalance.format(balance, 18); // "1.234567890123456789"
const rounded = TokenBalance.format(balance, 18, 6); // "1.234568"
```

***

### from()

> `const` **from**: (`value`) => [`TokenBalanceType`](#tokenbalancetype) = `_from`

Defined in: [src/primitives/TokenBalance/index.ts:29](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L29)

Create TokenBalance from bigint, number, or string

#### Parameters

##### value

bigint, number, or decimal/hex string

`string` | `number` | `bigint`

#### Returns

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If value is out of range or invalid

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000000000000000n); // 1 token with 18 decimals
const fromNumber = TokenBalance.from(100);
const fromHex = TokenBalance.from("0xff");
```

***

### fromBaseUnit()

> `const` **fromBaseUnit**: (`amount`, `decimals`) => [`TokenBalanceType`](#tokenbalancetype) = `_fromBaseUnit`

Defined in: [src/primitives/TokenBalance/index.ts:36](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L36)

Convert from human-readable base unit to raw TokenBalance

#### Parameters

##### amount

`string`

Human-readable amount (e.g., "1.5" for 1.5 tokens)

##### decimals

`number`

Number of decimal places (e.g., 18 for ETH, 6 for USDC)

#### Returns

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If amount format is invalid

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.fromBaseUnit("1.5", 18); // 1500000000000000000n
const usdc = TokenBalance.fromBaseUnit("100.5", 6); // 100500000n
```

***

### toBaseUnit()

> `const` **toBaseUnit**: (`balance`) => `bigint` = `_toBaseUnit`

Defined in: [src/primitives/TokenBalance/index.ts:37](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L37)

Convert TokenBalance to base unit bigint (raw value)

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### Returns

`bigint`

Raw bigint value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1500000000000000000n);
const raw = TokenBalance.toBaseUnit(balance); // 1500000000000000000n
```

***

### toBigInt()

> `const` **toBigInt**: (`balance`) => `bigint` = `_toBigInt`

Defined in: [src/primitives/TokenBalance/index.ts:31](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L31)

Convert TokenBalance to bigint

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`bigint`

bigint value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000n);
const bigint = TokenBalance.toBigInt(balance); // 1000000n
```

***

### toHex()

> `const` **toHex**: (`balance`) => `string` = `_toHex`

Defined in: [src/primitives/TokenBalance/index.ts:32](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L32)

Convert TokenBalance to hex string

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`string`

Hex string with 0x prefix

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(255n);
const hex = TokenBalance.toHex(balance); // "0xff"
```

***

### toNumber()

> `const` **toNumber**: (`balance`) => `number` = `_toNumber`

Defined in: [src/primitives/TokenBalance/index.ts:30](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/index.ts#L30)

Convert TokenBalance to number (unsafe for large values)

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`number`

number value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If value exceeds Number.MAX\_SAFE\_INTEGER

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(100n);
const num = TokenBalance.toNumber(balance); // 100
```

## Functions

### \_compare()

> **\_compare**(`a`, `b`): `number`

Defined in: [src/primitives/TokenBalance/compare.js:17](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/compare.js#L17)

Compare two TokenBalance values

#### Parameters

##### a

[`TokenBalanceType`](#tokenbalancetype)

First TokenBalance

##### b

[`TokenBalanceType`](#tokenbalancetype)

Second TokenBalance

#### Returns

`number`

-1 if a \< b, 0 if a === b, 1 if a > b

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
const result = TokenBalance.compare(a, b); // -1
```

***

### \_equals()

> **\_equals**(`a`, `b`): `boolean`

Defined in: [src/primitives/TokenBalance/equals.js:17](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/equals.js#L17)

Check if two TokenBalance values are equal

#### Parameters

##### a

[`TokenBalanceType`](#tokenbalancetype)

First TokenBalance

##### b

[`TokenBalanceType`](#tokenbalancetype)

Second TokenBalance

#### Returns

`boolean`

true if equal

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(100n);
const result = TokenBalance.equals(a, b); // true
```

***

### \_format()

> **\_format**(`balance`, `decimals`, `maxDecimals?`): `string`

Defined in: [src/primitives/TokenBalance/format.js:18](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/format.js#L18)

Format TokenBalance for display with decimals

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

##### decimals

`number`

Number of decimal places (e.g., 18 for ETH, 6 for USDC)

##### maxDecimals?

`number`

Maximum decimal places to display (for rounding)

#### Returns

`string`

Formatted string (e.g., "1.234567")

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1234567890123456789n);
const formatted = TokenBalance.format(balance, 18); // "1.234567890123456789"
const rounded = TokenBalance.format(balance, 18, 6); // "1.234568"
```

***

### \_from()

> **\_from**(`value`): [`TokenBalanceType`](#tokenbalancetype)

Defined in: [src/primitives/TokenBalance/from.js:20](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/from.js#L20)

Create TokenBalance from bigint, number, or string

#### Parameters

##### value

bigint, number, or decimal/hex string

`string` | `number` | `bigint`

#### Returns

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If value is out of range or invalid

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000000000000000n); // 1 token with 18 decimals
const fromNumber = TokenBalance.from(100);
const fromHex = TokenBalance.from("0xff");
```

***

### \_fromBaseUnit()

> **\_fromBaseUnit**(`amount`, `decimals`): [`TokenBalanceType`](#tokenbalancetype)

Defined in: [src/primitives/TokenBalance/fromBaseUnit.js:19](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/fromBaseUnit.js#L19)

Convert from human-readable base unit to raw TokenBalance

#### Parameters

##### amount

`string`

Human-readable amount (e.g., "1.5" for 1.5 tokens)

##### decimals

`number`

Number of decimal places (e.g., 18 for ETH, 6 for USDC)

#### Returns

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If amount format is invalid

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.fromBaseUnit("1.5", 18); // 1500000000000000000n
const usdc = TokenBalance.fromBaseUnit("100.5", 6); // 100500000n
```

***

### \_toBaseUnit()

> **\_toBaseUnit**(`balance`): `bigint`

Defined in: [src/primitives/TokenBalance/toBaseUnit.js:15](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/toBaseUnit.js#L15)

Convert TokenBalance to base unit bigint (raw value)

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value

#### Returns

`bigint`

Raw bigint value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1500000000000000000n);
const raw = TokenBalance.toBaseUnit(balance); // 1500000000000000000n
```

***

### \_toBigInt()

> **\_toBigInt**(`balance`): `bigint`

Defined in: [src/primitives/TokenBalance/toBigInt.js:15](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/toBigInt.js#L15)

Convert TokenBalance to bigint

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`bigint`

bigint value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000n);
const bigint = TokenBalance.toBigInt(balance); // 1000000n
```

***

### \_toHex()

> **\_toHex**(`balance`): `string`

Defined in: [src/primitives/TokenBalance/toHex.js:15](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/toHex.js#L15)

Convert TokenBalance to hex string

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`string`

Hex string with 0x prefix

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(255n);
const hex = TokenBalance.toHex(balance); // "0xff"
```

***

### \_toNumber()

> **\_toNumber**(`balance`): `number`

Defined in: [src/primitives/TokenBalance/toNumber.js:16](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TokenBalance/toNumber.js#L16)

Convert TokenBalance to number (unsafe for large values)

#### Parameters

##### balance

[`TokenBalanceType`](#tokenbalancetype)

TokenBalance value to convert

#### Returns

`number`

number value

#### See

[https://voltaire.tevm.sh/primitives/token-balance](https://voltaire.tevm.sh/primitives/token-balance) for TokenBalance documentation

#### Since

0.0.0

#### Throws

If value exceeds Number.MAX\_SAFE\_INTEGER

#### Example

```javascript theme={null}
import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(100n);
const num = TokenBalance.toNumber(balance); // 100
```