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

# iOS SDK v12 Migration Guide

This guide upgrades Embedded Wallets iOS SDK integrations from **v6 through v11** directly to **v12**.

If you're already on v11, focus on the [v12 changes](#v12-changes). For older versions, apply the sections below that match your current version, then complete the v12 updates.

## AI-assisted migration

For the best results, install the MetaMask Embedded Wallets **skill** and **MCP server** before you migrate. See [Build with AI](/embedded-wallets/build-with-ai/) for setup (`npx skills add web3auth/skill` and MCP at `https://mcp.web3auth.io`).

Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, Antigravity, or similar):

```txt
Migrate my MetaMask Embedded Wallets iOS (web3auth-swift-sdk) project to v12.

Before changing code:
1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference).
2. Read the migration guide: https://metamask-docs-git-docs-agent-wallet-s-66054a-consensys-ddffed67.vercel.app/embedded-wallets/migration-guides/ios/
3. Detect my current SDK version from Package.swift or Podfile and list which breaking changes apply.

Then migrate my codebase directly to v12:
- Update the Web3Auth dependency to 12.0.1 (Swift Package Manager or CocoaPods).
- Replace W3AInitParams with Web3AuthOptions (web3AuthNetwork: .SAPPHIRE_MAINNET or .SAPPHIRE_DEVNET).
- Replace login/W3ALoginParams with connectTo/LoginParams(authConnection:).
- Replace loginConfig with authConnectionConfig ([AuthConnectionConfig]).
- Replace getPrivKey/getEd25519PrivKey with getPrivateKey/getEd25519PrivateKey().
- Replace launchWalletServices(chainConfig:) with showWalletUI() and configure chains in Web3AuthOptions.
- Remove chainConfig from request(); configure chains at init instead.
- Do not change my Client ID or Sapphire network unless I ask; that would change wallet addresses.

After migrating, list every file you changed and any manual dashboard steps I still need to do.

```

tip

Use planning mode (where available) for the initial prompt. Review the plan before generating code; config mistakes can change wallet addresses in production.

## Install v12

### Swift Package Manager

In Xcode, go to **File > Add Package Dependencies** and add:

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

```

Select **Exact Version** and enter **12.0.1**.

### CocoaPods

Add to your `Podfile`:

```sh
pod 'Web3Auth', '~> 12.0.1'

```

Then run `pod install`.

Allowlist `{bundleId}://auth` on the [Embedded Wallets dashboard](https://developer.metamask.io).

## Breaking changes

Apply the sections below that match your current version. If you're already on v11, focus on the [v12 changes](#v12-changes).

### v12 changes

v12 introduces a cleaner API surface. Key renames:

| v11 and earlier                         | v12                                                    |
| --------------------------------------- | ------------------------------------------------------ |
| `W3AInitParams`                         | `Web3AuthOptions`                                      |
| `network: .sapphire_mainnet`            | `web3AuthNetwork: .SAPPHIRE_MAINNET`                   |
| `login(W3ALoginParams(loginProvider:))` | `connectTo(loginParams: LoginParams(authConnection:))` |
| `Web3AuthProvider` / `.JWT`             | `AuthConnection` / `.CUSTOM`                           |
| `loginConfig`                           | `authConnectionConfig`                                 |
| `web3Auth.state`                        | `web3Auth.web3AuthResponse`                            |
| `getPrivKey()`                          | `getPrivateKey()`                                      |
| `getEd25519PrivKey()`                   | `getEd25519PrivateKey()` (throws)                      |
| `launchWalletServices(chainConfig:)`    | `showWalletUI()`                                       |
| `request(chainConfig:...)`              | `request(method:requestParams:)`                       |

```swift
// v12 initialization
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        chains: [
            Chains(
                chainId: "0x89",
                rpcTarget: "https://rpc.ankr.com/polygon",
                displayName: "Polygon Mainnet"
            )
        ]
    )
)

// v12 login
let result = try await web3Auth.connectTo(
    loginParams: LoginParams(authConnection: .GOOGLE)
)

// v12 wallet services
try await web3Auth.showWalletUI()

```

Remove any `setResultUrl` / `onOpenURL` handlers; v12 uses `ASWebAuthenticationSession` internally.

### Network and init params (from v7)

Use Sapphire networks:

```swift
web3Auth = Web3Auth(W3AInitParams(
    clientId: "YOUR_WEB3AUTH_CLIENT_ID",
    network: .sapphire_mainnet, // or .sapphire_devnet
    redirectUrl: "com.yourapp.bundleid://auth",
))

```

`W3AInitParams` adds `buildEnv`, `mfaSettings`, and `sessionTime`. Configure MFA through `mfaSettings` instead of adapter-level options. See [MFA](/embedded-wallets/sdk/ios/advanced/mfa/).

### Whitelabel configuration (from v7)

`W3AWhiteLabelData` field names changed:

| v6 and earlier | v7 and later                           |
| -------------- | -------------------------------------- |
| `name`         | `appName`                              |
| `dark`         | `mode` (`.light`, `.dark`, or `.auto`) |

New optional fields include `appUrl` and `useLogoLoader`. Prefer [dashboard customization](/embedded-wallets/dashboard/customization/) for new projects.

If your app uses `web3.swift`, note that v7 updated the dependency to v1.6.0 with API changes in Ethereum client calls.

### Mandatory redirect URL (from v8.4)

`redirectUrl` is required in `W3AInitParams`:

```swift
redirectUrl: "com.yourapp.bundleid://auth"

```

### `launchWalletServices` signature (from v8.1 and v8.2)

From v8.1, move `chainConfig` out of `W3AInitParams` and into `launchWalletServices`. From v8.2, remove `loginParams`:

```swift
var chainConfig = ChainConfig(
    chainNamespace: ChainNamespace.eip155,
    chainId: "0x1",
    rpcTarget: "https://mainnet.infura.io/v3/<YOUR_KEY>",
    ticker: "ETH",
)

try await web3Auth?.launchWalletServices(chainConfig: chainConfig)

```

### `request` signature (from v8.3)

Remove `loginParams`. Pass `chainConfig`, method name, and request parameters:

```swift
var params = [Any]()
params.append("Hello, World!")
params.append("0x764dd67c0420b43a39ab337463d8995622f226a2")

var chainConfig = ChainConfig(
    chainNamespace: ChainNamespace.eip155,
    chainId: "0x1",
    rpcTarget: "https://mainnet.infura.io/v3/<YOUR_KEY>",
    ticker: "ETH",
)

let response = try await web3Auth?.request(
    chainConfig: chainConfig,
    method: "personal_sign",
    requestParams: params,
)

```

### v10 changes

`getSignResponse()` is removed. The `request()` method returns `SignResponse` directly:

```swift
let response = try await web3Auth?.request(
    chainConfig: chainConfig,
    method: "personal_sign",
    requestParams: params,
)

if response!.success {
    print(response!.result!)
} else {
    print(response!.error!)
}

```

v10 also adds support for Web3Auth Auth Service v9 and Wallet Services v3 (including swap in the prebuilt wallet UI).

## New APIs (non-breaking)

These APIs were added in intermediate versions. If you're upgrading from an older SDK, adopt the v10 signatures shown above.

| API                      | Added in | Purpose                                              |
| ------------------------ | -------- | ---------------------------------------------------- |
| `enableMFA()`            | v8       | Initiate MFA setup for logged-in users               |
| `launchWalletServices()` | v8       | Open the built-in wallet UI                          |
| `request()`              | v8       | Sign transactions with confirmation screens          |
| SMS Passwordless sign-in | v8.3     | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` |
| Farcaster sign-in        | v8.3     | `.Farcaster` sign-in provider                        |

See [Wallet Services](/embedded-wallets/sdk/ios/usage/showWalletUI/) and [MFA](/embedded-wallets/sdk/ios/advanced/mfa/) for usage details.

## Summary table

| Area              | Before v7                 | v7-v11                   | v12                         |
| ----------------- | ------------------------- | ------------------------ | --------------------------- |
| Network           | `.mainnet`, `.cyan`, etc. | Sapphire supported       | `.SAPPHIRE_MAINNET`         |
| Init params       | `W3AInitParams`           | `W3AInitParams`          | `Web3AuthOptions`           |
| Sign-in           | N/A                       | `login(W3ALoginParams)`  | `connectTo(LoginParams)`    |
| `redirectUrl`     | Optional                  | Mandatory (v8.4+)        | Mandatory                   |
| Whitelabel `name` | `name`                    | `appName`                | `appName`                   |
| Wallet UI         | N/A                       | `launchWalletServices`   | `showWalletUI()`            |
| `request`         | N/A                       | `chainConfig` parameter  | Chains in `Web3AuthOptions` |
| Sign result       | N/A                       | `getSignResponse()` (v9) | Return value of `request()` |

## Next steps

- [iOS SDK get started](/embedded-wallets/sdk/ios/)
- [Build with AI](/embedded-wallets/build-with-ai/) for ongoing integration help
- [Release notes](https://github.com/Web3Auth/web3auth-swift-sdk/releases)