Connecting Wallets

When a visitor connects a wallet, tell Lucia so their on-chain activity joins the same profile as their web sessions — that's what unifies web2 + web3 identity. This guide covers the three most common wallets — MetaMask, Phantom, and Coinbase Wallet — across the chains the SDK supports: EVM and Solana.

A lot of this is automatic

On init(), the SDK already detects an already-connected EVM or Solana wallet and sends it, and it listens for account changes (EVM accountsChanged, Solana connect) and sends those too. You still call sendWalletInfo explicitly in your connect flow to capture the first connection reliably — but returning, already-authorized wallets are picked up for you.

The method

LuciaSDK.sendWalletInfo(walletAddress, chainId, walletName);
// or, with the options object:
LuciaSDK.sendWalletInfo(walletAddress, { provider, providerRdns, connectorType, chainId });

The SDK de-duplicates per session, so calling it more than once for the same address is safe — it only sends the first time.

---

EVM chains (Ethereum, Base, Polygon, …)

MetaMask, Coinbase Wallet, and Phantom all expose the standard EIP-1193 window.ethereum provider, so one code path covers all three. After the user approves, read the address and chain and send them:

<button id="connect-evm">Connect wallet</button>
<script>
  async function connectEvm() {
    if (!window.ethereum) return alert('No EVM wallet found');

    const [address] = await window.ethereum.request({ method: 'eth_requestAccounts' });
    const chainId = parseInt(await window.ethereum.request({ method: 'eth_chainId' }), 16);

    // detectEvmProvider() names the wallet for you (MetaMask / Coinbase Wallet / Phantom / …)
    await LuciaSDK.sendWalletInfo(address, chainId, undefined);
  }
  document.getElementById('connect-evm').addEventListener('click', connectEvm);
</script>

• chainId comes back as a hex string (0x1), so convert it with parseInt(hex, 16) — Ethereum mainnet is 1, Base is 8453, Polygon is 137.
• The SDK recognizes which wallet it is from the provider flags (isMetaMask, isCoinbaseWallet, isPhantom), so you can pass undefined for the name — or set it explicitly if you prefer: sendWalletInfo(address, chainId, 'MetaMask').

Multiple extensions installed?

When a visitor has several EVM wallets, they can clash on window.ethereum. The SDK uses EIP-6963 to attribute each to the right wallet; detectEvmProvider() (exported from the package) returns the active wallet's name if you need it yourself.

---

Solana (Phantom)

Phantom injects window.phantom.solana (and window.solana). Connect, then send the public key. The SDK identifies Solana from the address and provider — it sends Solana wallets with the provider name and no EVM-style chainId, so use the options form:

<button id="connect-sol">Connect Phantom</button>
<script>
  async function connectSolana() {
    const provider = window.phantom?.solana ?? window.solana;
    if (!provider?.isPhantom) return alert('Phantom not found');

    const { publicKey } = await provider.connect();
    await LuciaSDK.sendWalletInfo(publicKey.toString(), { provider: 'Phantom' });
  }
  document.getElementById('connect-sol').addEventListener('click', connectSolana);
</script>

The SDK also auto-detects an already-connected Solana wallet on load and listens for Phantom's connect event, so returning users are captured without this handler. detectSolanaProvider() recognizes Phantom, Solflare, Backpack, Glow, and Coin98.

---

Wallet & chain coverage

Wallet	EVM	Solana
MetaMask	✅ window.ethereum	—
Phantom	✅ window.ethereum	✅ window.phantom.solana
Coinbase Wallet	✅ window.ethereum	—

✅ = auto-detected by the SDK, which also listens for account changes on both ecosystems.

Bitcoin and other chains

The SDK's wallet support is EVM and Solana today — those are the ecosystems it detects and attributes. Bitcoin and other non-EVM/non-Solana chains aren't currently supported.

---

Tie the wallet to a known user

If you also know who the person is (email or user ID), call userInfo so their web2 and web3 identities merge into one profile:

await LuciaSDK.sendWalletInfo(address, chainId);
await LuciaSDK.userInfo('jane@example.com', { wallet: address });

See How attribution works for how these signals resolve into a single customer, and the SDK API Reference for sendWalletInfo options and the exported detectEvmProvider / detectSolanaProvider helpers.