> 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[​](#ai-assisted-migration "Direct link to 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): ``` 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-dependabot-npmandya-6c9ea4-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[​](#install-v12 "Direct link to Install v12") ### Swift Package Manager[​](#swift-package-manager "Direct link to 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[​](#cocoapods "Direct link to CocoaPods") Add to your `Podfile`: ``` pod 'Web3Auth', '~> 12.0.1' ``` Then run `pod install`. Allowlist `{bundleId}://auth` on the [Embedded Wallets dashboard](https://developer.metamask.io). ## Breaking changes[​](#breaking-changes "Direct link to 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-changes "Direct link to 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)[​](#network-and-init-params-from-v7 "Direct link to 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](/embedded-wallets/sdk/ios/advanced/mfa/). ### Whitelabel configuration (from v7)[​](#whitelabel-configuration-from-v7 "Direct link to 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)[​](#mandatory-redirect-url-from-v84 "Direct link to Mandatory redirect URL (from v8.4)") `redirectUrl` is required in `W3AInitParams`: ``` redirectUrl: "com.yourapp.bundleid://auth" ``` ### `launchWalletServices` signature (from v8.1 and v8.2)[​](#launchwalletservices-signature-from-v81-and-v82 "Direct link to launchwalletservices-signature-from-v81-and-v82") 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/", ticker: "ETH", ) try await web3Auth?.launchWalletServices(chainConfig: chainConfig) ``` ### `request` signature (from v8.3)[​](#request-signature-from-v83 "Direct link to request-signature-from-v83") 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/", ticker: "ETH", ) let response = try await web3Auth?.request( chainConfig: chainConfig, method: "personal_sign", requestParams: params, ) ``` ### v10 changes[​](#v10-changes "Direct link to 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)[​](#new-apis-non-breaking "Direct link to 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[​](#summary-table "Direct link to 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[​](#next-steps "Direct link to 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)