API Reference

📖 API Reference

Detailed documentation for validator0x functions and types. All functions are exported from the main entry point.

---

🛠️ Main Functions

validateAddress

The core validation engine. It checks if an address is syntactically correct and (optionally) if it matches the blockchain's checksum or network requirements.

function validateAddress(
  address: string,
  blockchain: BlockchainType,
  options?: ValidationOptions
): ValidationResult;

Parameters

Parameter	Type	Required	Description
address	string	Yes	The wallet address string to validate.
blockchain	BlockchainType	Yes	One of: 'ethereum', 'solana', 'bitcoin', 'polygon'.
options	ValidationOptions	No	See ValidationOptions below.

Returns

Returns a ValidationResult object.

Examples

// Basic validation
const result = validateAddress(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  'ethereum'
);

// Strict mode (checksum required)
const strictResult = validateAddress(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  'ethereum',
  { strict: true }
);

// Network-specific validation
const testnetResult = validateAddress(
  'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx',
  'bitcoin',
  { network: 'testnet' }
);

---

formatAddress

Helper function to normalize and prettify addresses. Useful for UI display or database storage.

function formatAddress(
  address: string,
  blockchain: BlockchainType,
  options?: FormatOptions
): string;

Parameters

Parameter	Type	Required	Description
address	string	Yes	The address to format.
blockchain	BlockchainType	Yes	The target blockchain.
options	FormatOptions	No	See FormatOptions below.

Returns

Returns a formatted address string.

Examples

// Apply EIP-55 checksum
const checksummed = formatAddress(
  '0x742d35cc6634c0532925a3b844bc9e7595f0beb',
  'ethereum',
  { checksum: true }
);
// '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'

// Shorten for UI
const short = formatAddress(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  'ethereum',
  { shorten: true }
);
// '0x742d...0bEb'

// Custom shorten length
const customShort = formatAddress(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  'ethereum',
  { shorten: true, shortenLength: 6 }
);
// '0x742d35...5f0bEb'

---

detectBlockchain

Heuristically identifies potential blockchains for a given address.

function detectBlockchain(address: string): BlockchainType[];

Parameters

Parameter	Type	Required	Description
address	string	Yes	The address to analyze.

Returns

Returns an array of possible BlockchainType values.

Examples

// EVM address (could be Ethereum or Polygon)
const chains1 = detectBlockchain('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
// ['ethereum', 'polygon']

// Solana address
const chains2 = detectBlockchain('DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK');
// ['solana']

// Bitcoin address
const chains3 = detectBlockchain('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq');
// ['bitcoin']

---

🏗️ Types & Interfaces

BlockchainType

String literal type for supported blockchains:

type BlockchainType = 'ethereum' | 'solana' | 'bitcoin' | 'polygon';

---

ValidationResult

Field	Type	Description
valid	boolean	true if the address passes all checks.
blockchain	BlockchainType	The chain it was validated against.
error	string?	Human-readable error message (only if valid: false).
details	object?	Metadata about the address (see below).

details Object:

• format: Specific format (e.g., 'segwit', 'bech32', 'legacy').
• network: 'mainnet' or 'testnet'.
• checksum: boolean indicating if the checksum is correct.
• errorCode: A ValidationError enum value.

Example:

{
  valid: true,
  blockchain: 'ethereum',
  details: {
    format: 'eip55',
    network: 'mainnet',
    checksum: true
  }
}

---

ValidationOptions

Option	Type	Default	Description
strict	boolean	false	If true, fails if EIP-55 checksum is incorrect (ETH/Polygon).
network	string	'mainnet'	Enforce specific network validation (if supported).

Example:

const options: ValidationOptions = {
  strict: true,
  network: 'mainnet'
};

---

FormatOptions

Option	Type	Default	Description
checksum	boolean	true	Apply EIP-55 casing to Ethereum/Polygon addresses.
shorten	boolean	false	Returns truncated address like 0x12...34.
shortenLength	number	4	Number of characters to show at start and end.

Example:

const formatOptions: FormatOptions = {
  checksum: true,
  shorten: true,
  shortenLength: 6
};

---

ValidationError (Enum)

Possible values for details.errorCode:

enum ValidationError {
  INVALID_FORMAT = 'INVALID_FORMAT',
  INVALID_CHECKSUM = 'INVALID_CHECKSUM',
  INVALID_LENGTH = 'INVALID_LENGTH',
  INVALID_CHARACTERS = 'INVALID_CHARACTERS',
  UNSUPPORTED_CHAIN = 'UNSUPPORTED_CHAIN',
  BURN_ADDRESS = 'BURN_ADDRESS',
  UNSAFE_INPUT = 'UNSAFE_INPUT'
}

Error Descriptions:

• INVALID_FORMAT: Incorrect prefix or encoding.
• INVALID_CHECKSUM: Checksum verification failed (in strict mode).
• INVALID_LENGTH: Address is too short or too long.
• INVALID_CHARACTERS: Contains non-hex or invalid base58 characters.
• UNSUPPORTED_CHAIN: The requested blockchain is not implemented.
• BURN_ADDRESS: Address is a known "zero" or burn address.
• UNSAFE_INPUT: Potential injection or invalid string length.

---

🔍 Address Format Details

Ethereum & Polygon

• Format: 40 hexadecimal characters prefixed with 0x
• Length: 42 characters total
• Checksum: EIP-55 mixed-case encoding
• Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Solana

• Format: Base58-encoded 32-byte public key
• Length: 32-44 characters
• No checksum: Case-sensitive
• Example: DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK

Bitcoin

• Formats:
  • Legacy (P2PKH): Starts with 1
  • Script (P2SH): Starts with 3
  • SegWit (Bech32): Starts with bc1
  • Testnet: Starts with m, n, 2, or tb1
• Examples:
  • 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa (Legacy)
  • 3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy (P2SH)
  • bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq (SegWit)

---

💡 Usage Tips

Type Safety

Import types for better TypeScript support:

import {
  validateAddress,
  ValidationResult,
  ValidationOptions,
  BlockchainType
} from 'validator0x';

const blockchain: BlockchainType = 'ethereum';
const result: ValidationResult = validateAddress(address, blockchain);

Performance

All validation happens synchronously with minimal overhead:

// Batch validation
const addresses = ['0x...', '0x...', '0x...'];
const results = addresses.map(addr => 
  validateAddress(addr, 'ethereum')
);

Error Handling Pattern

function safeValidate(address: string, blockchain: BlockchainType) {
  try {
    const result = validateAddress(address, blockchain);
    return result;
  } catch (error) {
    return {
      valid: false,
      blockchain,
      error: 'Validation failed',
      details: { errorCode: 'UNSAFE_INPUT' }
    };
  }
}

---

Need more examples? Check out the Examples page!

Questions? Visit the FAQ or open an issue.