Try it Live

Run Base64 examples in the interactive playground

Encoding

Methods for encoding binary data and strings to base64 format.

Standard Base64 Encoding

TypeScript

`Base64.encode(data)`

Encodes bytes to standard base64 string using RFC 4648 alphabet (A-Z, a-z, 0-9, +, /) with padding.

const data = new Uint8Array([72, 101, 108, 108, 111])
const encoded = Base64.encode(data)
// "SGVsbG8="

// Works with any binary data
const binary = new Uint8Array([0xff, 0xfe, 0xfd])
const encoded2 = Base64.encode(binary)
// "/v79"

Parameters:

data: Uint8Array - Binary data to encode

Returns: Base64String - Standard base64-encoded string with paddingExample:

// Encode transaction hash
const hash = Bytes32() // 32-byte hash
const b64Hash = Base64.encode(hash)
console.log(b64Hash.length) // 44 characters (32 * 4/3 rounded up)

Defined in: primitives/Base64/BrandedBase64/encode.js:17

`Base64.encodeString(str)`

Encodes UTF-8 string to standard base64. Internally converts string to bytes using TextEncoder, then encodes to base64.

const message = "Hello, world!"
const encoded = Base64.encodeString(message)
// "SGVsbG8sIHdvcmxkIQ=="

// Works with Unicode
const unicode = "Hello, 世界!"
const encodedUnicode = Base64.encodeString(unicode)

// Decode back to original
const decoded = Base64.decodeToString(encodedUnicode)
console.log(decoded === unicode) // true

Parameters:

str: string - UTF-8 string to encode

Returns: Base64String - Base64-encoded string Example:

// Encode JSON data
const json = JSON.stringify({ foo: "bar", num: 42 })
const encoded = Base64.encodeString(json)

// Later decode and parse
const decoded = Base64.decodeToString(encoded)
const obj = JSON.parse(decoded)

Defined in: primitives/Base64/BrandedBase64/encodeString.js:14

URL-Safe Base64 Encoding

TypeScript

`Base64.encodeUrlSafe(data)`

Encodes bytes to URL-safe base64 string. Uses URL-safe alphabet (A-Z, a-z, 0-9, -, _) and removes padding characters.Differences from standard base64:

Replaces + with -
Replaces / with _
Removes = padding

const data = new Uint8Array([255, 254, 253])
const encoded = Base64.encodeUrlSafe(data)
// URL-safe, no padding

// Safe for URLs
const url = `https://example.com/data/${encoded}`

// Safe for filenames
const filename = `cache-${encoded}.dat`

Parameters:

data: Uint8Array - Binary data to encode

Returns: Base64UrlString - URL-safe base64 string without paddingExample:

// Encode token for URL
const tokenBytes = Bytes16() // 16-byte random token
crypto.getRandomValues(tokenBytes)
const token = Base64.encodeUrlSafe(tokenBytes)

// Use in URL without encoding
const apiUrl = `https://api.example.com/auth?token=${token}`

Defined in: primitives/Base64/BrandedBase64/encodeUrlSafe.js:19

`Base64.encodeStringUrlSafe(str)`

Encodes UTF-8 string to URL-safe base64. Combines TextEncoder with URL-safe base64 encoding.

const email = "user@example.com"
const encoded = Base64.encodeStringUrlSafe(email)
// No +, /, or = characters - safe for URLs

// Use in URL path or query parameter
const url = `/users/${encoded}`

Parameters:

str: string - UTF-8 string to encode

Returns: Base64UrlString - URL-safe base64 string Example:

// Encode state parameter for OAuth
const state = JSON.stringify({
  returnUrl: "/dashboard",
  timestamp: Date.now()
})
const encodedState = Base64.encodeStringUrlSafe(state)
const oauthUrl = `https://oauth.example.com/authorize?state=${encodedState}`

Defined in: primitives/Base64/BrandedBase64/encodeStringUrlSafe.js:9

Usage Patterns

Encoding with Size Calculation

// Pre-calculate encoded size
const dataSize = 1024
const encodedSize = Base64.calcEncodedSize(dataSize)

// Allocate exact buffer size needed
const data = new Uint8Array(dataSize)
const encoded = Base64.encode(data)
console.log(encoded.length === encodedSize) // true

Choosing Standard vs URL-Safe

// Use standard for general data encoding
const serialized = Base64.encodeString(JSON.stringify(data))

// Use URL-safe when output appears in URLs
const urlSafeId = Base64.encodeUrlSafe(idBytes)
const link = `https://example.com/item/${urlSafeId}` // No escaping needed

// Use URL-safe for filenames
const filename = `cache-${Base64.encodeUrlSafe(hash)}.bin`

Encoding Large Data

// For large data, consider chunking
function encodeChunked(data: Uint8Array, chunkSize = 1024): string[] {
  const chunks: string[] = []
  for (let i = 0; i < data.length; i += chunkSize) {
    const chunk = data.slice(i, i + chunkSize)
    chunks.push(Base64.encode(chunk))
  }
  return chunks
}

// Decode back
function decodeChunked(chunks: string[]): Uint8Array {
  const decoded = chunks.map(Base64.decode)
  const totalLength = decoded.reduce((sum, arr) => sum + arr.length, 0)
  const result = new Uint8Array(totalLength)
  let offset = 0
  for (const chunk of decoded) {
    result.set(chunk, offset)
    offset += chunk.length
  }
  return result
}

Binary Data Encoding

// Encode Ethereum address (20 bytes)
const address = new Uint8Array(20)
const b64Address = Base64.encode(address)

// Encode transaction signature (65 bytes)
const signature = new Uint8Array(65)
const b64Sig = Base64.encode(signature)

// Encode arbitrary binary
const binaryData = new Uint8Array([0x00, 0xff, 0x80, 0x7f])
const encoded = Base64.encode(binaryData)

Encoding Algorithm

Standard base64 encoding process:

Group input: Split input bytes into 3-byte groups
Convert to base64: Each 3-byte group becomes 4 base64 characters
Padding: If final group has fewer than 3 bytes, pad with =

Visual: 3 Bytes → 4 Characters

Input bytes:     [01001000] [01100101] [01101100]
                  H (72)     e (101)    l (108)

6-bit groups:    [010010] [000110] [010101] [101100]
                   18       6        21       44

Base64 chars:     S         G        V        s
                 (A-Z: 0-25, a-z: 26-51, 0-9: 52-61, +/: 62-63)

Complete Example: “Hello” → “SGVsbG8=”

Input:    H      e      l      l      o
Hex:      48     65     6c     6c     6f
Binary:   01001000 01100101 01101100 01101100 01101111
                  ↓ 6-bit groups
6-bits:   010010 | 000110 | 010101 | 101100 | 011011 | 000110 | 1111xx
Index:    18     | 6      | 21     | 44     | 27     | 6      | 60
Base64:   S      | G      | V      | s      | b      | G      | 8      | = (padding)
Output:   S G V s b G 8 =

Padding Rules:

Input length % 3 == 0: No padding (SGVs)
Input length % 3 == 1: Add == (SGVsbG8=)
Input length % 3 == 2: Add = (SGVsbGk=)

URL-safe encoding applies character substitutions after standard encoding:

// Standard: SGVs+G8/bG8=
// URL-safe: SGVs-G8_bG8  (no padding)
// Changes: + → -, / → _, = removed

Decoding - Decoding base64 strings
Validation - Validating base64 format
Utilities - Size calculations
BrandedBase64 - Tree-shakeable API

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Base64 Encoding

Try it Live

Encoding

Standard Base64 Encoding

`Base64.encode(data)`

`Base64.encodeString(str)`

URL-Safe Base64 Encoding

`Base64.encodeUrlSafe(data)`

`Base64.encodeStringUrlSafe(str)`

Usage Patterns

Encoding with Size Calculation

Choosing Standard vs URL-Safe

Encoding Large Data

Binary Data Encoding

Encoding Algorithm

Visual: 3 Bytes → 4 Characters

Complete Example: “Hello” → “SGVsbG8=”

Try it Live

​Encoding

​Standard Base64 Encoding

​Base64.encode(data)

​Base64.encodeString(str)

​URL-Safe Base64 Encoding

​Base64.encodeUrlSafe(data)

​Base64.encodeStringUrlSafe(str)

​Usage Patterns

​Encoding with Size Calculation

​Choosing Standard vs URL-Safe

​Encoding Large Data

​Binary Data Encoding

​Encoding Algorithm

​Visual: 3 Bytes → 4 Characters

​Complete Example: “Hello” → “SGVsbG8=”

​Related

Encoding

Standard Base64 Encoding

`Base64.encode(data)`

`Base64.encodeString(str)`

URL-Safe Base64 Encoding

`Base64.encodeUrlSafe(data)`

`Base64.encodeStringUrlSafe(str)`

Usage Patterns

Encoding with Size Calculation

Choosing Standard vs URL-Safe

Encoding Large Data

Binary Data Encoding

Encoding Algorithm

Visual: 3 Bytes → 4 Characters

Complete Example: “Hello” → “SGVsbG8=”

Related