Wallet Services configuration

The iOS SDK provides fine-grained control over the showWalletUI and request flows through the walletServicesConfig parameter in Web3AuthOptions. Customize how transaction confirmations display and tailor the wallet UI branding.

note

Wallet Services requires a paid plan. You can use this feature in sapphire_devnet at no cost. The minimum pricing plan to use this feature in a production environment is the Scale Plan.

WalletServicesConfig

Pass walletServicesConfig in Web3AuthOptions to configure how Wallet Services behave across your dapp.

Parameters

Parameter	Description
confirmationStrategy?	Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy. Default is .defaultStrategy. The dashboard setting overrides it; see the note below.
whiteLabel?	Whitelabel configuration for the Wallet Services UI. When provided, merged with the project-level whitelabel config. Accepts WhiteLabelData as a value.
enableKeyExport?	Whether users can export their private key from the Wallet Services UI. Accepts Bool as a value. Default is nil.

ConfirmationStrategy

ConfirmationStrategy controls the UI shown when a user needs to confirm a transaction or signature request.

caution

The confirmation modal setting in the dashboard's Wallet UI configuration takes precedence over the confirmationStrategy you pass in code. If the dashboard enables the confirmation modal, the SDK uses .modal. If the dashboard disables it, the SDK uses .autoApprove. The SDK uses your confirmationStrategy only when the dashboard doesn't set this option.

Value	Description
.defaultStrategy	Shows the default Web3Auth confirmation screen inside the wallet WebView. This is the default value.
.modal	Shows the confirmation request in a bottom sheet modal on top of your application, rather than navigating to a new full-screen WebView.
.popup	Shows the confirmation in a small popup window. Useful for minimal UI disruption.
.autoApprove	Approves requests without showing a confirmation screen.

Interface

public struct WalletServicesConfig: Codable {
    public init(
        confirmationStrategy: ConfirmationStrategy? = .defaultStrategy,
        whiteLabel: WhiteLabelData? = nil,
        enableKeyExport: Bool? = nil
    )
}

public enum ConfirmationStrategy: String, Codable {
    case popup = "popup"
    case modal = "modal"
    case autoApprove = "auto-approve"
    case defaultStrategy = "default"
}

Setup

Configure walletServicesConfig during SDK initialization. The user must be signed in before you call showWalletUI or request. Wallet Services use the chains configured in your dashboard, or the chains you pass in Web3AuthOptions if the dashboard response has no chains field. If neither is set, these methods throw an error.

The SDK also applies the Wallet UI settings from your dashboard (such as token, NFT, send, buy, and receive visibility) on top of the whiteLabel theme you pass here.

import Web3Auth

web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        redirectUrl: "com.yourapp.bundleid://auth",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        walletServicesConfig: WalletServicesConfig(
            confirmationStrategy: .modal,
            whiteLabel: WhiteLabelData(
                appName: "My App",
                theme: ["primary": "#0364FF"]
            )
        )
    )
)

Usage examples

Show Wallet UI

do {
    try await web3Auth.showWalletUI()
} catch {
    print(error.localizedDescription)
    // Handle error
}

Sign Personal Message

do {
    var params = [Any]()
    params.append("Hello, Web3Auth from iOS!")
    params.append(address) // User's EOA address

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

    if let response = response, response.success {
        print("Signature: \(response.result!)")
    }
} catch {
    print(error.localizedDescription)
    // Handle error
}

Sign Typed Data

do {
    let typedData = """
    {
        "types": {
            "EIP712Domain": [
                { "name": "name", "type": "string" }
            ],
            "Mail": [
                { "name": "contents", "type": "string" }
            ]
        },
        "primaryType": "Mail",
        "domain": { "name": "Ether Mail" },
        "message": { "contents": "Hello, Bob!" }
    }
    """

    var params = [Any]()
    params.append(address) // User's EOA address
    params.append(typedData)

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

    if let response = response, response.success {
        print("Signature: \(response.result!)")
    }
} catch {
    print(error.localizedDescription)
    // Handle error
}