New: External Wallets
Learn how to seamlessly integrate external wallets into your Capsule-enabled application
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
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.
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.
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.
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
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.
import { backpackWallet, CapsuleSolanaProvider, glowWallet, phantomWallet } from '@usecapsule/solana-wallet-connectors';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { clusterApiUrl } from '@solana/web3.js';
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.
WalletAdapterNetwork.Devnet;
const endpoint = clusterApiUrl(solanaNetwork);
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.
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>
);
};
Combining EVM and Solana Providers
You can use both EVM and Solana providers together by wrapping them around each other:
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:
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:
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.
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
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.
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
A detailed description of the problem you’re encountering.
2
Any relevant error messages or logs.
3
Steps to reproduce the issue.
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?