> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Hex

:::info
`Hex` is a re-export of ox's [`Hex`](https://oxlib.sh/api/Hex). Refer to the ox documentation for the full reference.
:::

A set of Ethereum-related utility functions for working with hexadecimal string values (e.g. `"0xdeadbeef"`).

## Examples

Below are some examples demonstrating common usages of the `Hex` module:

* [Instantiating Hex](#instantiating-hex)

* [Converting from Hex](#converting-from-hex)

* [Concatenating Hex](#concatenating-hex)

* [Slicing Hex](#slicing-hex)

* [Padding Hex](#padding-hex)

* [Trimming Hex](#trimming-hex)

### Instantiating Hex

Values can be instantiated as [`Hex.Hex`](/docs/utilities/hex/types#hex) using:

* [`Hex.fromBoolean`](/docs/utilities/hex/fromBoolean)

* [`Hex.fromBytes`](/docs/utilities/hex/fromBytes)

* [`Hex.fromNumber`](/docs/utilities/hex/fromNumber)

* [`Hex.fromString`](/docs/utilities/hex/fromString)

```ts twoslash
// @noErrors
import { Bytes, Hex } from 'viem/utils'

const value_boolean = Hex.fromBoolean(true)
// @log: '0x1'

const value_bytes = Hex.fromBytes(Bytes.from([1, 2, 3]))
// @log: '0x010203'

const value_number = Hex.fromNumber(1234567890)
// @log: '0x499602d2'

const value_string = Hex.fromString('Hello World!')
// @log: '0x48656c6c6f20576f726c6421'
```

### Converting from Hex

Values can be converted from [`Hex.Hex`](/docs/utilities/hex/types#hex) using:

* [`Hex.toBoolean`](/docs/utilities/hex/toBoolean)

* [`Hex.toBytes`](/docs/utilities/hex/toBytes)

* [`Hex.toNumber`](/docs/utilities/hex/toNumber)

* [`Hex.toString`](/docs/utilities/hex/toString)

```ts twoslash
// @noErrors
import { Hex } from 'viem/utils'

const value_boolean = Hex.toBoolean('0x1')
// @log: true

const value_bytes = Hex.toBytes('0x010203')
// @log: Uint8Array [1, 2, 3]

const value_number = Hex.toNumber('0x499602d2')
// @log: 1234567890

const value_string = Hex.toString(
  '0x48656c6c6f20576f726c6421'
)
// @log: 'Hello World!'
```

### Concatenating Hex

Hex values can be concatenated using [`Hex.concat`](/docs/utilities/hex/concat):

```ts twoslash
// @noErrors
import { Hex } from 'viem/utils'

const a = Hex.fromString('0x1234567890abcdef')
const b = Hex.fromString('0xdeadbeef')
const c = Hex.concat(a, b)
// @log: '0x1234567890abcdefdeadbeef'
```

### Slicing Hex

Hex values can be sliced using [`Hex.slice`](/docs/utilities/hex/slice):

```ts twoslash
// @noErrors
import { Hex } from 'viem/utils'

const value = Hex.slice('0x1234567890abcdefdeadbeef', 2, 8)
// @log: '0x34567890'
```

### Padding Hex

Hex values can be padded with zeroes using [`Hex.padLeft`](/docs/utilities/hex/padLeft) or [`Hex.padRight`](/docs/utilities/hex/padRight):

```ts twoslash
// @noErrors
import { Hex } from 'viem/utils'

const value = Hex.padLeft('0x1234567890abcdef', 16)
// @log: '0x00000000000000001234567890abcdef'
```

### Trimming Hex

Hex values can be trimmed of zeroes using [`Hex.trimLeft`](/docs/utilities/hex/trimLeft) or [`Hex.trimRight`](/docs/utilities/hex/trimRight):

```ts twoslash
// @noErrors
import { Hex } from 'viem/utils'

const value = Hex.trimLeft(
  '0x00000000000000001234567890abcdef'
)
// @log: '0x1234567890abcdef'
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Hex.assert`](/docs/utilities/hex/assert) | Asserts if the given value is [`Hex.Hex`](/docs/utilities/hex/types#hex). |
| [`Hex.concat`](/docs/utilities/hex/concat) | Concatenates two or more [`Hex.Hex`](/docs/utilities/hex/types#hex). |
| [`Hex.from`](/docs/utilities/hex/from) | Instantiates a [`Hex.Hex`](/docs/utilities/hex/types#hex) value from a hex string or [`Bytes.Bytes`](/docs/utilities/bytes/types#bytes) value. |
| [`Hex.fromBoolean`](/docs/utilities/hex/fromBoolean) | Encodes a boolean into a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.fromBytes`](/docs/utilities/hex/fromBytes) | Encodes a [`Bytes.Bytes`](/docs/utilities/bytes/types#bytes) value into a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.fromNumber`](/docs/utilities/hex/fromNumber) | Encodes a number or bigint into a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.fromString`](/docs/utilities/hex/fromString) | Encodes a string into a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.isEqual`](/docs/utilities/hex/isEqual) | Checks if two [`Hex.Hex`](/docs/utilities/hex/types#hex) values are equal. |
| [`Hex.padLeft`](/docs/utilities/hex/padLeft) | Pads a [`Hex.Hex`](/docs/utilities/hex/types#hex) value to the left with zero bytes until it reaches the given `size` (default: 32 bytes). |
| [`Hex.padRight`](/docs/utilities/hex/padRight) | Pads a [`Hex.Hex`](/docs/utilities/hex/types#hex) value to the right with zero bytes until it reaches the given `size` (default: 32 bytes). |
| [`Hex.random`](/docs/utilities/hex/random) | Generates a random [`Hex.Hex`](/docs/utilities/hex/types#hex) value of the specified length. |
| [`Hex.size`](/docs/utilities/hex/size) | Retrieves the size of a [`Hex.Hex`](/docs/utilities/hex/types#hex) value (in bytes). |
| [`Hex.slice`](/docs/utilities/hex/slice) | Returns a section of a [`Bytes.Bytes`](/docs/utilities/bytes/types#bytes) value given a start/end bytes offset. |
| [`Hex.toBigInt`](/docs/utilities/hex/toBigInt) | Decodes a [`Hex.Hex`](/docs/utilities/hex/types#hex) value into a BigInt. |
| [`Hex.toBoolean`](/docs/utilities/hex/toBoolean) | Decodes a [`Hex.Hex`](/docs/utilities/hex/types#hex) value into a boolean. |
| [`Hex.toBytes`](/docs/utilities/hex/toBytes) | Decodes a [`Hex.Hex`](/docs/utilities/hex/types#hex) value into a [`Bytes.Bytes`](/docs/utilities/bytes/types#bytes). |
| [`Hex.toNumber`](/docs/utilities/hex/toNumber) | Decodes a [`Hex.Hex`](/docs/utilities/hex/types#hex) value into a number. |
| [`Hex.toString`](/docs/utilities/hex/toString) | Decodes a [`Hex.Hex`](/docs/utilities/hex/types#hex) value into a string. |
| [`Hex.trimLeft`](/docs/utilities/hex/trimLeft) | Trims leading zeros from a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.trimRight`](/docs/utilities/hex/trimRight) | Trims trailing zeros from a [`Hex.Hex`](/docs/utilities/hex/types#hex) value. |
| [`Hex.validate`](/docs/utilities/hex/validate) | Checks if the given value is [`Hex.Hex`](/docs/utilities/hex/types#hex). |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Hex.InvalidHexBooleanError`](/docs/utilities/hex/errors#hexinvalidhexbooleanerror) | Thrown when the provided hex value cannot be represented as a boolean. |
| [`Hex.InvalidHexTypeError`](/docs/utilities/hex/errors#hexinvalidhextypeerror) | Thrown when the provided value is not a valid hex type. |
| [`Hex.SizeExceedsPaddingSizeError`](/docs/utilities/hex/errors#hexsizeexceedspaddingsizeerror) | Thrown when the size of the value exceeds the pad size. |
| [`Hex.SizeOverflowError`](/docs/utilities/hex/errors#hexsizeoverflowerror) | Thrown when the size of the value exceeds the expected max size. |
| [`Hex.SliceOffsetOutOfBoundsError`](/docs/utilities/hex/errors#hexsliceoffsetoutofboundserror) | Thrown when the slice offset exceeds the bounds of the value. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Hex.Hex`](/docs/utilities/hex/types#hexhex) | Root type for a Hex string. |
| [`Hex.IntegerOutOfRangeError`](/docs/utilities/hex/types#hexintegeroutofrangeerror) | Re-exported from `internal/codec/int.ts`. |
| [`Hex.InvalidHexValueError`](/docs/utilities/hex/types#hexinvalidhexvalueerror) | Re-exported from `internal/codec/hex.ts`. |
| [`Hex.InvalidLengthError`](/docs/utilities/hex/types#hexinvalidlengtherror) | Re-exported from `internal/codec/hex.ts`. |