---
title: "Wallet address validator"
url: "https://platformdocs.coinme.com/#/docs/wallet-address-validator"
markdown: "https://platformdocs.coinme.com/docs/wallet-address-validator.md"
summary: "Check that a cryptocurrency wallet address is well-formed before you store it or send funds to it. One typed function covers 160+ coins and tokens across more than 60 chains. It runs offline with zero runtime dependencies and works the same in the browser, Node.js, and React Native."
surface: "both"
platform: "web"
package: "@coinme/wallet-address-validator"
version: "1.2.0"
updated: "2026-10-21"
---

# Wallet address validator

Check that a cryptocurrency wallet address is well-formed before you store it or send funds to it. One typed function covers 160+ coins and tokens across more than 60 chains. It runs offline with zero runtime dependencies and works the same in the browser, Node.js, and React Native.

```typescript
import { validateAddress } from '@coinme/wallet-address-validator';

validateAddress({
  address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  currency: 'usdt',
  chainType: 'tron',
  strict: true,
}); // → true
```

The package is `@coinme/wallet-address-validator`. It makes no network requests and talks to no Coinme service, so it needs no credentials beyond the registry token that installs it, and it fits either way of building on Coinme. A Widget partner checks an address before passing it to the widget as `walletAddress` (see the [field table on Build](https://platformdocs.coinme.com/pages/build/index.md#config)), and a Coinme-as-a-Service partner checks the send or withdrawal addresses its own screens collect.

## Why use it

Most blockchains cannot reverse a transfer. If a user pastes an address with a typo, an address for the wrong chain, or something that is not an address at all, the funds are usually gone. Catching that in the address field is the cheapest place to stop it.

`validateAddress` checks what a chain itself checks: the address length and characters, the network prefix, and the checksum the chain uses to catch typos. It returns a plain `true` or `false`, and it tells you separately when it cannot judge an asset at all, so an unsupported asset never looks like a valid address.

What this package adds over a hand-rolled regex or a typical open-source validator:

- **Cross-chain mistakes are caught.** With `chainType` and `strict: true`, a Tron address is rejected for USDT on Ethereum, a Bitcoin address is rejected for Litecoin, and a currency/chain pair that does not go together throws instead of quietly validating something else.
- **Real checksums for every family it supports**, including CashAddr (Bitcoin Cash), bech32/bech32m (SegWit and Taproot), EIP-55 (EVM), SS58 (Polkadot), CRC16 (Stellar, TON), and Cardano Shelley and Byron.
- **The address formats users actually paste**: XRP X-addresses, Stellar muxed accounts, TON raw and friendly forms, Hedera checksummed ids and EVM aliases.
- **Safe on hostile input.** Oversized or malformed input returns `false` quickly instead of hanging the UI thread.
- **One package for every runtime.** No Node built-ins, no native modules, no polyfills. It is tested on every change as an installed package under Node (ESM and CommonJS), TypeScript, a Vite browser bundle, and Metro (React Native).
- **Typed and introspectable.** TypeScript declarations ship with the package, and `getSupportedAssets()` / `getSupportedChains()` expose the supported list at runtime.

### What it does not check

This is a format validator, not a blockchain client. It makes no network requests, so it cannot tell you whether an address exists, holds a balance, is controlled by your user, or belongs to a sanctioned party. `true` means "this is a well-formed address for this asset and chain", not "this is safe to send to". Pair it with your own controls (address ownership checks, allow-lists, screening, or a small test transfer) where that matters.

It also does not validate memos or destination tags; see [Memos and destination tags](#memos-and-destination-tags).

## Install

The package is published to Coinme's private npm registry. Configure the `@coinme` scope with the registry token Coinme provides, then install.

`.npmrc` (npm / Yarn Classic):

```properties
@coinme:registry=https://npm.coinme.com/coinme-sdk-frontend/
//npm.coinme.com/coinme-sdk-frontend/:_authToken=${COINME_REGISTRY_TOKEN}
//npm.coinme.com/coinme-sdk-frontend/:always-auth=true
```

`.yarnrc.yml` (Yarn Berry v2+):

```yaml
npmScopes:
  coinme:
    npmRegistryServer: 'https://npm.coinme.com/coinme-sdk-frontend/'
    npmAuthToken: '${COINME_REGISTRY_TOKEN}'
    npmAlwaysAuth: true
```

Then export the token and install:

```bash
export COINME_REGISTRY_TOKEN=<your-token>
npm install @coinme/wallet-address-validator
# or: yarn add @coinme/wallet-address-validator
```

`COINME_REGISTRY_TOKEN` is the read-only registry access token. Request it from your Coinme integration contact. Treat it like any other credential: keep it in your CI secret store and out of source control.

The package has no runtime or peer dependencies.

## Quickstart

```typescript
import {
  UnsupportedChainError,
  UnsupportedCurrencyError,
  validateAddress,
} from '@coinme/wallet-address-validator';

// Single-chain assets: currency alone picks the validator.
validateAddress({
  address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
  currency: 'btc',
}); // → true

validateAddress({ address: 'not-an-address', currency: 'btc' }); // → false

// Multi-chain assets: say which chain the address is on.
validateAddress({
  address: 'GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ',
  currency: 'usdc',
  chainType: 'stellar',
  strict: true,
}); // → true

// Testnet.
validateAddress({
  address: 'mipcBbFg9gMiCh81Kj8tqqdgoZub1ZJRfn',
  currency: 'btc',
  network: 'testnet',
}); // → true

// Unsupported assets throw rather than returning false.
try {
  validateAddress({ address: '...', currency: 'xyz', strict: true });
} catch (e) {
  if (e instanceof UnsupportedCurrencyError) {
    console.log(e.currency); // "xyz"
  }
}
```

## Recommended integration

1. **Use `strict: true`.** It turns integration mistakes (an unknown currency, a misspelled or mismatched `chainType`, a missing chain for USDT/USDC) into errors you see in development instead of looser validation in production.
2. **Always pass `chainType` for assets that live on more than one chain.** Strict mode requires it for `usdt` and `usdc`. For EVM tokens it lets you reject a valid address on the wrong chain family.
3. **Trim the input first.** `validateAddress` does not trim or otherwise edit the address. Leading or trailing whitespace makes it invalid.
4. **Strip payment URIs.** `bitcoin:…?amount=…`, `ethereum:…@1` and similar URIs are not addresses. The one exception is Bitcoin Cash, where the `bitcoincash:` (or `bchtest:`) prefix is part of the address format and is optional.
5. **Treat the three outcomes differently in your UI:**

| Outcome | Meaning | Suggested handling |
| --- | --- | --- |
| `true` | Well-formed address for this asset/chain | Proceed (with your own ownership and compliance checks) |
| `false` | Not a valid address for this asset/chain | Show a field error, e.g. "This isn't a valid USDC (Stellar) address" |
| `UnsupportedCurrencyError`, `UnsupportedChainError` | This library cannot judge this asset/chain | Integration issue: log it, and don't let the user send to an unvalidated address |

```typescript
import {
  UnsupportedChainError,
  UnsupportedCurrencyError,
  validateAddress,
} from '@coinme/wallet-address-validator';

type Result = 'valid' | 'invalid' | 'unsupported';

const checkAddress = (
  address: string,
  currency: string,
  chainType?: string
): Result => {
  try {
    return validateAddress({
      address: address.trim(),
      currency,
      chainType,
      strict: true,
    })
      ? 'valid'
      : 'invalid';
  } catch (e) {
    if (
      e instanceof UnsupportedCurrencyError ||
      e instanceof UnsupportedChainError
    ) {
      return 'unsupported';
    }
    throw e;
  }
};
```

`validateAddress` does no I/O and is fast, so it is fine to call on every keystroke.

## API

### `validateAddress(params): boolean`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | `string` | yes | The address to validate. Not trimmed. A non-string returns `false`. |
| `currency` | `string` | yes | Currency symbol or name, e.g. `'btc'`, `'bitcoin'`, `'usdc'`. Case-insensitive. |
| `chainType` | `string` | no | The chain the address is on: a chain id or alias, e.g. `'ethereum'`, `'erc20'`, `'tron'`, `'trc20'`. See [Chains](#chains-and-chaintype). |
| `network` | `'mainnet' \| 'testnet'` | no | Network to validate against. Defaults to `'mainnet'`. See [Networks](#networks). |
| `strict` | `boolean` | no | Strict currency/chain checking. Defaults to `false`. See [Strict mode](#strict-mode). |

Returns `true` if the address is valid for the currency (and chain), `false` otherwise.

Throws:

- `UnsupportedCurrencyError` if the currency is not supported. (For backward compatibility, without `strict` an unknown currency is still validated by its chain alone when `chainType` is a chain id such as `'ethereum'` or one of the aliases `erc20`, `binance`, `matic`, `omni`, `raiblocks`, `hyperspace`, `ton`. Ticker and token-standard aliases such as `eth` or `trc20` do not do this.)
- `UnsupportedChainError` in strict mode, if `chainType` is missing for a multi-chain asset, unrecognized, or does not use the currency's address format.
- `TypeError` if `network` is neither `'mainnet'` nor `'testnet'`.

### Strict mode

`strict` defaults to `false` so existing integrations keep their behavior. With `strict: true`:

- The `currency` must be supported, even if `chainType` names a known chain.
- A `chainType`, when given, must be recognized and must use the currency's address format: `btc` on `bitcoin`, `usdt` on `tron`, any EVM token on any EVM chain. `btc` on `ethereum` or `usdc` on `tron` throws `UnsupportedChainError`.
- `usdt` and `usdc` require a `chainType`, because their address format depends on the chain.

Without `strict`, an unrecognized `chainType` is ignored, and `usdt`/`usdc` without a recognized chain accept an address that is valid on any of their common chains. Prefer strict mode for new integrations.

### `UnsupportedCurrencyError`

```typescript
class UnsupportedCurrencyError extends Error {
  readonly currency: string; // the currency you passed
}
```

### `UnsupportedChainError`

```typescript
class UnsupportedChainError extends Error {
  readonly currency: string;
  readonly chainType: string | undefined; // undefined when it was required but missing
}
```

### `isSupported({ currency, chainType?, strict? }): boolean`

Whether `validateAddress` would accept this currency/chain pair (with the same `strict` setting) without throwing. Use it to decide which assets to offer, or to fail fast at startup if your asset configuration references something this library cannot validate.

```typescript
isSupported({ currency: 'usdc', chainType: 'solana', strict: true }); // → true
isSupported({ currency: 'usdc', strict: true }); // → false (chainType required)
```

### `getSupportedAssets(): SupportedAsset[]`

Every supported currency, from the same registry `validateAddress` uses.

```typescript
interface SupportedAsset {
  symbol: string; // 'usdc'
  name: string; // 'USD Coin'
  chainTypes: string[]; // chain ids accepted in strict mode, e.g. ['ethereum', …, 'stellar']
  requiresChainType: boolean; // true for usdt and usdc
}
```

### `getSupportedChains(): SupportedChain[]`

Every accepted `chainType`: canonical chain ids and their aliases.

```typescript
interface SupportedChain {
  id: string; // 'tron'
  aliases: string[]; // ['trx', 'trc20']
}
```

### Types

`ValidateAddressParams`, `SupportQuery`, `SupportedAsset`, and `SupportedChain` are exported for TypeScript projects.

## Chains and `chainType`

`chainType` names the chain an address belongs to. It is case-insensitive and accepts the chain id or any of its aliases, including chain tickers and token standards. The most common values:

| Chain | `chainType` values |
| --- | --- |
| Ethereum | `ethereum`, `eth`, `erc20` |
| BNB Smart Chain | `binancesmartchain`, `bsc`, `bep20`, `bnb`, `binance` |
| Polygon | `polygon`, `pol`, `matic` |
| Arbitrum | `arbitrum` |
| Optimism | `optimism` |
| Avalanche C-Chain | `avalanche`, `avax` |
| Base | `base` |
| Tron | `tron`, `trx`, `trc20` |
| Solana | `solana`, `sol`, `spl` |
| Stellar | `stellar`, `xlm` |
| TON | `toncoin`, `ton` |
| Bitcoin (Omni for USDT) | `bitcoin`, `btc`, `omni` |

Other chains include `cardano` (`ada`), `polkadot` (`dot`), `ripple` (`xrp`), `algorand` (`algo`), `hedera`, `aptos`, `tezos`, `litecoin` (`ltc`), `dogecoin` (`doge`), and `bitcoincash`. All EVM chains share one address format, so any EVM `chainType` validates `0x…` addresses.

The full list of chains, aliases, and which assets are accepted on which chains is in [Supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md) (the package carries the same list as `docs/supported-assets.md`), and at runtime from `getSupportedChains()` and `getSupportedAssets()`.

## Networks

`network: 'testnet'` validates testnet addresses instead of mainnet ones. How much that changes depends on the chain:

- **Network-aware** (mainnet and testnet addresses differ, and the wrong one returns `false`): the Bitcoin family (Bitcoin, Litecoin, Dogecoin, Bitcoin Cash, and others), Cardano, Monero, TON (test-only flag), Cronos, XRP X-addresses, and Hedera ids with a checksum suffix. Bitcoin testnet also accepts regtest `bcrt1…` addresses.
- **Network-agnostic** (the same address is valid on every network, so `network` has no effect): EVM chains, Solana, Tron, Stellar, XRP classic addresses, Polkadot, Algorand, Hedera ids without a checksum, Aptos, Tezos, Nano, and EOS.
- A few legacy coins define no testnet address types; on `testnet` they reject every address.

## Address formats worth knowing

- **EVM (`0x…`)**: mixed-case addresses must match their EIP-55 checksum. All-lowercase and all-uppercase addresses are valid but carry no checksum, so a typo in them cannot be detected. Prefer collecting checksummed addresses.
- **Bitcoin**: legacy (`1…`), P2SH (`3…`), SegWit (`bc1q…`) and Taproot (`bc1p…`) are all accepted. Bech32 addresses must be one case.
- **Bitcoin Cash**: CashAddr with or without the `bitcoincash:` prefix, and legacy addresses.
- **Litecoin**: `L…`, `M…` and `ltc1…`. Legacy `3…` P2SH addresses are rejected, because they cannot be told apart from Bitcoin P2SH addresses.
- **XRP**: classic `r…` addresses and X-addresses (`X…` mainnet, `T…` testnet).
- **Stellar**: `G…` accounts and `M…` muxed accounts.
- **TON**: friendly form (`EQ…`, `UQ…`; `kQ…`, `0Q…` on testnet) and raw form (`0:<hex>`).
- **Hedera**: `0.0.12345`, `0.0.12345-abcde` (HIP-15 checksum), or a `0x…` EVM alias.
- **Polkadot**: Polkadot (`1…`) and generic Substrate (`5…`) formats. Other networks' formats, such as Kusama, are rejected.
- **Aptos**: the full 64-hex-digit form. Short forms such as `0x1` are framework addresses and are rejected.
- **No checksum on some formats.** Solana addresses, Aptos addresses, EOS account names, Hedera ids without a checksum suffix, TON raw-form addresses, and all-lowercase EVM addresses have no checksum. The validator checks their shape, but a mistyped character usually still produces a well-formed address. Consider confirming these with the user, for example by showing the start and end of the address.

## Memos and destination tags

Some chains route a deposit to the right customer with a value sent alongside the address: an XRP destination tag, a Stellar memo, an EOS or Hedera memo, a TON comment. Exchanges and custodians often require it, and a transfer without it can be lost or delayed.

This library validates the address only. If you send to such an account, collect and check the memo or tag separately. Two formats carry it inside the address and are validated here: XRP X-addresses (destination tag) and Stellar muxed accounts (account id).

## Compatibility

| Environment | Supported |
| --- | --- |
| Node.js | 18 and later |
| Browsers | Current evergreen browsers (ES2020 with `BigInt`) |
| React Native | 0.74 and later with Hermes (needs `BigInt` and `TextEncoder`) |
| Bundlers | Vite, webpack, Rollup, esbuild, Metro; `package.json` `exports` with a `main`/`module` fallback |
| Modules | ESM and CommonJS |
| TypeScript | Declarations for both ESM and CommonJS consumers, including `moduleResolution` `node16`/`nodenext` and `bundler` |

- **Zero runtime dependencies.** The cryptographic primitives ([`@noble/hashes`](https://github.com/paulmillr/noble-hashes) and [`@scure/base`](https://github.com/paulmillr/scure-base)) are bundled in; their license notices ship in the package's `NOTICE` file.
- **About 22 KB** minified and gzipped, all assets included. The package is marked side-effect free.
- **No network or filesystem access**, no native modules, no Node built-ins or polyfills.

## Versioning

Releases follow [semantic versioning](https://semver.org): new assets, chains, and options are minor releases, fixes are patch releases, and any breaking change gets a new major version. Install the stable releases, which is what `npm install @coinme/wallet-address-validator` resolves to.

## Verify your integration

The package needs no environment, so the same checks hold in development and production. With the addresses from the [Quickstart](#quickstart):

1. Check that `validateAddress({ address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', currency: 'btc' })` returns `true`, and that `'not-an-address'` returns `false`.
2. Check that the USDC address on Stellar returns `true` with `chainType: 'stellar'` and `strict: true`, and that the same call with `chainType: 'tron'`, or with no `chainType`, throws `UnsupportedChainError`.
3. Type the address into your field with a space before or after it, and check that your code trims it before validating.
4. Check that a currency the package does not support, such as `'xyz'` with `strict: true`, throws `UnsupportedCurrencyError`, and that your screen does not let the user send to that address.
5. In a React Native app, run these checks on a device or simulator with Hermes, on both platforms you ship.

## Security

Report a suspected vulnerability privately to your Coinme integration contact, not in a public issue, and do not share details publicly until a fix is released. Include the package version, the exact `validateAddress` call (address, currency, chainType, network, strict), the result you got and the result you expected. Coinme treats these as security issues: an address that `validateAddress` accepts although it is not valid for the given currency, chain or network (a false accept); input that makes `validateAddress` hang, crash or consume excessive CPU or memory; and anything in the published package that performs I/O, executes remote code or leaks data. Security fixes are released for the latest minor version of the current major version, so stay on the latest release.

## Commonly asked questions

### Does a valid result mean it is safe to send to the address?

No. `true` means the address is well-formed for the asset and chain. The package makes no network requests, so it cannot tell whether the address exists, who controls it or whether it belongs to a sanctioned party. Keep your own ownership, allow-list and screening controls; see [What it does not check](#what-it-does-not-check).

### Does it call Coinme or need Coinme credentials?

No. It runs entirely in your app, offline, and talks to no Coinme service. The only credential is the registry token that installs it.

### Which integration is it for?

Both. With the Coinme Widget, check an address your app collects before you pass it to the widget as `walletAddress` (and lock it with `walletAddressLock`); see the [field table on Build](https://platformdocs.coinme.com/pages/build/index.md#config). With Coinme-as-a-Service, check the send or withdrawal addresses your own screens collect before your backend uses them.

### How do I validate a USDC or USDT address?

Pass the chain the address is on as `chainType`, with `strict: true`, for example `{ address, currency: 'usdc', chainType: 'stellar', strict: true }`. Strict mode requires `chainType` for `usdc` and `usdt`, because their address format depends on the chain, and throws `UnsupportedChainError` without it.

### Can I validate on every keystroke?

Yes. `validateAddress` does no I/O and is fast, and oversized or malformed input returns `false` quickly.

### Which assets and chains are supported?

Every one is listed in [Supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md), and at runtime by `getSupportedAssets()` and `getSupportedChains()`. To fail fast when your own asset configuration names something the package cannot validate, check each pair with `isSupported` at startup.

## Troubleshooting

**`validateAddress` returns `false` for an address that looks right.** The input has leading or trailing whitespace (trim it first), is a payment URI such as `bitcoin:…?amount=…` (strip it to the address), is a testnet address validated without `network: 'testnet'` on a network-aware chain, or is in a format the chain rejects: a mixed-case EVM address whose EIP-55 checksum does not match, a mixed-case bech32 address, a Litecoin `3…` address, a short Aptos address such as `0x1`, or a Kusama address for Polkadot. See [Address formats worth knowing](#address-formats-worth-knowing).

**It throws `UnsupportedChainError`.** In strict mode, `chainType` is missing for a multi-chain asset (`usdt`, `usdc`), unrecognized, or names a chain that does not use the currency's address format, such as `btc` on `ethereum`. Check the value against [Chains and `chainType`](#chains-and-chaintype).

**It throws `UnsupportedCurrencyError`.** The package does not support the currency. Check it with `isSupported` or `getSupportedAssets()`, and do not let the user send to an address it could not validate.

**It throws `TypeError`.** `network` is neither `'mainnet'` nor `'testnet'`.

**It fails to load in React Native.** The package needs `BigInt` and `TextEncoder`: React Native 0.74 or later with Hermes.
