Supported Wallets

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/frol/near-connect-ios/llms.txt

Use this file to discover all available pages before exploring further.

​

Wallet Compatibility

​

Wallet Types

​

Web Wallets

1. When the user selects a web wallet from the selector, near-connect calls window.open() to create a popup
2. NEAR Connect iOS intercepts this and creates a new WKWebView popup
3. The popup loads the wallet’s web interface
4. After authentication or transaction approval, the wallet redirects back to the bridge page with result data
5. The popup is automatically closed and removed

func webView(
    _ webView: WKWebView,
    createWebViewWith configuration: WKWebViewConfiguration,
    for navigationAction: WKNavigationAction,
    windowFeatures: WKWindowFeatures
) -> WKWebView? {
    // Override the data store to enable cookies (required by Cloudflare-protected wallets)
    configuration.websiteDataStore = .default()
    
    let popup = WKWebView(frame: webView.bounds, configuration: configuration)
    popup.navigationDelegate = self
    popup.uiDelegate = self
    popup.backgroundColor = .systemBackground
    popup.customUserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) ..."
    
    manager.bridgeWebView.addSubview(popup)
    popupWebViews.append(popup)
    return popup
}

• No app installation required
• Works immediately on any device
• Wallet updates don’t require app updates
• Universal compatibility across platforms

• Requires internet connection
• May be subject to Cloudflare or other web protections
• User must trust the in-app browser environment

​

Native App Wallets

1. User selects a native wallet from the selector
2. near-connect generates a deep link URL (e.g., tg://, near://)
3. NEAR Connect iOS detects the custom URL scheme and opens it with UIApplication.shared.open()
4. The wallet app launches, shows its native UI, and processes the request
5. After approval, the wallet redirects back to your app or the web bridge with result data

private func shouldOpenExternally(_ url: URL) -> Bool {
    let scheme = url.scheme?.lowercased() ?? ""
    
    // Non-HTTP schemes open externally (custom deep links)
    if scheme != "http" && scheme != "https" {
        return true
    }
    
    // Known app-link domains that should open native apps
    let externalDomains = ["t.me", "telegram.me"]
    if let host = url.host?.lowercased(),
       externalDomains.contains(where: { host == $0 || host.hasSuffix(".\($0)") }) {
        return true
    }
    
    return false
}

if shouldOpenExternally(url) {
    UIApplication.shared.open(url)  // Launches native app
    return nil
}

• Native iOS UI and performance
• Can work offline (depending on wallet implementation)
• Better integration with device security (biometrics, secure enclave)
• More control over UX

• User must have the wallet app installed
• Deeplink URL schemes must be properly configured
• App-to-app communication depends on URL callbacks

​

Special Case: HOT Wallet (Telegram)

• Launched via deep link: https://t.me/... or tg://...
• Runs in the Telegram app’s embedded browser
• Leverages Telegram’s authentication and security
• Returns to your app via callback URL

Your App → near-connect selector → User picks HOT
  ↓
Deep link to t.me/hot_wallet
  ↓
Telegram app opens → HOT mini-app loads
  ↓
User approves transaction in Telegram
  ↓
HOT redirects back to bridge page
  ↓
Your app receives result

let externalDomains = ["t.me", "telegram.me"]
if let host = url.host?.lowercased(),
   externalDomains.contains(where: { host == $0 || host.hasSuffix(".\($0)") }) {
    UIApplication.shared.open(url)  // Opens Telegram
    return true
}

​

Connecting to Specific Wallets

// Connect to a specific wallet
walletManager.connect(walletId: "my-near-wallet")

• "hot-wallet" - HOT Wallet (Telegram)
• "my-near-wallet" - MyNearWallet
• "meteor-wallet" - Meteor Wallet
• "intear-wallet" - Intear Wallet

​

Wallet Feature Support

​

Common Features

• ✅ Wallet connection - Basic account authentication
• ✅ NEAR transfers - Sending tokens to other accounts
• ✅ Smart contract calls - Invoking contract methods
• ✅ Transaction signing - Signing and broadcasting transactions

​

Optional Features

​

Handling Fallbacks

​

Example: Connect and Sign Message

let result = try await walletManager.connectAndSignMessage(
    message: "Authenticate with MyApp",
    recipient: "myapp.near"
)

if let signedMessage = result.signedMessage {
    print("Wallet supports signInAndSignMessage: \(signedMessage)")
} else {
    print("Wallet only supports basic signIn, no message signature returned")
}

// Either way, result.account is populated
print("Connected account: \(result.account.accountId)")

case .signedIn(let accountId, let publicKey, let walletId):
    let account = NEARAccount(accountId: accountId, publicKey: publicKey, walletId: walletId)
    currentAccount = account
    
    // If a signInAndSignMessage continuation is waiting but we got
    // a plain signIn event, still complete it (wallet doesn't support the feature)
    if let cont = signInAndSignMessageContinuation {
        let result = SignInWithMessageResult(
            account: account,
            signedMessage: nil  // No signature available
        )
        cont.resume(returning: result)
        signInAndSignMessageContinuation = nil
    }

​

Network Support

// Mainnet (default)
let walletManager = NEARWalletManager()
walletManager.network = .mainnet

// Testnet
let testnetManager = NEARWalletManager()
testnetManager.network = .testnet

• Which wallet environments are shown in the selector
• Which RPC endpoints are used for queries (rpc.mainnet.near.org vs rpc.testnet.near.org)
• Where transactions are broadcast

​

Session Persistence

private func saveAccount(_ account: NEARAccount) {
    if let data = try? JSONEncoder().encode(account) {
        userDefaults.set(data, forKey: accountStorageKey)
    }
}

private func loadStoredAccount() {
    guard let data = userDefaults.data(forKey: accountStorageKey),
          let account = try? JSONDecoder().decode(NEARAccount.self, from: data) else {
        return
    }
    currentAccount = account
}

• ✅ Account ID (e.g., "user.near")
• ✅ Public key (if provided by wallet)
• ✅ Wallet ID (which wallet was used)
• ❌ Private keys (always remain in the wallet)

​

Disconnecting Wallets

walletManager.disconnect()

1. Calls window.nearDisconnect() in the JavaScript bridge
2. Clears the near-connect session state
3. Sets currentAccount to nil
4. Removes the stored account from UserDefaults

​

Adding Custom Wallets

1. Submit to the near-connect manifest: Open a PR to near-connect-ios repository
2. Fork and modify: Clone the near-connect library and add your wallet to the manifest locally
3. Use direct connection: If your wallet follows NEAR wallet standards, use connect(walletId:) with your custom wallet ID

​

Security Considerations

​

Web Wallets

• Run in WKWebView with standard WebKit sandboxing
• Use WKWebsiteDataStore.default() to enable cookies (required by some wallets)
• Custom user agent to ensure compatibility: Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 ...)
• HTTPS-only for production wallets (near-connect enforces this)

​

Native Wallets

• Deep link validation ensures only registered URL schemes are opened
• Callback URLs are verified by near-connect before processing
• Private keys remain in the native app’s secure storage (Keychain, secure enclave, etc.)

​

Bridge Security

• The persistent WebView only loads the bundle’s local HTML file
• JavaScript is loaded from the official near-connect CDN with integrity checks
• Message handlers only accept messages from the trusted bridge page
• All wallet operations require user approval in the wallet UI