Multi-Chain Crypto Wallet Address Validator

r2c-wallet-validator is a comprehensive, lightweight, and high-performance utility to validate cryptocurrency wallet addresses across multiple blockchains. Built for Web3 developers, DApps, and crypto exchanges who need reliable address validation.

Maintained by Road2Crypto.com.

Table of Contents

• Features
• Installation
• Usage
  • Basic Example
  • Advanced Example
  • EVM Checksum Validation
• API Reference
  • Functions
  • Types
• Supported Chains
• Contributing
• License

Features

• 🚀 Multi-Chain Support: Validate addresses for EVM (Ethereum, Polygon, BSC), Solana, Bitcoin, Polkadot, Cosmos, TRON, and Cardano.
• 🔐 Audited Hashing: Bundles only the audited Keccak, SHA 256, and BLAKE2b code needed for checksum validation, with zero runtime dependencies.
• 🌳 Tree-Shakable: Optimized for modern bundlers (Webpack, Rollup, Vite) with sideEffects: false.
• ⚡ High Performance: Regex-based and algorithmic validation for maximum speed.
• 🎯 Selective Validation: Configure the validator to only accept specific chains relevant to your application.
• 🛡️ TypeScript: Native TypeScript support with comprehensive type definitions (.d.ts).
• 🔍 Detailed Errors: Granular error reporting for easier debugging and UI feedback.
• Supported chains: Chains

Installation

npm install r2c-wallet-validator
# or
yarn add r2c-wallet-validator
# or
pnpm add r2c-wallet-validator

Usage

Basic Example

// Simple validation example
import { isWalletValid } from "r2c-wallet-validator";

const result = isWalletValid("0x742d35Cc6634C0532925a3b844Bc454e4438f44e");

if (!result.valid) {
  console.error("Error message:", result.error?.message);
} else {
  console.log("Wallet address type:", result.type); // WalletType.EVM
}

Advanced Example

// Advanced usage with all supported address types
import {
  isWalletValid,
  ValidationErrorMessage,
  WalletType,
} from "r2c-wallet-validator";

// 1. Validate specific chains (only check Bitcoin and EVM)
const specificResult = isWalletValid(
  "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  {
    chains: [WalletType.BITCOIN, WalletType.EVM],
  }
); // Valid, type: EVM

// 2. Validate against a single specific chain
const singleChainResult = isWalletValid("InvalidBitcoin", {
  chains: [WalletType.BITCOIN],
}); // Invalid

// 3. Validate an Ethereum checksum with the EIP 155 chain ID
const ethereumResult = isWalletValid(
  "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  {
    chains: [WalletType.EVM],
    evmChainId: 1,
  }
); // Valid, type: EVM

const addresses = [
  "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", // EVM
  "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy", // Bitcoin
  "9A5oG2fXhxpBnh9qVHVk3dxp4Up1gkp8q5vj5rwiUJr", // Solana
  "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", // TRON
  "cosmos1hsk6jryyqjfhp5dhc55tc9jtckygx0eph6dd02", // Cosmos
  "invalid_address",
];

addresses.forEach((address) => {
  const result = isWalletValid(address);
  if (!result.valid) {
    switch (result.error?.message) {
      case ValidationErrorMessage.EMPTY_ADDRESS:
        console.log(`Address: ${address} is invalid: Address is empty.`);
        break;
      case ValidationErrorMessage.INVALID_ADDRESS:
        console.log(
          `Address: ${address} is invalid: Address format is incorrect.`
        );
        break;
      default:
        console.log(`Address: ${address} is invalid.`);
        break;
    }
  } else {
    switch (result.type) {
      case WalletType.EVM:
        console.log(`Address: ${address} is valid and of type EVM.`);
        break;
      case WalletType.SOLANA:
        console.log(`Address: ${address} is valid and of type Solana.`);
        break;
      case WalletType.BITCOIN:
        console.log(`Address: ${address} is valid and of type Bitcoin.`);
        break;
      case WalletType.COSMOS:
        console.log(`Address: ${address} is valid and of type Cosmos.`);
        break;
      case WalletType.TRON:
        console.log(`Address: ${address} is valid and of type TRON.`);
        break;
      default:
        console.log(`Address: ${address} is valid but of unknown type.`);
        break;
    }
  }
});

EVM Checksum Validation

Pass evmChainId when the caller knows the concrete EVM network and wants mixed-case checksum validation:

const ethereum = isWalletValid(
  "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  { chains: [WalletType.EVM], evmChainId: 1 }
);

const rootstock = isWalletValid(
  "0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD",
  { chains: [WalletType.EVM], evmChainId: 30 }
);

evmChainId is a positive safe integer containing the public EIP-155 network identifier, not an internal application or database identifier. Rootstock mainnet 30 and testnet 31 use the chain-aware EIP-1191 checksum. For chain IDs that have not opted into EIP-1191, the validator uses EIP-55.

Lowercase and uppercase address bodies remain valid unchecksummed forms. Mixed-case addresses must match the checksum for the supplied network. When evmChainId is omitted, EVM validation checks the address format only to preserve existing behavior.

API Reference

Functions

isWalletValid(address: string, options?: ValidationOptions): WalletValidationResponse

Validates a cryptocurrency wallet address.

Parameters:

• address (string): The cryptocurrency wallet address to validate.
• options (optional): Configuration object.
  • chains (WalletType[]): Array of allowed wallet types to validate against. If provided, the address must match one of the specified types.
  • evmChainId (number): Optional positive safe integer containing the EIP-155 network identifier used for EVM checksum validation.

isAddress(address: string, options?: ValidationOptions): boolean

Checks if a cryptocurrency wallet address is valid. Returns true if valid, false otherwise.

Parameters:

• address (string): The cryptocurrency wallet address to validate.
• options (optional): Configuration object.
  • chains (WalletType[]): Array of allowed wallet types to validate against. If provided, the address must match one of the specified types.
  • evmChainId (number): Optional positive safe integer containing the EIP-155 network identifier used for EVM checksum validation.

Returns:

• WalletValidationResponse: An object containing validation results:
  • When valid: { valid: true, type: WalletType }
  • When invalid: { valid: false, error: { statusCode: number, message: ValidationErrorMessage } }

Types

ValidationErrorMessage

enum ValidationErrorMessage {
  EMPTY_ADDRESS = "The provided address is empty.",
  INVALID_ADDRESS = "The provided address does not match any supported wallet address patterns.",
}

WalletType

enum WalletType {
  EVM = "evm",
  SOLANA = "solana",
  BITCOIN = "bitcoin",
  COSMOS = "cosmos",
  TRON = "tron",
  XRP = "xrp",
}

WalletValidationResponseError

interface WalletValidationResponseError {
  statusCode: number;
  message: ValidationErrorMessage;
}

WalletValidationResponse

interface WalletValidationResponse {
  valid: boolean;
  type?: WalletType;
  error?: WalletValidationResponseError;
}

ValidationOptions

interface ValidationOptions {
  chains?: WalletType[];
  evmChainId?: number;
}

Supported Chains

| Chain | Description | Example Address | | -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | EVM | EIP-55, plus EIP-1191 for Rootstock when evmChainId is supplied | 0x742d35Cc6634C0532925a3b844Bc454e4438f44e | | Solana | Solana blockchain addresses (strict 32-byte Base58 public keys) | 9A5oG2fXhxpBnh9qVHVk3dxp4Up1gkp8q5vj5rwiUJr | | Bitcoin | Bitcoin addresses (Legacy and SegWit) | 3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy | | Cosmos | Cosmos Hub cosmos1... accounts (20 byte, or 32 byte ADR 028 derived accounts) | cosmos1hsk6jryyqjfhp5dhc55tc9jtckygx0eph6dd02 | | TRON | TRON mainnet (Base58Check T... or hex 41... with optional 0x prefix) | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | Cardano | Cardano addresses (Shelley addr1..., stake1... and Byron Ae2..., DdzFF...) | addr1q9... | | Polkadot | Polkadot Mainnet addresses (SS58 format starting with 1) | 131MmXTN7xzy6wcb9di1JgChVoGjBfXMpphcGkGT6btu5YTo | | Litecoin | Litecoin addresses (Legacy L..., P2SH M.../3..., Bech32 ltc1...) | ltc1qg42tkwuuxefutzxezdkdel39gfstuap288mfea | | Dogecoin | Dogecoin addresses (Legacy D..., Multisig A.../9...) | DH5yaieqoZN36fDVciNyRueRGvGLR3mr7L | | Sui | Sui addresses (Hex 0x..., approx 66 chars) | 0x1a052c15a0c3241b1842b1096053f0b2a8d3ccdd5a747926b471e956bc1b38f8 | | Aptos | Aptos addresses (Hex 0x..., approx 66 chars) | 0x83e24403164007f3544d03e92e5e1e76b1f236e7a63d91f24d9c4912e75e927c | | TON | TON user friendly addresses (E.../U.../k.../0..., 48 chars in standard or URL safe base64) and raw addresses (0:..., -1:...) | EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N | | XRP | XRP classic addresses (r..., 25-35 chars) and X-addresses (X.../T..., 47 chars) | rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh |

Sui and Aptos addresses share the same 0x plus 64 hex character format, so the format alone cannot tell them apart. When both chains are allowed, a matching address is reported as WalletType.SUI. Pass chains: [WalletType.APTOS] to validate an address as Aptos.

Contributing

All contributions are welcome! Please feel free to open a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

About Road2Crypto

r2c-wallet-validator is maintained by Road2Crypto, the ultimate crypto portfolio tracker.

Road2Crypto allows you to track your entire crypto portfolio in one single dashboard.

• Multi-Chain Sync: Track ETH, SOL, BTC, ADA, and 100+ other chains.
• DeFi & Exchange Support: Connect Binance, Kraken, and 1,000+ DeFi protocols.
• Real-Time Analytics: Profit/Loss analysis, live price alerts, and historical data.
• 100% Secure: We never ask for your private keys.

Try Road2Crypto for Free | Download on iOS

License

This project is licensed under the MIT License - see the LICENSE file for details.