Cardano Connect with Wallet

This repository provides JavaScript/TypeScript helpers and React components that make it easy to connect Cardano wallets to dApps, on both desktop and mobile.

• core: framework-independent helpers and utilities (zero React dependency)
• react: ConnectWalletButton and ConnectWalletList components plus a useCardano hook

✨ Features

Feature	Description
CIP-8	Message signing
CIP-30	Web wallet bridge (connect, sign, submit)
CIP-45	P2P wallet connection via QR code (mobile ↔ desktop)
CIP-95	Governance extension
CIP-158	Mobile deep links: open the dApp inside the wallet's in-app browser

Supported Wallets

Desktop (browser extension) Eternl · Nami · Yoroi · Typhon · Flint · NuFi · Lace · GeroWallet · Vespr · Begin

Mobile (native app) Eternl · Vespr · Begin · Yoroi · Flint

Mobile wallets that implement CIP-158 (currently Eternl and Vespr) are opened via a web+cardano:// deep link so the wallet's in-app browser loads the dApp directly. For other mobile wallets the user is redirected to the App Store or Play Store if the app is not already installed.

🚀 Getting Started

React

npm i @cardano-foundation/cardano-connect-with-wallet

import { ConnectWalletButton } from '@cardano-foundation/cardano-connect-with-wallet';

// Desktop + mobile, CIP-158 deep links enabled by default
<ConnectWalletButton
  supportedWallets={['Eternl', 'Nami', 'Yoroi', 'Vespr']}
  onConnect={(walletName) => console.log('connected:', walletName)}
/>

// Opt out of CIP-158 deep links
<ConnectWalletButton cip158Enabled={false} />

For detailed prop documentation and live examples see the storybook playground and the react module.

Core (framework-independent)

npm i @cardano-foundation/cardano-connect-with-wallet-core

import { Wallet, generateCip158DeepLink, checkIsMobile } from '@cardano-foundation/cardano-connect-with-wallet-core';

// Generate a CIP-158 deep link for the current page
const deepLink = generateCip158DeepLink();
// → 'web+cardano://browse/v1?uri=https%3A%2F%2Fmy-dapp.io%2F...'

// Connect a wallet by name
await Wallet.connectToWallet('eternl', NetworkType.MAINNET);

Full API reference is available in the core module.

Adding a Wallet

Most of the work is in two files:

File	What to do
core/wallets.ts	Add a registry entry with all wallet metadata
core/walletIcons.ts	Add the fallback icon as a data: URI (optional but recommended)

No other file needs to change.

Steps

1. (Optional) Add your icon to core/walletIcons.ts

   Paste your icon as a base64-encoded data: URI and export it. Keeping icons in this file avoids cluttering the registry with large strings.

   export const myWalletIcon = `data:image/svg+xml;base64,...`;

   You can skip this step and inline the data URI directly in the registry entry instead, or leave the icon field blank and the library will fall back to the icon injected by the wallet extension itself (window.cardano[key].icon).

2. Add an entry to walletRegistry in core/wallets.ts:

   import { myWalletIcon } from './walletIcons';
   
   // inside walletRegistry:
   {
     // Required
     key: 'mywallet',          // must match window.cardano[key] (lowercase)
     displayName: 'My Wallet', // shown in the UI
   
     icon: myWalletIcon,       // from walletIcons.ts (or inline data URI, or omit)
   
     // Desktop browser extension
     chromeExtensionId: 'abcdefghijklmnopqrstuvwxyz012345',
     chromeExtensionName: 'my-wallet', // Chrome Web Store URL slug
   
     // Mobile app
     playStoreUrl: 'https://play.google.com/store/apps/details?id=com.mywallet',
     appStoreUrl:  'https://apps.apple.com/app/my-wallet/id000000000',
     hasCIP158Support: true,  // true if your app handles web+cardano:// deep links
   }

3. Open a pull request. The Chrome Store redirect, mobile deep links, and app store fallback all derive automatically from the registry entry.

Field reference

Field	Required	Description
key	yes	Lowercase key in window.cardano (e.g. "eternl")
displayName	yes	Human-readable wallet name shown in the UI
icon	no	Fallback icon as a data:image/...;base64,... URI; the injected window.cardano[key].icon is used when omitted
chromeExtensionId	no	Chrome Web Store extension ID
chromeExtensionName	no	URL path slug for the Chrome Web Store link
playStoreUrl	no	Google Play Store URL for the mobile app
appStoreUrl	no	Apple App Store URL for the mobile app
hasCIP158Support	no	true if the app handles web+cardano://browse/v1?uri=... deep links (CIP-158)
mobileDeepLinkPrefix	no	Custom deep-link prefix (legacy); the current page URL is percent-encoded and appended

How mobile deep links work

When a user on a mobile device taps a wallet button:

1. If the wallet extension is already injected (in-app browser), it connects directly.
2. If mobileDeepLinkPrefix is set, the user is redirected to that prefix with the current URL appended (used by Flint).
3. If hasCIP158Support: true and cip158Enabled is not set to false on the component, a web+cardano://browse/v1?uri=<encoded_url> deep link is fired. If the wallet app opens within 2.5 s the app store redirect is cancelled; otherwise the user is sent to the Play Store or App Store.
4. Otherwise the user is redirected straight to the Play Store or App Store.

💪 Contributing

Please have a look at our contributing infos to become familiar with our guidelines. There is also a short description for our development setup as we use Storybook for testing, playing around and for supporting the development process.