> For the complete documentation index, see [llms.txt](/llms.txt).

# Embedded Wallets SDK for iOS

## Overview[​](#overview "Direct link to 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[​](#prerequisites "Direct link to Prerequisites")

- iOS 14+
- Xcode 12+
- Swift 5.x
- A project configured on the [Embedded Wallets dashboard](https://developer.metamask.io/). See the [dashboard setup](/embedded-wallets/dashboard/) guide for details.

## Installation[​](#installation "Direct link to Installation")

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

### Swift package manager[​](#swift-package-manager "Direct link to 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[​](#cocoapods "Direct link to 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[​](#configure-redirection "Direct link to Configure redirection")

To use Embedded Wallets for iOS, allowlist your `bundleId` in your Embedded Wallets project.

- Go to the [Embedded Wallets developer dashboard](https://developer.metamask.io) 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[​](#initialize-embedded-wallets "Direct link to 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[​](#create-and-initialize-an-embedded-wallets-instance "Direct link to 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[​](#advanced-configuration "Direct link to Advanced configuration")

The Embedded Wallets iOS SDK supports several advanced configuration options:

- **[Custom authentication](/embedded-wallets/sdk/ios/advanced/custom-authentication/):** Define authentication methods.
- **[Whitelabeling and UI customization](/embedded-wallets/sdk/ios/advanced/whitelabel/):** Personalize the modal's appearance.
- **[Multi-Factor Authentication (MFA)](/embedded-wallets/sdk/ios/advanced/mfa/):** Set up and manage MFA.
- **[Dapp share](/embedded-wallets/sdk/ios/advanced/dapp-share/):** Share dapp sessions across devices.

tip

See the [advanced configuration sections](/embedded-wallets/sdk/ios/advanced/) to learn more about each configuration option.

- Basic Configuration
- Advanced Configuration

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

```

```
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "<YOUR_CLIENT_ID>",
        web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
        redirectUrl: "<YOUR_BUNDLE_ID>://auth",
        authConnectionConfig: [
            AuthConnectionConfig(
                authConnectionId: "<YOUR_AUTH_CONNECTION_ID>", // From the Embedded Wallets dashboard
                authConnection: .GOOGLE,
                clientId: "YOUR_GOOGLE_CLIENT_ID"
            )
        ],
        mfaSettings: MfaSettings(
            deviceShareFactor: MfaSetting(enable: true, priority: 1),
            backUpShareFactor: MfaSetting(enable: true, priority: 2),
            socialBackupFactor: MfaSetting(enable: true, priority: 3),
            passwordFactor: MfaSetting(enable: true, priority: 4)
        )
    )
)

```

## Single-factor authentication (SFA) support[​](#single-factor-authentication-sfa-support "Direct link to 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[​](#blockchain-integration "Direct link to Blockchain integration")

Embedded Wallets supports any blockchain network, with built-in support for **Ethereum** and **Solana**.

### Ethereum integration[​](#ethereum-integration "Direct link to 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[​](#solana-integration "Direct link to 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)

```