EVM Wallets

This guide will walk you through the process of integrating EVM Wallets into your Para Modal and Para-enabled application, allowing you to onboard new users and connect with existing users who may already have external wallets like MetaMask, Coinbase Wallet and more.

The ParaEvmProvider is built with wagmi and @tanstack/react-query to provide a seamless experience for integrating EVM wallets into your application in tandem to the Para Embedded Wallets.You can use all of the wagmi hooks and functionality in your application, including the useAccount, useConnect, and useDisconnect hooks. For more details on using the wagmi hooks, refer to the latest wagmi documentation on their website.

Prerequisites

Before integrating wallet connections, ensure you have an existing Para project with the Para Modal set up. If you haven’t set up Para yet, follow one of our Framework Setup guides like this React + NextJS guide.

Setting up EVM Wallets

Setup is simple - just wrap your app in a provider and pass the appropriate props and configuration options to the provider. Once configured, the Para modal and wallet options will automatically appear in the modal when opened. Para provides seamless integration with popular EVM wallets including MetaMask, Rainbow, Coinbase Wallet, WalletConnect, Zerion, Safe, Rabby, and OKX.

Safe App Registration: To use Safe as an external wallet, you’ll need to register your application as a Safe App in the Safe App Registry. This is required because Safe apps need to run within Safe’s context to ensure proper security and functionality. The registration process involves providing your app’s details and undergoing a review by the Safe team.

Install dependencies

Install the required packages alongside your existing Para dependencies:

npm install @getpara/evm-wallet-connectors @tanstack/react-query wagmi

Import components

Import the wallet connectors and supporting components you need. Adjust the imports based on which wallets you want to support:

main.tsx

import {
  ParaEvmProvider,
  coinbaseWallet,
  metaMaskWallet,
  rabbyWallet,
  rainbowWallet,
  walletConnectWallet,
  zerionWallet,
  safeWallet,
} from "@getpara/evm-wallet-connectors";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { sepolia } from "wagmi/chains";

Configure the providers

Configure the ParaEvmProvider component by wrapping your application content in the QueryClientProvider and ParaEvmProvider components. Pass in the required configuration props:

Add the `ParaEvmProvider to your providers component from the Para setup guide.

main.tsx

const queryClient = new QueryClient();

export const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <ParaEvmProvider
        config={{
          projectId: "your_wallet_connect_project_id",
          appName: "your_app_name",
          chains: [mainnet, polygon, sepolia, celo],
          wallets: [metaMaskWallet, rainbowWallet, walletConnectWallet, zerionWallet, coinbaseWallet],
          para: para, // Your para client instance
        }}>
        {/* Your app content and existing ParaModal */}
      </ParaEvmProvider>
    </QueryClientProvider>
  );
};

Provider Configuration

config

object

required

Show properties

projectId

string

required

Your WalletConnect project ID for wallet connections. If not using WalletConnect, you can use an empty string.

appName

string

required

The name of your application displayed in wallet connection prompts

chains

Chain[]

required

Array of supported EVM chains from wagmi/chains (e.g., mainnet, polygon, sepolia)

wallets

WalletConnector[]

required

Array of enabled wallet connectors from @getpara/evm-wallet-connectors

para

ParaClient

required

Your initialized Para client instance

WalletConnect (Reown) Setup: You’ll need a WalletConnect project ID if you’re using their connector. Get one from theWalletConnect (Reown) Developer Portal. You can use an empty string for testing, but this isn’t recommended for production.

The ParaEvmProvider extends Wagmi’s provider functionality, giving you access to all Wagmi Hooksin your application. Place the provider near the root of your component tree for optimal performance.

Advanced Provider Pattern

Setting up a dedicated provider component that encapsulates all the necessary providers and modal state management is considered a best practice. This pattern makes it easier to manage the modal state globally and handle session management throughout your application.

Creating a Custom Provider

A custom provider component can be created to encapsulate the ParaEvmProvider and ParaModal, allowing for easier management of the modal state and wallet connections. An example implementation is shown below:

Web3Provider.tsx

const Web3Context = createContext({
  openModal: () => {},
  closeModal: () => {},
  isOpen: false
});

export const useWeb3Modal = () => useContext(Web3Context);

export const Web3Provider = ({ children, config }) => {
  const [isOpen, setIsOpen] = useState(false);
  const queryClient = new QueryClient();

  const openModal = () => setIsOpen(true);
  const closeModal = () => setIsOpen(false);

  return (
    <Web3Context.Provider value={{ openModal, closeModal, isOpen }}>
      <QueryClientProvider client={queryClient}>
        <ParaEvmProvider config={
          {
            projectId: "your_wallet_connect_project_id",
            appName: "your_app_name",
            chains: [mainnet, polygon],
            wallets: [metaMaskWallet, rainbowWallet],
            para: para,
          };
        }>
          <ParaModal isOpen={isOpen} onClose={closeModal} />
          {children}
        </ParaEvmProvider>
      </QueryClientProvider>
    </Web3Context.Provider>
  );
};

Server-Side Rendering Considerations

When using Next.js or other SSR frameworks, proper client-side initialization is crucial since web3 functionality relies on browser APIs. There are two main approaches:

Using the 'use client' directive in Next.js 13+:
- Add the directive at the component level where browser APIs are needed. If using a custom provider, add the directive to the top of the provider file.
- Ensures the Web3Provider component and its dependencies only run on the client side
Using dynamic imports:
- In Next.js, use the dynamic function to import the provider component with { ssr: false }.
- Lazily loads the provider component
- Automatically handles client-side only code
- Provides fallback options during loading

After setting up your providers you need to configure the ParaModal component to display the external wallets and authentication options to your users. You need to pass in the externalWallets and authLayout configuration options to the ParaModal component to control which of the wallets show in the modal that were specified in the provider configuration. Optionally, you can pass the createLinkedEmbeddedForExternalWallets prop to include full Para authentication for specific wallets. This will add a signature verification step for these wallets and will setup a full Para account for the user, including creating Para wallets according to your APi key settings.

Set the modal props

<ParaModal
 externalWallets={[ExternalWallet.METAMASK, ExternalWallet.ZERION,...]}
 createLinkedEmbeddedForExternalWallets={[ExternalWallet.METAMASK, ExternalWallet.ZERION,...]}
 authLayout={["AUTH_FULL","EXTERNAL_FULL"]}
 theme={{
   mode: "light",
   foregroundColor: "#000000",
   backgroundColor: "#FFFFFF",
   accentColor: "#007AFF"
 }}
 logo={yourLogoUrl}
 appName="Your App Name"
 para={para}
/>

Modal prop options for customizing the Para Modal are included below. For advanced customization options, refer toCustomization Guide.

Show props

externalWallets

ExternalWallet[]

required

Array of supported external wallets to display in the modal

authLayout

AuthLayout[]

required

Defines the authentication layout style for social login and external wallets. Options are AUTH_FULL, EXTERNAL_FULL, AUTH_CONDENSED, and EXTERNAL_CONDENSED. Test the layout options in our Modal Designer

createLinkedEmbeddedForExternalWallets

ExternalWallet[]

Which external wallets to include full Para authentication for

theme

object

Show properties

mode

'light' | 'dark'

Color mode for the modal

foregroundColor

string

Primary text and content color (hex format)

backgroundColor

string

Modal background color (hex format)

accentColor

string

Highlight and button colors (hex format)

logo

string

URL for your application logo

appName

string

Your application name displayed in the modal

para

ParaClient

required

Your initialized Para client instance

oAuthMethods

OAuthMethod[]

Array of supported OAuth authentication methods

Disable email-based authentication

Disable phone-based authentication

recoverySecretStepEnabled

boolean

Enable the recovery secret step in the flow

onRampTestMode

boolean

Enable test mode for on-ramp features

Connection Only Wallets

Connection only external wallets bypass all Para functionality (account creation, user tracking, etc.) when connecting an external wallet. To enable this, set the following option on your Para instance:

{
  externalWalletConnectionOnly: true,
  ...restOfYourOptions
}

Since connection only wallets bypass Para, most Para functionality will be unavailable. This includes full Para auth with external wallets, on & off ramping, etc.

Examples

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

Modal Designer

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

For an example code implementation using EVM Wallets, check out our GitHub repository:

GitHub Repository

View an example implementation of the Para Modal with EVM Wallets in a React application.

Next Steps

Now that you have integrated EVM wallets into your Para Modal, you can explore more advanced features like signing using the Para SDK with popular libraries like Ethers.js.

EVM Integrations

Learn how to integrate the Para SDK with popular EVM libraries like Ethers.js and Wagmi.

Introduction

Setup

Guides

API & Troubleshooting

Prerequisites

Setting up EVM Wallets

Provider Configuration

Advanced Provider Pattern

Creating a Custom Provider

Server-Side Rendering Considerations

Connection Only Wallets

Examples

Modal Designer

GitHub Repository

Next Steps

EVM Integrations

Introduction

Setup

Guides

API & Troubleshooting

​Prerequisites

​Setting up EVM Wallets

​Provider Configuration

​Advanced Provider Pattern

​Creating a Custom Provider

​Server-Side Rendering Considerations

​Configuring the Para Modal

​Modal Props Config

​Connection Only Wallets

​Examples

Modal Designer

GitHub Repository

​Next Steps

EVM Integrations

Prerequisites

Setting up EVM Wallets

Provider Configuration

Advanced Provider Pattern

Creating a Custom Provider

Server-Side Rendering Considerations

Configuring the Para Modal

Modal Props Config

Connection Only Wallets

Examples

Next Steps