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: You’ll need to create a Wallet Connect project and obtain a project ID to set up external wallets. You can do so on their developer portal.

​
Dependency Installation

In addition to your existing Capsule web installations, install the following packages for EVM and Solana integration:

​
Quick Start

​
EVM Setup

1

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

2

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],
        }}
      >
        {/* Your app content */}
      </CapsuleEvmProvider>
    </QueryClientProvider>
  );
};

Adjust the config object to include the chains and wallets you want to support in your application. You can also add additional options like theme and logo to customize the appearance of the Capsule modal.

​
Solana Setup

1

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';
2

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);
3

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.

​
Combining EVM and Solana Providers

You can use both EVM and Solana providers together by wrapping them around each other:

main.tsx
export const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <CapsuleEvmProvider config={...}>
        <CapsuleSolanaProvider {...props}>
          {/* Your app content */}
        </CapsuleSolanaProvider>
      </CapsuleEvmProvider>
    </QueryClientProvider>
  );
};

The order of the providers doesn’t matter. You can wrap the CapsuleSolanaProvider inside the CapsuleEvmProvider or vice versa.

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

logo
string

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.

​
Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our support team for assistance. To help us serve you better, include the following information in your support 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-RampsCapsule Webinars and Talks