Wallet Address Import

Reusable MetaMask multichain wallet address import for browser dapps. Read-only EVM + Solana account discovery with a confirm-before-save React flow.

import { importAccountsFromBrowserWallet } from "@tgoliveira/wallet-address-import";

const accounts = await importAccountsFromBrowserWallet({
  dapp: { name: "My App", url: window.location.origin },
});

Integrating with an AI agent? Read AGENTS.md first.

Why

Apps that track wallets (vaults, monitors, dashboards) need a consistent way to import addresses from MetaMask. This package centralizes multichain connect, CAIP-10 normalization, nickname hints, and a review UI — without coupling to any one product's storage layer.

Features

• Read-only — requests account addresses only; no transactions or approvals.
• Multichain first — MetaMask Connect for EVM + Solana in one prompt when supported.
• EVM fallback — eth_requestAccounts for other injected wallets.
• Consumer-owned persistence — onConfirm receives { address, label }[].
• Themable React UI — labels and class names are overridable.

Quick start

Headless

npm i @tgoliveira/wallet-address-import

import { importAccountsFromBrowserWallet } from "@tgoliveira/wallet-address-import";

const accounts = await importAccountsFromBrowserWallet({
  dapp: { name: "My App", url: window.location.origin },
});

React

npm i @tgoliveira/wallet-address-import react

import { WalletAddressImporter } from "@tgoliveira/wallet-address-import/react";

<WalletAddressImporter
  importConfig={{ dapp: { name: "My App", url: window.location.origin } }}
  readExistingLabel={(address) => savedLabels[address]}
  onConfirm={async (entries) => {
    await saveAddresses(entries);
  }}
  metamaskIconSrc="/wallets/metamask.svg"
/>

Documentation

| Doc | Description | |-----|-------------| | AGENTS.md | AI agent integration guide | | docs/contributing.md | Branch, PR, changelog workflow | | docs/publishing.md | Manual npm release process | | docs/CURRENT_PRODUCT_SURFACE.md | Published exports and API surface |

License

MIT — see LICENSE.