This guide will walk you through the process of integrating external wallets into your Capsule-enabled application, allowing you to onboard new users and connect with existing users who may already have external wallets accross EVM and Solana networks.

​
Prerequisites

You primarily need an existing Capsule project setup. If you haven’t already set up Capsule, refer to the React & Web quick start guide to get started.

Note: If using our EVM wallet provider with WalletConnect you will need to create a WalletConnect project and obtain a project ID to set up external wallets. You can do so on their developer portal. Otherwise you can pass in an empty string to the projectId prop.

​
Quick Start

​
EVM Setup

Capsule integrates with a number of browser EVM wallets, including MetaMask, Rainbow, Coinbase Wallet, WalletConnect, Zerion, and Rabby.

1

Install dependencies

Install the following packages in addition to your current Capsule dependencies:

2

Import required components and wallets

To get started with external wallets, import all the wallets you will support in your application and the CapsuleEvmProvider component. The following example import includes all available wallets. You can adjust the wallets and chains as needed for your application.

main.tsx
  import {
    CapsuleEvmProvider,
    coinbaseWallet,
    metaMaskWallet,
    rabbyWallet,
    rainbowWallet,
    walletConnectWallet,
    zerionWallet,
  } from '@usecapsule/evm-wallet-connectors';
  import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
  import { sepolia, celo, mainnet, polygon } from 'wagmi/chains';

Ensure you’ve imported all necessary components and wallets for your specific integration needs. React Query is a prerequisite dependency.

3

Set up the CapsuleEvmProvider

With all the necessary imports in place, you can now set up the CapsuleEvmProvider component. First, create a new QueryClient instance, then wrap your application content in the QueryClientProvider and CapsuleEvmProvider components. It’s advised to wrap these as high up in your component tree as possible. Lastly, pass in a config object.

main.tsx
const queryClient = new QueryClient();

export const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <CapsuleEvmProvider
        config={{
          projectId: 'your_wallet_connect_project_id',
          appName: 'Your App Name',
          chains: [mainnet, polygon, sepolia, celo],
          wallets: [metaMaskWallet, rainbowWallet, walletConnectWallet, zerionWallet, coinbaseWallet],
          capsule: capsuleClient, // Your capsule client instance
        }}
      >
        {/* Your app content */}
      </CapsuleEvmProvider>
    </QueryClientProvider>
  );
};

CapsuleEvmProvider is built on top of Wagmi’s WagmiConfig and WagmiProvider. This means that all Wagmi hooks will function as expected, as long as this provider wraps your application. The config object you pass to CapsuleEvmProvider is a Wagmi config object extended with Capsule-specific configurations. This includes modified Wagmi wallet connectors to work seamlessly with Capsule.

At a minimum, ensure the following parameters are set in your config object:

  • projectId (the project ID for your wallet connectors)
  • appName (the name of your application)
  • chains (the list of EVM chains you want to support)
  • wallets (the wallet connectors you want to enable)
  • capsule (your Capsule client instance)

All other Wagmi configurations are also supported.

​
Solana Setup

Capsule integrates with Solana browser wallets Phantom, Glow, and Backpack.

1

Install dependencies

Install the following packages in addition to your current Capsule dependencies:

2

Import Solana components and wallets

Similar to the EVM setup, import the necessary components and wallets for Solana integration. The following example includes all available wallets. You can adjust the wallets as needed for your application.

main.tsx
import { backpackWallet, CapsuleSolanaProvider, glowWallet, phantomWallet } from '@usecapsule/solana-wallet-connectors';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { clusterApiUrl } from '@solana/web3.js';
3

Set up Solana network and endpoint

You’ll need to set up the Solana network and endpoint for your application. The following example sets up the Devnet network. You can adjust the network as needed for your application.

main.tsx
const solanaNetwork = WalletAdapterNetwork.Devnet;
const endpoint = clusterApiUrl(solanaNetwork);
4

Configure the CapsuleSolanaProvider

Now configure the CapsuleSolanaProvider component by wrapping your application content in the QueryClientProvider and CapsuleSolanaProvider components. Pass in the endpoint, wallets, chain, and app identity as props.

main.tsx
export const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <CapsuleSolanaProvider
        endpoint={endpoint}
        wallets={[glowWallet, phantomWallet, backpackWallet]}
        chain={solanaNetwork}
        appIdentity={{ name: 'Your App Name', uri: `${location.protocol}//${location.host}` }}
      >
        {/* Your app content */}
      </CapsuleSolanaProvider>
    </QueryClientProvider>
  );
};
Update the uri property in the appIdentity object to match your application’s URI.

​
Cosmos Setup

Capsule currently supports two Cosmos browser wallets, Keplr and Leap. The wallet integration makes use of a modified fork of the graz React library.

1

Install dependencies

Install the following packages in addition to your current Capsule dependencies:

2

Configure the CapsuleCosmosProvider

Configure the CapsuleSolanaProvider component by wrapping your application content in the QueryClientProvider and CapsuleCosmosProvider components. chain ID, available wallets, and available chains as props.

main.tsx
import { useState } from 'react';
import { CapsuleCosmosProvider, keplrWallet, leapWallet } from '@usecapsule/cosmos-wallet-connectors';
import { axelar, cosmoshub, osmosis, sommelier, stargaze } from '@usecapsule/graz/chains';
import { type ChainInfo } from 'keplr-wallet/types';

const cosmosChains: ChainInfo[] = [
  { ...cosmoshub, rpc: 'https://rpc.cosmos.directory/cosmoshub', rest: 'https://rest.cosmos.directory/cosmoshub' },
  { ...sommelier, rpc: 'https://rpc.cosmos.directory/sommelier', rest: 'https://rest.cosmos.directory/sommelier' },
  { ...stargaze, rpc: 'https://rpc.cosmos.directory/stargaze', rest: 'https://rest.cosmos.directory/stargaze' },
  { ...axelar, rpc: 'https://rpc.cosmos.directory/axelar', rest: 'https://rest.cosmos.directory/axelar' },
  { ...osmosis, rpc: 'https://rpc.cosmos.directory/osmosis', rest: 'https://rest.cosmos.directory/osmosis' },
];

export const App = () => {
  const [chainId, setChainId] = useState<string>(cosmoshub.chainId);

  return (
    <CapsuleCosmosProvider
      chains={cosmosChains}
      wallets={[keplrWallet, leapWallet]}
      selectedChainId={chainId}
      onSwitchChain={chainId => {
        setChainId(chainId);
      }}
      multiChain
      walletConnect={{ options: { projectId: '...' } }}
    >
      {/* Your app content */}
    </CapsuleCosmosProvider>
  );
};

The CapsuleCosmosProvider offers most of the same configuration props as the GrazProvider component from graz.

​
Combining Multiple Providers

You can use EVM, Solana, and Cosmos providers together by nesting them. Note that because of graz implementation details, CapsuleCosmosProvider must be the outermost component if present, and you will not need to wrap the providers in a QueryClientProvider.

main.tsx
// With Cosmos:
export const App = () => {
  return (
    <CapsuleCosmosProvider>
      <CapsuleEvmProvider>
        <CapsuleSolanaProvider>{/* Your app content */}</CapsuleSolanaProvider>
      </CapsuleEvmProvider>
    </CapsuleCosmosProvider>
  );
};

// Without Cosmos:
const myQueryClient = new QueryClient();

export const AppWithoutCosmos = () => {
  return (
    <QueryClientProvider client={myQueryClient}>
      <CapsuleEvmProvider>
        <CapsuleSolanaProvider>{/* Your app content */}</CapsuleSolanaProvider>
      </CapsuleEvmProvider>
    </QueryClientProvider>
  );
};

​
Configuring CapsuleModal

With the providers set up, you can now configure the CapsuleModal component to display external wallets. This configuration works for both EVM and Solana wallets:

app.tsx
import { ExternalWallet, AuthLayout } from "@usecapsule/evm-wallet-connectors";

const externalWallets = [
  ExternalWallet.METAMASK,
  ExternalWallet.ZERION,
  ExternalWallet.PHANTOM,
];
const authLayout = [AuthLayout.AUTH_FULL];

<CapsuleModal
  oAuthMethods={oAuthMethods}
  externalWallets={externalWallets}
  authLayout={authLayout}
  theme={{
    mode: "light",
    foregroundColor: "#000000",
    backgroundColor: "#FFFFFF",
    accentColor: "#007AFF",
  }}
  logo={yourLogoUrl}
  appName="Your App Name"
/>;

​
Customization

You can customize the appearance and behavior of the external wallet integration using various props on the CapsuleModal component:

​
externalWallets
ExternalWallet[]
required

An array of external wallet options to display. This determines which wallets will be supported and the order they will appear in the modal. This array should include the wallets you imported in the provider setup.

​
authLayout
AuthLayout[]
required

An array defining the layout of authentication options. This determines whether the auth options are displayed in an expanded or collapsed format. If you’d like to learn more about what each layout might look like check our our Modal Designer

​
theme
object

Theming options for the modal, including color mode, foreground color, background color, and accent color. You can learn more about theming capsule in the

UI & Theming

guide.

URL of your application’s logo to be displayed in the modal.

​
appName
string

The name of your application to display in the modal.

For more detailed customization options and advanced configurations:

Advanced Customization

Explore more ways to tailor the Capsule experience to your application's needs.

​
Examples

For an example of what the Capsule External Wallets Modal might look like in your application, check out our demo:

Demo

View a live demo of the Capsule External Wallets Modal in action.

​
Troubleshooting

For a more comprehensive list of solutions, visit our troubleshooting guide:

Troubleshooting

Our troubleshooting guide provides solutions to common integration and usage problems.

​
Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.

Was this page helpful?

Fiat On and Off-RampsCapsule Webinars and Talks