> 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 initializer. 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)

```