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

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://docs.metamask.io/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:

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

Select Exact Version and enter 12.0.1.

CocoaPods

Add to your Podfile:

pod 'Web3Auth', '~> 12.0.1'

Then run pod install.

Allowlist {bundleId}://auth on the Embedded Wallets dashboard.

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 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:)

// 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:

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.

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 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:

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:

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:

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:

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 and 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
• Build with AI for ongoing integration help
• Release notes