Skip to main content

Onboard users

What's a game without players? Blockchain games need to connect to users' blockchain wallets in order to authenticate them and facilitate transactions.

onboard usersonboard users

User wallets

Having a wallet is essential for users in the Web3 world. It enables secure management of cryptocurrencies, NFTs, and decentralized applications, allowing users to do various things like make transactions and own unique digital assets.

There are two key wallets that you can recommend to your users that provide optimal compatibilty with Immutable applications:

Immutable Passport

Immutable Passport is a non-custodial wallet and authentication solution that streamlines user onboarding through passwordless sign-on and automated wallet creation.

Passport offers battle-tested security, frictionless gameplay, persistent identity across Web3 games, and a consistent configuration across all applications. As Immutable Passport is web-based, no browser extensions or downloads are required. For users of Immutable Passport, creating a wallet is as simple as logging in.


MetaMask is a popular and trusted option that provides a seamless and user-friendly experience, making it easy to interact with decentralized applications on various blockchain networks (including Ethereum and Immutable zkEVM). It also has robust security features and ensures the privacy of sensitive data enabling the secure storage, sending and receiving of digital assets such as cryptocurrencies and NFTs. With its browser extension and mobile app versions, it is extremely versatile for a variety of use-cases.

For information on how to create and set up a MetaMask wallet, please see our Set up your blockchain wallet guide.

Authenticate users

Immutable provides Immutable Passport, which is a blockchain-based identity and wallet system that caters to the needs of Web3 games. It offers a persistent identity that accompanies users across Web3 games, ensuring a consistent configuration across all applications.


1. Initialise the provider

💡Passport provider implements EIP-1193 standard

Passport's zkEVM provider implements the Ethereum EIP-1193 standard, which means that you can use the same logic to interact with a user's Passport wallet as you would with any other Ethereum wallet.

As it implements the EIP-1193 standard, you can create a Passport provider and call a range of RPC methods on it directly. Alternatively, you can use the Passport provider in an Ethers.js provider.

Create the Passport provider:

const passportProvider = passport.connectEvm();

Once a provider is created, you can call various methods on it via the request function (which is protocol-agnostic), for example:

const accounts = await provider.request({ method: "eth_requestAccounts" });

See the full range of supported RPC methods.

2. Trigger the login process

The login flow is triggered by calling the requestAccounts RPC on the Passport provider:

If you are using an EIP-1193 provider directly, then you can call the requestAccounts method directly:

const provider = passport.connectEvm();
const accounts = await provider.request({ method: "eth_requestAccounts" });

Once the requestAccounts RPC method has been called, the Passport module will begin the authentication process. If the user successfully authenticates, then the user will be redirected to the Redirect URI that was set in the OIDC Configuration.

3. Configure the login callback

At this point, the route that handles requests to the Redirect URI will need to call the loginCallback method on page load. Your specific implementation will vary based on your application's architecture, but a vanilla Javascript implementation may look as follows:

window.addEventListener('load', function() {

The loginCallback method will then process the response from the Immutable's auth domain, store the authenticated user in session storage and close the pop-up. Once the authentication flow is complete, the Promise returned from requestAccounts will also resolve with a single-item array containing the user's address.

Next steps

Learn how to:

Connect to user wallets

Immutable provides Checkout, which enables applications to connect to user wallets. When you integrate Checkout in your application, you can trigger a widget that a user can easily connect their blockchain wallet to your game with.

Integrate Connect Widget

The Connect widget is a drop-in solution for web-based games and marketplaces that offers users a friendly wallet interface, simplifying the process of linking their wallets and integrating onto the Immutable zkEVM network.

💡Supported wallets
The Connect widget supports Metamask and Immutable Passport. However to support Passport as a wallet option you must integrate your application with Passport. Then follow our Passport integration docs.

connect widgetconnect widget
// Import the checkoutWidgets module from the Immutable SDK package
import { checkoutWidgets } from '@imtbl/sdk';

// Add the Connect component to your web application
<checkoutWidgets.ConnectReact />;

To learn more about this widget explore the Connect Widget documentation.