---
name: coinme-wallet-address-validator
description: "Check that a cryptocurrency wallet address is well-formed for its asset and chain before the app stores it or sends funds to it, using @coinme/wallet-address-validator: install from the private registry, call validateAddress in strict mode with chainType for multi-chain assets such as USDC and USDT, trim the input, treat valid, invalid and unsupported differently, and check the app's asset list with isSupported at startup. Offline and format-only, for browsers, Node.js and React Native, on both the Widget and the CaaS integrations. Use when asked to validate, check or verify a wallet, crypto or destination address, or to add the Coinme wallet address validator."
metadata:
  surface: "both"
  package: "@coinme/wallet-address-validator"
  version: "1.2.0"
---

# Wallet address validation with the wallet address validator

## When to use this skill

The human's app collects a cryptocurrency wallet address and should reject a malformed one before storing it or sending funds to it: a Widget partner whose own screen collects the destination wallet it pre-fills or locks in the widget (`walletAddress`, `walletAddressLock`), or a CaaS partner whose screens collect send or withdrawal addresses. The package runs in browsers, Node.js 18 or later and React Native 0.74 or later with Hermes. It checks format only: it cannot tell whether an address exists, who controls it or whether it belongs to a sanctioned party.

## Which integration this is

This skill works on **both integrations**, the Widget / Ramp integration and the Coinme-as-a-Service (CaaS) integration, because the package runs entirely in the human's app and uses no Coinme service or credential. With the Coinme Widget, use it where the human's own app collects a wallet address, for example before passing it to the widget as `walletAddress`; with CaaS, where the human's own screens collect a send or withdrawal address. It does not embed the widget or onboard anyone: for those, read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and use that integration's skills as well.

## What you will produce

An address check in the human's app that trims the input, calls `validateAddress` with `strict: true` and the asset's `chainType` wherever the asset lives on more than one chain, and treats the three outcomes differently: a valid address goes on to the human's own ownership and compliance checks, an invalid one shows a field error, and an unsupported asset or chain is logged as an integration issue and never lets the user send. Plus a startup check that every asset and chain the app offers passes `isSupported`.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `COINME_REGISTRY_TOKEN` | Read-only token for the private npm registry that serves @coinme/wallet-address-validator. | An environment variable read by a gitignored `.npmrc` or `.yarnrc.yml` entry at install time; CI reads it from a secret. Never in a committed file. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- The package talks to no Coinme service, so it needs no environment, base URL, `rampId`, `partnerKey`, embed allowlist or token at runtime. Do not ask for any of them or add them for this skill; the only credential is the registry token that installs it.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

`true` means well-formed for this asset and chain, not safe to send to. Keep the human's own controls (ownership checks, allow-lists, screening or a small test transfer) and never present a `true` as more than a format check. The package does not validate memos or destination tags; step 5 covers them.

Do not write a regular expression or another validator alongside it, and do not wrap `validateAddress` in a function that returns `true` when it throws: an unsupported asset must stay distinguishable from a valid address.

## Procedure

### 1. 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.

### 2. Wrap `validateAddress` for the address field

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.

### 3. Name the chain for each asset

Map each asset the app offers to the `chainType` of the network it sends on, and pass it on every call. In strict mode `usdt` and `usdc` throw without it, and a `chainType` that does not use the currency's address format throws rather than validating something else.

`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()`.

`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.

Every chain id, alias and asset is listed in [Supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md).

### 4. Check the asset list at startup

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)
```

Run `isSupported` with `strict: true` over every currency and `chainType` pair the app offers when it starts (or in a test), and fail loudly on a pair that returns `false`, so a configuration the package cannot validate is found before a user meets it.

### 5. Collect memos and destination tags separately

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).

## Verify

The package needs no environment, so the same checks hold in development and production. With the addresses from the [Quickstart](https://platformdocs.coinme.com/docs/wallet-address-validator.md#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.

### Reading the result

**Done when:** `isSupported` is true for every asset and chain the app offers, and known-good and known-bad addresses validate as expected.

**Stop and ask the human when** an asset the human needs is not supported in strict mode.

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## 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](https://platformdocs.coinme.com/docs/wallet-address-validator.md#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`](https://platformdocs.coinme.com/docs/wallet-address-validator.md#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.

## Reference
- [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md)
- [Wallet address validator: supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md)
- [Build: the CoinmeConfig fields, walletAddress among them](https://platformdocs.coinme.com/pages/build/index.md)
- [Build: the Library of SDKs and documents](https://platformdocs.coinme.com/pages/build/library.md)
