Skip to main content

Embedded Wallets SDK for iOS

Overview​

MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides a seamless authentication experience for iOS applications with social logins, external wallets, and more. Our iOS SDK, written in Swift, simplifies connecting users to their preferred wallets and manage authentication state natively.

Requirements​

  • iOS 14+
  • Xcode 12+
  • Swift 5.x
  • Basic knowledge of Swift and iOS Development

Prerequisites​

tip

See the dashboard setup guide to learn more.

Installation​

Install the Web3Auth iOS SDK using one of the following methods:

Swift package manager​

  1. In Xcode, with your app project open, navigate to File > Add Package Dependencies.

  2. When prompted, add the Web3Auth iOS SDK repository:

    https://github.com/Web3Auth/web3auth-swift-sdk

    From the Dependency Rule dropdown, select Exact Version and enter 12.0.1 as the version.

  3. When finished, Xcode will automatically begin resolving and downloading your dependencies in the background.

Cocoapods​

To install the Embedded Wallets SDK using Cocoapods, follow the steps:

  1. Open the Podfile, and add the Embedded Wallets pod:
pod 'Web3Auth', '~> 12.0.1'
  1. Once added, use pod install command to download the Embedded Wallets dependency.

Configure redirection​

To use Embedded Wallets for iOS you need to allowlist your bundleId in your Embedded Wallets project.

  • Go to Embedded Wallets developer dashboard, and create or open an existing Embedded Wallets project.
  • Allowlist {bundleId}://auth in the dashboard. This step is mandatory for the redirect to work.

Initialize Embedded Wallets​

The iOS SDK uses an async initializer. The constructor fetches project configuration and restores any active session automatically. There is no separate initialize() call.

Create and initialize an Embedded Wallets instance​

Import and configure Web3Auth in your application:

import Web3Auth

class ViewModel: ObservableObject {
    var web3Auth: Web3Auth?

    func setup() async {
        do {
            web3Auth = try await Web3Auth(
                options: Web3AuthOptions(
                    clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Web3Auth Dashboard
                    web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
                    redirectUrl: "com.yourapp.bundleid://auth"
                )
            )

            // Check for an active session
            if web3Auth?.web3AuthResponse != nil {
                // User is already logged in
            }
        } catch {
            print("Error initializing Web3Auth: \(error)")
        }
    }
}
note

The async constructor throws if the project configuration fetch fails or if a stored session token is invalid. Wrap it in do/catch and treat any error as a failed initialization rather than an absent session.

Advanced configuration​

The Embedded Wallets iOS SDK offers a rich set of advanced configuration options:

tip

See the advanced configuration sections to learn more about each configuration option.

web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
        redirectUrl: "com.yourapp.bundleid://auth"
    )
)

Single Factor Auth (SFA) support​

The iOS SDK includes built-in support for Single Factor Auth (SFA), allowing seamless authentication when you already have a JWT token from your own authentication system. When MFA is disabled, users are authenticated directly using your JWT token, making the login experience completely frictionless.

// SFA login with custom JWT
let result = try await web3Auth.connectTo(
    loginParams: LoginParams(
        authConnection: .CUSTOM,
        authConnectionId: "your-auth-connection-id",
        idToken: "your_jwt_token"
    )
)

SFA mode is activated automatically when you provide an idToken parameter.

Blockchain integration​

Embedded Wallets is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Embedded Wallets offers robust support for both Solana and Ethereum.

Ethereum integration​

For Ethereum integration, you can get the private key using the getPrivateKey method and use it with web3.swift or other Ethereum libraries:

import web3
import Web3Auth

// Use your Web3Auth instance to get the private key
let privateKey = web3Auth.getPrivateKey()

// Generate the Ethereum Account
let account = try EthereumAccount(privateKey)

// Get the address
let address = account.address

// Create a client
let client = EthereumHttpClient(
    // Please avoid using public RPC URL in production, use services like Infura.
    url: URL(string: rpcUrl)!,
    // Replace with the chain id of the network you want to connect to
    network: .custom(chainId)
)

// Get the balance
let balanceResponse = try await client.eth_getBalance(
    address: address,
    block: .Latest
)

// Convert the balance from Wei to Ether format
let balance = toEther(wei: balanceResponse)

Solana integration​

For Solana integration, you can get the Ed25519 private key using the getEd25519PrivateKey method and use it with SolanaSwift or any other Solana libraries:

import SolanaSwift

// Use your Web3Auth instance to get the private key
let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey()

// Generate the KeyPair
let keyPair = try KeyPair(secretKey: Data(hex: ed25519PrivateKey))

// Get the user account
let userAccount = keyPair.publicKey.base58EncodedString

// Create the JSONRPCAPIClient instance
let endpoint = APIEndPoint(
    address: "https://api.devnet.solana.com",
    network: .devnet
)
let solanaJSONRPCClient = JSONRPCAPIClient(endpoint: endpoint)

// Get the balance
let balanceResponse = try await solanaJSONRPCClient.getBalance(
    account: userAccount
)

// Solana's token decimals is set to be 9
let userBalance = balanceResponse.convertToBalance(decimals: 9)
On this page