For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Embedded Wallets SDK for iOS

Overview​

The MetaMask Embedded Wallets SDK for iOS (formerly Web3Auth Plug and Play) supports social sign-ins, external wallets, and native authentication state management. The SDK is written in Swift.

Prerequisites​

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. Xcode automatically resolves and downloads 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, allowlist your bundleId in your Embedded Wallets project.

  • Go to the Embedded Wallets developer dashboard and create or open an existing 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 initialization pattern. The constructor fetches project configuration and restores any active session automatically. The SDK does not require a 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_CLIENT_ID>", // From the Embedded Wallets dashboard
                    web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
                    redirectUrl: "<YOUR_BUNDLE_ID>://auth"
                )
            )

            // Check for an active session
            if web3Auth?.web3AuthResponse != nil {
                // User is already signed 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 supports several advanced configuration options:

tip

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

web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "<YOUR_CLIENT_ID>",
        web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
        redirectUrl: "<YOUR_BUNDLE_ID>://auth"
    )
)

Single-factor authentication (SFA) support​

The iOS SDK supports single-factor authentication (SFA), which authenticates users directly with a JWT token from your own authentication system. When MFA is disabled, users sign in using only the JWT token.

// SFA sign-in 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 supports any blockchain network, with built-in support for Ethereum and Solana.

Ethereum integration​

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​

Get the Ed25519 private key using the getEd25519PrivateKey method and use it with SolanaSwift or 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