Hosted wallet connector on Flutter (headless)

Render your own native wallet list with a hidden WebViewWidget engine. Connect, sign messages, send EVM, Solana or Bitcoin transactions, and sign PSBTs. No wallet SDK in your app.

This is an enterprise-only feature. Please contact us to enable.

The same headless architecture as iOS and Android: render your own native list and drive a hidden WebViewWidget that runs the Dynamic SDK and returns results (including message and transaction signatures) over a JS bridge. No wallet SDK in your Flutter app.

The basic Flutter flow is the recommended default.

No SDK in your app. Your app links no wallet SDK: no CocoaPods, no native crypto, no Gradle dep. It needs a hidden WebViewWidget pointed at the /headless.html engine route and your URL scheme. All WalletConnect / MetaMask / Phantom logic (and the wallet list itself) comes from that hosted view. Redeploy the page to update wallets; the app never changes.

View fireblocks_headless_connect.dart (copy-paste ready)

fireblocks_headless_connect.dart

import 'dart:async';
import 'dart:convert';
import 'dart:math';

import 'package:flutter/widgets.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:webview_flutter/webview_flutter.dart';

import 'app_config.dart';
import 'models.dart';

/// Runs the hosted Fireblocks connect logic (the Dynamic SDK) inside a HIDDEN
/// [WebViewWidget], so the app renders its own native wallet list and keeps
/// every bit of connection logic in the web layer.
///
/// For WalletConnect-protocol wallets (MetaMask, Rainbow, Trust, …) the
/// pairing is relay-based — the engine mints a URI, we open the wallet via
/// deeplink, the user approves, and the approval promise resolves over a
/// WebSocket — none of which needs a visible page. Wallets with no such path
/// come back as [ConnectFallbackRequired] so the caller opens the visible
/// [FireblocksConnect] flow.
///
/// ## Setup
///
/// 1. Wrap your home screen with [FireblocksEngineHost]:
///    ```dart
///    home: FireblocksEngineHost(child: ExampleScreen()),
///    ```
///
/// 2. Warm up at app launch (done for you in `main.dart`):
///    ```dart
///    FireblocksHeadlessConnect.shared.prewarm();
///    ```
///
/// 3. Connect a wallet:
///    ```dart
///    final result = await FireblocksHeadlessConnect.shared.connect(
///      walletKey: 'metamask',
///      chain: 'evm',
///    );
///    switch (result) {
///      case ConnectSuccess(:final wallet): ...
///      case ConnectFallbackRequired(:final reason): ...
///      case ConnectFailure(:final code, :final message): ...
///    }
///    ```
class FireblocksHeadlessConnect {
  FireblocksHeadlessConnect._();
  static final shared = FireblocksHeadlessConnect._();

  /// The no-UI engine page. `returnScheme` is where Phantom's in-app browser
  /// sends the user back (`<scheme>://phantom-headless`) — must match your
  /// registered app URL scheme.
  /// Sourced from [AppConfig] so it can be overridden with `--dart-define`
  /// without touching source.
  String engineUrl = AppConfig.engineUrl;

  /// UI locale for the iframe app, sent as `?locale=<value>` — e.g. `"en_US"`,
  /// `"es_LA"`; see the iframe app's README for the current allow-list.
  /// `null`/empty leaves the page on its own default (`en_US`). Never changes
  /// anything on the native side — it's forwarded as-is to the iframe app.
  ///
  /// Set this BEFORE [prewarm]/[connect]: the URL is resolved when the hidden
  /// WebView is first built, so a later change only takes effect on the next
  /// engine reload.
  String? locale;

  /// UI theme for the iframe app, sent as `?theme=<value>` — `"light"` or
  /// `"dark"`. `null`/empty leaves the page on its own default (`light`).
  /// Never changes anything on the native side — it's forwarded as-is to
  /// the iframe app.
  ///
  /// Set this BEFORE [prewarm]/[connect]: same resolution timing as [locale].
  String? theme;

  /// [engineUrl] with [locale]/[theme] applied.
  String get _resolvedEngineUrl {
    final base = Uri.parse(engineUrl);
    return base.replace(queryParameters: {
      ...base.queryParameters,
      if (locale != null && locale!.isNotEmpty) 'locale': locale,
      if (theme != null && theme!.isNotEmpty) 'theme': theme,
    }).toString();
  }

  static const _startupTimeout = Duration(seconds: 20);
  static const _signTimeout = Duration(seconds: 60);

  /// Longer than [_signTimeout]: a send can involve two sequential wallet
  /// approvals (switch network, then send) rather than one, so 60s is too
  /// tight a budget to fail loud on before the user's had a fair chance to
  /// clear both prompts.
  static const _sendTimeout = Duration(seconds: 120);

  /// How long to wait for wallet approval AFTER a connect deeplink has
  /// opened successfully. [_startupTimeout] is cancelled at that point (see
  /// [_openDeeplink]) with nothing to replace it — so a wallet that never
  /// answers (backgrounded relay session that never resumes, wallet-side
  /// bug, user just closes the wallet app) used to leave [connect]'s
  /// `Future` pending forever, no error, no way out but killing the app.
  /// Generous on purpose: switching to a wallet app and back takes real
  /// human time, and a WalletConnect session proposal is normally good for
  /// 5 minutes anyway.
  static const _connectApprovalTimeout = Duration(minutes: 3);

  // Universal-link hosts that must be opened externally from inside WebView.
  // Kept identical to the Android/iOS native harnesses so wallet-open
  // behavior stays in parity across platforms.
  static const _walletHosts = {
    'phantom.app',
    'phantom.com',
    'link.metamask.io',
    'metamask.app.link',
    'link.trustwallet.com',
    'rnbwapp.com',
    'rainbow.me',
    'www.okx.com',
    'link.okx.com',
    'zerion.io',
  };

  // Never opened, whether reached via a nav-delegate interception or an
  // engine-supplied `deeplink` URL — script / data / local-file vectors, plus
  // the authority-bearing schemes (`intent:`, …) Android hands to
  // `startActivity(ACTION_VIEW)` with no further checks. Mirrors
  // `BLOCKED_REDIRECT_SCHEMES` in `src/config.ts` (#27) exactly — keep the
  // two lists in sync if either changes.
  static const _blockedSchemes = {
    'javascript',
    'data',
    'vbscript',
    'file',
    'blob',
    'about',
    'intent',
    'android-app',
    'market',
    'content',
    'chrome',
    'chrome-extension',
    'moz-extension',
    'ftp',
    'ws',
    'wss',
  };

  /// The engine's own origin (`scheme://host:port`). Inbound bridge messages
  /// are only trusted while the WebView's current page is on this origin —
  /// see [_handleMessage].
  late final Uri _trustedOrigin = Uri.parse(engineUrl);

  /// Updated on every navigation (including SPA `pushState`); starts `null`
  /// so no message is trusted before the first real navigation event lands.
  Uri? _currentOrigin;

  late final WebViewController _controller = _buildController();

  /// The hidden WebView widget. Mount via [FireblocksEngineHost] before calling
  /// any other methods.
  Widget get widget => WebViewWidget(controller: _controller);

  bool _ready = false;
  final _pendingReady = <VoidCallback>[];
  final _connectHandlers = <String, void Function(ConnectResult)>{};
  final _signHandlers = <String, void Function(SignResult)>{};
  final _signTxHandlers = <String, void Function(SignTxResult)>{};
  final _sendTxHandlers = <String, void Function(SendResult)>{};
  final _startupTimers = <String, Timer>{};
  final _signTimers = <String, Timer>{};
  final _signTxTimers = <String, Timer>{};
  final _secureRandom = Random.secure();

  List<HeadlessWallet> _wallets = [];

  void Function(List<HeadlessWallet>)? _onWallets;

  /// Called whenever the engine delivers (or re-delivers) the wallet
  /// catalogue. Setting this replays the last-known list immediately if the
  /// catalogue was already received, so a listener that subscribes late
  /// (e.g. a screen that mounts after the engine is already warm) doesn't
  /// spin forever waiting for a message that already happened.
  set onWallets(void Function(List<HeadlessWallet>)? callback) {
    _onWallets = callback;
    if (callback != null && _wallets.isNotEmpty) callback(_wallets);
  }

  void Function(List<HeadlessWallet>)? get onWallets => _onWallets;

  // MARK: – Public API

  /// Build and load the hidden WebView ahead of time so the first connect
  /// isn't slowed by SDK init + relay negotiation. Safe to call more than once.
  void prewarm() {
    _controller; // ignore: unnecessary_statements — triggers lazy init
  }

  /// Connect [walletKey] through the headless engine. Resolves once.
  ///
  /// [chain] is 'evm', 'solana' or 'bitcoin'.
  Future<ConnectResult> connect({
    required String walletKey,
    String? chain,
  }) {
    // A previous attempt is still in flight — reset to a fresh engine state so
    // the new wallet gets a clean slate (avoids stuck WC/Dynamic sessions).
    if (_connectHandlers.isNotEmpty) _resetEngine();
    final requestId = _generateRequestId('req');
    final completer = Completer<ConnectResult>();
    _connectHandlers[requestId] = completer.complete;
    _scheduleStartupTimeout(requestId);
    void work() => _drive(requestId: requestId, walletKey: walletKey, chain: chain);
    if (_ready) {
      work();
    } else {
      _pendingReady.add(work);
    }
    return completer.future;
  }

  /// Abort every in-flight connect (e.g. user backed out of the wallet list).
  /// Any pending [connect] call resolves with a cancelled failure so callers
  /// never await a [Future] that would otherwise never complete.
  void cancel() {
    _safeRunJavaScript("window.headlessConnect && window.headlessConnect.cancel('');");
    _drainConnectHandlers(const ConnectFailure(code: 'cancelled', message: 'Cancelled'));
  }

  /// Sign [message] with the currently-connected wallet. Resolves once.
  ///
  /// Requires the engine URL to point to a build that includes sign support.
  Future<SignResult> sign({required String message}) {
    final requestId = _generateRequestId('sign');
    final completer = Completer<SignResult>();
    _signHandlers[requestId] = completer.complete;
    _scheduleSignTimeout(requestId, _signHandlers);
    final params = json.encode({'requestId': requestId, 'message': message});
    _safeRunJavaScript('window.headlessConnect && window.headlessConnect.sign($params);');
    return completer.future;
  }

  /// Send a transaction with the currently-connected wallet — EVM, Solana,
  /// or Bitcoin. Resolves once. [transaction] is an opaque JSON string (or,
  /// for Solana, opaque base64); its shape depends on which chain the
  /// connected wallet is on — this method itself is chain-agnostic and just
  /// forwards it to the engine.
  ///
  /// The wallet signs AND broadcasts in one step: `eth_sendTransaction` for
  /// EVM (rather than `eth_signTransaction`, which isn't reliably implemented
  /// by mobile wallets — MetaMask rejects it outright), broadcast-after-sign
  /// for Solana, and the wallet's own `sendBitcoin` RPC for Bitcoin.
  ///
  /// [transaction] format (EVM): JSON string
  /// `{"to":"0x…","value":"0x0","data":"0x","chainId":"0x1"}` — `chainId` is
  /// required; the engine verifies it against the wallet's own active network
  /// before sending, using the Dynamic SDK's network-switching support. On a
  /// mismatch it asks the wallet to switch (adding the chain first via the
  /// SDK's own network config if the wallet does not have it configured) and only
  /// proceeds once the wallet confirms it actually moved, rather than
  /// silently sending on the wrong chain. See `SendFailure.error.code`:
  /// `chain_switch_unavailable` (wallet can't switch programmatically),
  /// `chain_not_configured` (chain isn't in this project's network config),
  /// `chain_switch_rejected` (wallet declined the switch/add prompt), or
  /// `chain_mismatch` (wallet claimed success without actually switching).
  ///
  /// [transaction] format (Solana): base64-encoded, pre-built
  /// `VersionedTransaction` (or legacy `Transaction`) bytes — this app is
  /// responsible for building it (a native SOL transfer vs. an SPL-token
  /// transfer for USDC are both just "whatever instructions are already in
  /// the bytes"); the engine only signs and submits. No chain-switch dance
  /// for Solana — there's no wallet-side "active network" to verify, the
  /// transaction already targets whichever cluster its recent blockhash
  /// came from.
  ///
  /// [transaction] format (Bitcoin): JSON string
  /// `{"recipientAddress":"bc1…","amountSats":"12345"}` — `amountSats` is
  /// the amount in satoshis as a decimal-digit string. The wallet's own
  /// `sendBitcoin` RPC signs AND broadcasts; there is no chain-switch step
  /// (Bitcoin has no equivalent of an EVM chainId to mismatch on).
  ///
  /// On success, [SendSuccess.txHash] is the on-chain transaction hash (EVM),
  /// signature (Solana, which IS the transaction's identifier), or
  /// transaction ID (Bitcoin) — it has already been submitted, there is
  /// nothing further to broadcast.
  Future<SendResult> sendTransaction({required String transaction}) {
    final requestId = _generateRequestId('sendtx');
    final completer = Completer<SendResult>();
    _sendTxHandlers[requestId] = completer.complete;
    _signTimers[requestId] = Timer(_sendTimeout, () {
      _signTimers.remove(requestId);
      _sendTxHandlers.remove(requestId)?.call(
            const SendFailure(SignError(
              code: 'timeout',
              message: 'Wallet did not respond in time — if you approved it, the transaction '
                  'may still have been submitted; check the explorer before retrying.',
            )),
          );
    });
    final params = json.encode({'requestId': requestId, 'transaction': transaction});
    // `sendTx` is a newer addition to the engine than everything else this
    // class calls — a deployment that predates it would otherwise leave this
    // request silently unanswered until the 60s timeout, indistinguishable
    // from a dead wallet. Self-report immediately instead, straight over the
    // same `walletNative` channel _handleMessage already listens on.
    _safeRunJavaScript(
      'if (window.headlessConnect && window.headlessConnect.sendTx) {'
      '  window.headlessConnect.sendTx($params);'
      '} else if (window.walletNative && window.walletNative.postMessage) {'
      '  window.walletNative.postMessage(JSON.stringify({'
      '    type: "sentTxFailed",'
      '    requestId: ${json.encode(requestId)},'
      '    code: "unsupported_engine",'
      '    message: "engine build predates sendTx — redeploy connect.dynamicauth.com"'
      '  }));'
      '}',
    );
    return completer.future;
  }

  /// Sign a transaction with the currently-connected wallet without
  /// broadcasting it. Resolves once.
  ///
  /// [transaction] format (EVM): JSON string
  /// `{"to":"0x…","value":"0x0","data":"0x","chainId":"0x1"}`.
  ///
  /// [transaction] format (Solana): base64-encoded, pre-built
  /// `VersionedTransaction` (or legacy `Transaction`) bytes.
  ///
  /// [transaction] format (Bitcoin): JSON string
  /// `{"unsignedPsbtBase64","allowedSighash","signature"}`. The result is a
  /// base64 signed PSBT; the caller must finalize and broadcast it.
  Future<SignTxResult> signTransaction({required String transaction}) {
    final requestId = _generateRequestId('signtx');
    final completer = Completer<SignTxResult>();
    _signTxHandlers[requestId] = completer.complete;
    _signTxTimers[requestId] = Timer(_signTimeout, () {
      _signTxTimers.remove(requestId);
      _signTxHandlers.remove(requestId)?.call(
            const SignTxFailure('timeout', 'Wallet did not respond in time'),
          );
    });
    final params =
        json.encode({'requestId': requestId, 'transaction': transaction});
    _safeRunJavaScript(
      'if (window.headlessConnect && window.headlessConnect.signTx) {'
      '  window.headlessConnect.signTx($params);'
      '} else if (window.walletNative && window.walletNative.postMessage) {'
      '  window.walletNative.postMessage(JSON.stringify({'
      '    type: "signTxFailed",'
      '    requestId: ${json.encode(requestId)},'
      '    code: "unsupported_engine",'
      '    message: "engine build predates signTx — redeploy connect.dynamicauth.com"'
      '  }));'
      '}',
    );
    return completer.future;
  }

  /// Tear down the session. Clears localStorage so stale Dynamic SDK state
  /// doesn't bleed into the next connect, then reloads the engine page.
  /// Any handlers still pending are drained with a cancelled result first.
  Future<void> disconnect() async {
    _drainConnectHandlers(const ConnectFailure(code: 'disconnected', message: 'Disconnected'));
    _drainSignHandlers();
    _ready = false;
    _pendingReady.clear();
    _wallets = [];
    _onWallets?.call(_wallets);
    // Clear storage before reload — equivalent to the iOS ephemeral WebView teardown.
    await _safeRunJavaScript('localStorage.clear(); sessionStorage.clear();');
    try {
      await _controller.reload();
    } catch (_) {
      // Page may not have finished its initial load yet — ignore, the
      // subsequent loadRequest inside _buildController already covers cold start.
    }
  }

  /// Consume `<scheme>://phantom-headless`, the zero-payload "Return to app"
  /// tap from Phantom's in-app browser. Opening the link already brought the
  /// app forward, and the engine gets the connection over the WalletConnect
  /// relay, so there's nothing to forward. Returns `true` if it consumed the URL.
  ///
  /// Call this from your app's `app_links` listener:
  /// ```dart
  /// AppLinks().uriLinkStream.listen((uri) {
  ///   FireblocksHeadlessConnect.shared.handleReturnUrl(uri);
  /// });
  /// ```
  bool handleReturnUrl(Uri uri) => uri.host.toLowerCase() == 'phantom-headless';

  // MARK: – Private

  WebViewController _buildController() {
    return WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      // `walletNative` matches the Android @JavascriptInterface name (and the
      // generic `window.walletNative.postMessage` fallback checked by the web
      // bridge) — no engine changes needed for Flutter.
      ..addJavaScriptChannel(
        'walletNative',
        onMessageReceived: (msg) => _handleMessage(msg.message),
      )
      ..setNavigationDelegate(NavigationDelegate(
        // Tracks the page actually loaded, for the origin check in
        // _handleMessage — `onNavigationRequest` alone tells us what was
        // *requested*, not what's live once redirects/SPA routing settle.
        onPageStarted: _updateCurrentOrigin,
        onUrlChange: (change) => _updateCurrentOrigin(change.url),
        onNavigationRequest: _onNavigationRequest,
      ))
      ..loadRequest(Uri.parse(_resolvedEngineUrl));
  }

  void _updateCurrentOrigin(String? url) {
    _currentOrigin = url == null ? null : Uri.tryParse(url);
  }

  /// Deny-by-default, including subframes — mirrors the bridge fix in PR #26
  /// ("Navigation is deny-by-default, including subframes"). Only the
  /// engine's own origin is ever allowed to load, in any frame; a
  /// cross-origin subframe (e.g. an XSS'd `<iframe>` on the engine's own
  /// page) is refused outright rather than handed to url_launcher, and a
  /// cross-origin *main*-frame navigation either hands off to an installed
  /// app (subject to [_blockedSchemes]) or is dropped — it never gets to
  /// load inside this privileged WebView and inherit the `walletNative`
  /// channel.
  ///
  /// Known gap: `webview_flutter`'s `onNavigationRequest` has historically
  /// not fired for every subframe load on Android (`shouldOverrideUrlLoading`
  /// skips some iframe navigations) — this closes the main-frame redirect
  /// path with certainty; treat subframe coverage as defense-in-depth, not
  /// a proven guarantee, until verified on-device per platform.
  NavigationDecision _onNavigationRequest(NavigationRequest req) {
    final uri = Uri.tryParse(req.url);
    if (uri == null) {
      debugPrint('[FireblocksHeadlessConnect] blocked unparsable navigation target');
      return NavigationDecision.prevent;
    }
    if (_isEngineOrigin(uri)) return NavigationDecision.navigate;
    if (!req.isMainFrame) {
      debugPrint('[FireblocksHeadlessConnect] blocked cross-origin subframe: ${req.url}');
      return NavigationDecision.prevent;
    }
    if (_isBlockedScheme(uri)) {
      debugPrint('[FireblocksHeadlessConnect] blocked scheme in navigation: ${req.url}');
      return NavigationDecision.prevent;
    }
    if (_shouldOpenExternally(uri)) _openExternally(uri);
    return NavigationDecision.prevent;
  }

  bool _isEngineOrigin(Uri uri) =>
      uri.scheme.toLowerCase() == _trustedOrigin.scheme.toLowerCase() &&
      uri.host.toLowerCase() == _trustedOrigin.host.toLowerCase() &&
      _effectivePort(uri) == _effectivePort(_trustedOrigin);

  int _effectivePort(Uri uri) =>
      uri.hasPort ? uri.port : (uri.scheme.toLowerCase() == 'https' ? 443 : 80);

  /// Never-allowed schemes — see [_blockedSchemes]'s doc comment.
  bool _isBlockedScheme(Uri uri) => _blockedSchemes.contains(uri.scheme.toLowerCase());

  bool _shouldOpenExternally(Uri uri) {
    final scheme = uri.scheme.toLowerCase();
    if (scheme != 'http' && scheme != 'https') return true; // custom schemes (fbapp://, metamask://)
    final host = uri.host.toLowerCase();
    return _walletHosts.any((h) => host == h || host.endsWith('.$h'));
  }

  /// Cryptographically-random per-call request id — deliberately not a
  /// sequential counter. A guessable id lets whatever's currently loaded in
  /// the WebView (attacker-controlled content, if the origin/navigation
  /// checks above were ever bypassed) forge a reply that completes a
  /// *different* pending request. Mirrors the per-connect UUIDs PR #26 added
  /// to the iOS/Android bridges; implemented with `dart:math`'s
  /// `Random.secure()` rather than a `uuid` package dependency.
  String _generateRequestId(String prefix) {
    final bytes = List<int>.generate(16, (_) => _secureRandom.nextInt(256));
    final hex = bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
    return '$prefix-$hex';
  }

  void _drive({required String requestId, required String walletKey, String? chain}) {
    final params = <String, dynamic>{'requestId': requestId, 'walletKey': walletKey};
    if (chain != null) params['chain'] = chain;
    _safeRunJavaScript(
      'window.headlessConnect && window.headlessConnect.connect(${json.encode(params)});',
    );
  }

  void _resetEngine() {
    _drainConnectHandlers(const ConnectFailure(code: 'reset', message: 'Superseded by a new connect request'));
    _ready = false;
    _pendingReady.clear();
    try {
      _controller.reload();
    } catch (_) {
      // Ignore — next connect() will retry once the reload settles.
    }
  }

  /// Every inbound bridge message is checked against the engine's own origin
  /// before being trusted — mirrors PR #26 ("Origin-check every inbound
  /// message against the engine URL; drop anything else"). `webview_flutter`
  /// injects the `walletNative` channel into every frame on the page, and
  /// doesn't expose which frame a given message came from, so this checks
  /// the *page* (via [_currentOrigin], updated by the navigation delegate)
  /// rather than the sender — the deny-by-default nav delegate in
  /// [_onNavigationRequest] is what stops a cross-origin frame from loading
  /// in the first place; this is the second layer, not a substitute for it.
  void _handleMessage(String jsonStr) {
    final origin = _currentOrigin;
    if (origin == null || !_isEngineOrigin(origin)) {
      debugPrint('[FireblocksHeadlessConnect] dropped bridge message from untrusted origin: $origin');
      return;
    }

    final Map<String, dynamic> obj;
    try {
      obj = json.decode(jsonStr) as Map<String, dynamic>;
    } catch (_) {
      return;
    }

    switch (obj['type'] as String?) {
      case 'ready':
        _ready = true;
        final work = List<VoidCallback>.of(_pendingReady);
        _pendingReady.clear();
        for (final fn in work) {
          fn();
        }

      case 'wallets':
        final raw = obj['wallets'];
        if (raw is List) {
          _wallets = raw.whereType<Map<String, dynamic>>().map(HeadlessWallet.fromJson).toList();
          _onWallets?.call(_wallets);
          // Which chains the engine is actually offering per wallet is
          // otherwise invisible from the device, and it's the first thing you
          // need when a wallet+chain combination misbehaves (a Phantom "EVM"
          // entry that no connection path backed went unnoticed exactly
          // because of this blind spot).
          for (final w in _wallets) {
            debugPrint('[FireblocksHeadlessConnect] wallet ${w.key}: '
                'chains=${w.chains} mode=${w.mode}');
          }
        }

      case 'deeplink':
        // Engine produced a WalletConnect / MetaMask URI — open the wallet.
        _openDeeplink(obj['requestId'] as String?, obj['url'] as String?);

      case 'openWallet':
        // A WalletConnect sign/send request is waiting — wake the wallet app
        // so its approval prompt surfaces (the request itself already went
        // over the relay; without this it sits invisibly until the user
        // opens the wallet by hand). requestId here is a sign/send id, not a
        // connect attempt — pass null so no connect bookkeeping is touched.
        _openDeeplink(null, obj['url'] as String?);

      case 'opening':
        // Wallet being opened via WebView navigation (Phantom redirect protocol).
        _cancelStartupTimer(obj['requestId'] as String?);

      case 'connected':
        final address = obj['address'] as String?;
        // A `connected` message with no address used to succeed with `''`
        // silently — Finding 19 in the PR #26 stack. Fail loud instead: an
        // engine bug (or a message that slipped past the origin check above)
        // should never read to the caller as "the user connected wallet ''".
        _finishConnect(
          obj['requestId'] as String?,
          (address == null || address.isEmpty)
              ? const ConnectFailure(
                  code: 'malformed_result',
                  message: 'Engine sent connected with no address')
              : ConnectSuccess(WalletConnection(
                  address: address,
                  chain: obj['chain'] as String? ?? '',
                  network: obj['network'] as String?,
                  walletName: obj['walletName'] as String? ?? '',
                  walletImage: obj['walletImage'] as String? ?? '',
                )),
        );

      case 'fallback':
        _finishConnect(
          obj['requestId'] as String?,
          ConnectFallbackRequired(obj['reason'] as String? ?? ''),
        );

      case 'error':
        _finishConnect(
          obj['requestId'] as String?,
          ConnectFailure(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          ),
        );

      case 'signed':
        _finishSign(obj['requestId'] as String?, SignSuccess(obj['signature'] as String? ?? ''));

      case 'signFailed':
        _finishSign(
          obj['requestId'] as String?,
          SignFailure(SignError(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          )),
        );

      case 'signedTx':
        _finishSignTx(
          obj['requestId'] as String?,
          SignTxSuccess(
            obj['signedTransaction'] as String? ?? '',
            obj['chain'] as String? ?? '',
          ),
        );

      case 'signTxFailed':
        _finishSignTx(
          obj['requestId'] as String?,
          SignTxFailure(
            obj['code'] as String? ?? 'unknown',
            obj['message'] as String? ?? '',
          ),
        );

      case 'sentTx':
        _finishSendTx(
          obj['requestId'] as String?,
          SendSuccess(obj['txHash'] as String? ?? '', chain: obj['chain'] as String? ?? ''),
        );

      case 'sentTxFailed':
        _finishSendTx(
          obj['requestId'] as String?,
          SendFailure(SignError(
            code: obj['code'] as String? ?? 'unknown',
            message: obj['message'] as String? ?? '',
          )),
        );

      case 'event':
        // The engine's diagnostic timeline (wallet_selected, deeplink_opened,
        // fallback, connected, wallet_action_requested, error …). Logged rather
        // than dropped: the resolved chain and the exact fallback reason only
        // exist here, and without them a failed connect looks identical from
        // the device whether it never found a path, opened the wrong app, or
        // was rejected in the wallet. Swap the debugPrint for an analytics
        // hook if you want these off-device.
        debugPrint('[FireblocksHeadlessConnect] event ${obj['event']} '
            '${obj['requestId'] ?? ''} ${obj['data'] ?? ''}');

    }
  }

  /// Attempt to open a wallet deeplink produced by the engine. On success the
  /// startup timer is REPLACED with the longer [_connectApprovalTimeout]
  /// (the user is now away in their wallet app, approving) — not just
  /// cancelled outright, or a wallet that never answers back would leave
  /// [connect]'s `Future` pending forever (see that constant's doc comment).
  /// On failure the engine is told immediately via `onDeeplinkFailed` so it
  /// can fall back to the visible flow rather than waiting out the full
  /// startup timeout — the startup timer itself is left running as a backstop
  /// in case the engine doesn't respond to that call.
  Future<void> _openDeeplink(String? requestId, String? url) async {
    if (url == null) return;
    final uri = Uri.tryParse(url);
    if (uri == null) return;
    // Belt-and-braces: this URL comes from the engine, which has already
    // passed the origin check by the time this fires, but native enforces
    // the scheme block-list on every hand-off to the OS regardless of
    // source — see [_blockedSchemes]'s doc comment.
    if (_isBlockedScheme(uri)) {
      debugPrint('[FireblocksHeadlessConnect] blocked scheme in deeplink: $url');
      return;
    }
    var opened = false;
    try {
      opened = await launchUrl(uri, mode: LaunchMode.externalApplication);
    } catch (_) {
      opened = false;
    }
    if (opened) {
      // requestId is null for a sign/send wake-up (see the 'openWallet' case
      // above) — nothing to reschedule there, sign/send have their own
      // timers already running.
      if (requestId != null) {
        _scheduleConnectApprovalTimeout(requestId);
      } else {
        _cancelStartupTimer(requestId);
      }
    } else if (requestId != null) {
      _safeRunJavaScript(
        'window.headlessConnect && window.headlessConnect.onDeeplinkFailed && '
        'window.headlessConnect.onDeeplinkFailed(${json.encode(requestId)});',
      );
    }
  }

  Future<void> _openExternally(Uri uri) async {
    try {
      await launchUrl(uri, mode: LaunchMode.externalApplication);
    } catch (_) {
      // No app to handle it — nothing to recover to from a bare navigation
      // interception (there's no requestId here), matching Android's stance.
    }
  }

  void _finishConnect(String? requestId, ConnectResult result) {
    if (requestId == null) return;
    final handler = _connectHandlers.remove(requestId);
    _cancelStartupTimer(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped connect reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSign(String? requestId, SignResult result) {
    if (requestId == null) return;
    _signTimers.remove(requestId)?.cancel();
    final handler = _signHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped sign reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSignTx(String? requestId, SignTxResult result) {
    if (requestId == null) return;
    _signTxTimers.remove(requestId)?.cancel();
    final handler = _signTxHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped signTx reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _finishSendTx(String? requestId, SendResult result) {
    if (requestId == null) return;
    _signTimers.remove(requestId)?.cancel();
    final handler = _sendTxHandlers.remove(requestId);
    if (handler == null) {
      debugPrint('[FireblocksHeadlessConnect] dropped sendTx reply for unknown requestId: $requestId');
      return;
    }
    handler(result);
  }

  void _drainConnectHandlers(ConnectResult result) {
    final handlers = Map<String, void Function(ConnectResult)>.of(_connectHandlers);
    _connectHandlers.clear();
    for (final id in handlers.keys) {
      _cancelStartupTimer(id);
    }
    for (final handler in handlers.values) {
      handler(result);
    }
  }

  void _drainSignHandlers() {
    for (final timer in _signTimers.values) {
      timer.cancel();
    }
    _signTimers.clear();
    const result = SignFailure(SignError(code: 'disconnected', message: 'Disconnected'));
    final signHandlers = Map<String, void Function(SignResult)>.of(_signHandlers);
    _signHandlers.clear();
    for (final handler in signHandlers.values) {
      handler(result);
    }
    for (final timer in _signTxTimers.values) {
      timer.cancel();
    }
    _signTxTimers.clear();
    const signTxResult = SignTxFailure('disconnected', 'Disconnected');
    final signTxHandlers =
        Map<String, void Function(SignTxResult)>.of(_signTxHandlers);
    _signTxHandlers.clear();
    for (final handler in signTxHandlers.values) {
      handler(signTxResult);
    }
    const sendResult = SendFailure(SignError(code: 'disconnected', message: 'Disconnected'));
    final sendHandlers = Map<String, void Function(SendResult)>.of(_sendTxHandlers);
    _sendTxHandlers.clear();
    for (final handler in sendHandlers.values) {
      handler(sendResult);
    }
  }

  void _scheduleStartupTimeout(String requestId) {
    _startupTimers[requestId]?.cancel();
    _startupTimers[requestId] = Timer(_startupTimeout, () {
      _startupTimers.remove(requestId);
      _finishConnect(requestId, const ConnectFallbackRequired('headless startup timeout'));
    });
  }

  void _cancelStartupTimer(String? requestId) {
    if (requestId == null) return;
    _startupTimers.remove(requestId)?.cancel();
  }

  /// Reuses [_startupTimers] (same map, same cancel-on-`_finishConnect` path)
  /// with [_connectApprovalTimeout]'s longer budget — see that constant's
  /// doc comment for why this exists at all.
  void _scheduleConnectApprovalTimeout(String requestId) {
    _startupTimers[requestId]?.cancel();
    _startupTimers[requestId] = Timer(_connectApprovalTimeout, () {
      _startupTimers.remove(requestId);
      _finishConnect(
        requestId,
        const ConnectFailure(code: 'timeout', message: 'Wallet did not respond in time'),
      );
    });
  }

  void _scheduleSignTimeout(
    String requestId,
    Map<String, void Function(SignResult)> handlers,
  ) {
    _signTimers[requestId] = Timer(_signTimeout, () {
      _signTimers.remove(requestId);
      handlers.remove(requestId)?.call(
            const SignFailure(SignError(code: 'timeout', message: 'Wallet did not respond in time')),
          );
    });
  }

  Future<void> _safeRunJavaScript(String js) async {
    try {
      await _controller.runJavaScript(js);
    } catch (_) {
      // WebView not attached / navigation in progress — safe to drop; the
      // caller has already scheduled its own timeout as a backstop.
    }
  }
}

/// Mounts the hidden engine WebView while rendering [child].
///
/// Place near the root of your app so the engine is always alive regardless of
/// which screen is active:
///
/// ```dart
/// MaterialApp(
///   home: FireblocksEngineHost(child: ExampleScreen()),
/// )
/// ```
class FireblocksEngineHost extends StatelessWidget {
  final Widget child;
  const FireblocksEngineHost({super.key, required this.child});

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        child,
        // Hidden 1×1 — positioned off-screen to avoid intercepting touch events
        // while staying in the tree so Flutter doesn't throttle / suspend it.
        Positioned(
          left: -1,
          top: -1,
          width: 1,
          height: 1,
          child: FireblocksHeadlessConnect.shared.widget,
        ),
      ],
    );
  }
}

View models.dart (copy-paste ready)

models.dart

/// A wallet entry in the native list, delivered live by the engine.
/// [mode] is `"headless"` (silent connection) or `"fallback"` (visible flow needed).
class HeadlessWallet {
  final String key;
  final String name;
  final String icon;
  final List<String> chains;
  final String mode;
  final bool featured;

  /// The wallet's in-app-browser URL template (`{{encodedDappURI}}`), when the
  /// wallet book carries one — `null` otherwise.
  ///
  /// This is NOT one of [chains]: it means "this wallet can open a URL in its
  /// own browser", where it injects its providers. Some wallets are only
  /// reachable that way for some chains (Phantom on EVM — see
  /// [FireblocksWalletBrowser]). The template itself says nothing about WHICH
  /// chains that browser serves — see [inAppBrowserChain] for the one case
  /// where the engine can say so trustworthily.
  final String? inAppBrowserUrl;

  /// The chain [inAppBrowserUrl] is for — set by the engine (`headless.ts`)
  /// ONLY when the wallet-book entry has a single unambiguous chain for it
  /// (e.g. Xverse: exactly one `injectedConfig` entry, `chain: "btc"`).
  /// `null` for a wallet like Phantom, whose template is overloaded (really
  /// its Sui entry, not EVM) — that case still needs the hand-verified route
  /// in [FireblocksWalletBrowser] rather than trusting this field.
  final String? inAppBrowserChain;

  const HeadlessWallet({
    required this.key,
    required this.name,
    required this.icon,
    required this.chains,
    required this.mode,
    required this.featured,
    this.inAppBrowserUrl,
    this.inAppBrowserChain,
  });

  factory HeadlessWallet.fromJson(Map<String, dynamic> json) => HeadlessWallet(
        key: json['key'] as String? ?? '',
        name: json['name'] as String? ?? '',
        icon: json['icon'] as String? ?? '',
        chains: (json['chains'] as List<dynamic>?)?.cast<String>() ?? const [],
        mode: json['mode'] as String? ?? 'fallback',
        featured: json['featured'] as bool? ?? false,
        inAppBrowserUrl: json['inAppBrowser'] as String?,
        inAppBrowserChain: json['inAppBrowserChain'] as String?,
      );

  bool get isMultiChain => chains.length > 1;
  bool get isHeadless => mode == 'headless';
}

/// A successfully connected wallet account.
class WalletConnection {
  final String address;
  final String chain;
  final String walletName;
  final String walletImage;

  /// `true` for wallets connected through the hidden WebView engine;
  /// `false` for the visible ASWebAuth / Chrome Custom Tabs fallback flow.
  final bool connectedHeadlessly;

  /// The [HeadlessWallet.key] that produced this connection, e.g. `"metamask"`.
  ///
  /// NOT part of the engine's wire protocol (the `connected` bridge message
  /// carries no wallet key) — set locally by the caller that made the
  /// `connect()` call, so the UI can offer a one-tap "Reconnect" to the same
  /// wallet on a later app launch. `null` when unknown.
  final String? walletKey;

  /// The Solana network this wallet SESSION is bound to ('mainnet-beta' |
  /// 'devnet'), when the wallet's protocol binds one at connect time
  /// (Phantom's redirect protocol does). The session decides what the wallet
  /// will sign for, so send UIs must follow it — the engine rejects a send
  /// on the other network. `null` for wallets with no such binding (their
  /// send UI may offer a network choice freely).
  final String? network;

  /// Set when this connection was made inside the WALLET's own in-app browser
  /// ([FireblocksWalletBrowser]) — the in-app-browser URL template it was
  /// opened with. The connection belongs to the provider injected in that
  /// browser and exists nowhere else, so sign/send have to be re-opened there
  /// too: pass this back to [FireblocksWalletBrowser.signMessage] /
  /// [FireblocksWalletBrowser.sendTransaction]. `null` for every other path
  /// (headless engine, system-browser visible flow).
  final String? walletBrowserUrl;

  const WalletConnection({
    required this.address,
    required this.chain,
    required this.walletName,
    required this.walletImage,
    this.connectedHeadlessly = true,
    this.walletKey,
    this.network,
    this.walletBrowserUrl,
  });

  WalletConnection copyWith({String? walletKey}) => WalletConnection(
        address: address,
        chain: chain,
        walletName: walletName,
        walletImage: walletImage,
        connectedHeadlessly: connectedHeadlessly,
        walletKey: walletKey ?? this.walletKey,
        network: network,
        walletBrowserUrl: walletBrowserUrl,
      );
}

/// Describes a failed sign operation.
class SignError {
  final String code;
  final String message;

  const SignError({required this.code, required this.message});

  @override
  String toString() => '[$code] $message';
}

// ── Connect result ───────────────────────────────────────────────────────────

sealed class ConnectResult {
  const ConnectResult();
}

final class ConnectSuccess extends ConnectResult {
  final WalletConnection wallet;
  const ConnectSuccess(this.wallet);
}

/// The wallet can't go headless; caller should open [FireblocksConnect.connect].
final class ConnectFallbackRequired extends ConnectResult {
  final String reason;
  const ConnectFallbackRequired(this.reason);
}

final class ConnectFailure extends ConnectResult {
  final String code;
  final String message;
  const ConnectFailure({required this.code, required this.message});
}

// ── Sign result ──────────────────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.sign] (headless) OR
/// [FireblocksConnect.signMessage] (visible flow — Base Account / Coinbase
/// Smart Wallet, or any other wallet that can only connect that way; see
/// that method's docs for why it can't go through the headless engine).
sealed class SignResult {
  const SignResult();
}

final class SignSuccess extends SignResult {
  /// Signed message: hex signature string.
  /// Signed tx (EVM): RLP-encoded hex. Signed tx (Solana): base64.
  final String value;
  const SignSuccess(this.value);
}

final class SignFailure extends SignResult {
  final SignError error;
  const SignFailure(this.error);
}

// ── Sign transaction result ──────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.signTransaction]. This operation signs
/// without broadcasting; a Bitcoin success contains a signed PSBT that the
/// caller finalizes and broadcasts.
sealed class SignTxResult {
  const SignTxResult();
}

final class SignTxSuccess extends SignTxResult {
  /// Signed transaction: RLP-encoded hex (EVM), base64 (Solana), or a base64
  /// signed PSBT (Bitcoin).
  final String signedTransaction;

  /// "evm", "solana", or "bitcoin".
  final String chain;

  const SignTxSuccess(this.signedTransaction, this.chain);
}

final class SignTxFailure extends SignTxResult {
  final String code;
  final String message;

  const SignTxFailure(this.code, this.message);
}

// ── Send result ──────────────────────────────────────────────────────────────

/// Result of [FireblocksHeadlessConnect.sendTransaction] (headless, EVM,
/// Solana, or Bitcoin) OR [FireblocksConnect.sendTransaction] (visible flow —
/// Base Account / Coinbase Smart Wallet, or any other wallet that can only
/// connect that way; EVM only — see that method's docs for why it can't go
/// through the headless engine). Unlike [SignResult] (sign-only, nothing
/// broadcast), this wallet call signs AND broadcasts the transaction; a
/// [SendSuccess] means it's already on-chain.
sealed class SendResult {
  const SendResult();
}

final class SendSuccess extends SendResult {
  /// The on-chain transaction hash (EVM), signature (Solana, which IS the
  /// transaction's identifier), or transaction ID (Bitcoin) — already
  /// submitted, not a raw signed tx.
  final String txHash;

  /// "evm", "solana", or "bitcoin". Empty for the visible-flow path, which is
  /// EVM-only and doesn't echo a chain back.
  final String chain;

  const SendSuccess(this.txHash, {this.chain = ''});
}

final class SendFailure extends SendResult {
  final SignError error;
  const SendFailure(this.error);
}

// ── Exchange transfer result ─────────────────────────────────────────────────

/// Result of [FireblocksConnect.fundFromExchange] — funds sent from the user's
/// exchange account to an address.
///
/// No wallet is involved: the user authenticates with the EXCHANGE, and the
/// exchange signs and broadcasts the withdrawal itself. That's also why this
/// isn't a [SendResult] — there is no transaction hash to return, only the
/// exchange's own transfer id (see [ExchangeTransferSuccess.transferId]).
sealed class ExchangeTransferResult {
  const ExchangeTransferResult();
}

final class ExchangeTransferSuccess extends ExchangeTransferResult {
  /// The EXCHANGE's transfer id — not an on-chain hash. The exchange
  /// broadcasts on its own schedule, so at this point there may be no hash at
  /// all yet; poll the exchange (or the destination address) for settlement.
  final String transferId;

  /// Which exchange the funds came from, e.g. `"coinbase"`.
  final String exchange;

  /// Amount and currency the exchange accepted, echoed back — it can differ
  /// from what was requested (e.g. rounded to the currency's precision).
  final String amount;
  final String currency;

  /// The exchange's own status string when it reports one (e.g. `"pending"`).
  final String? status;

  const ExchangeTransferSuccess({
    required this.transferId,
    required this.exchange,
    required this.amount,
    required this.currency,
    this.status,
  });
}

final class ExchangeTransferFailure extends ExchangeTransferResult {
  final SignError error;
  const ExchangeTransferFailure(this.error);
}

// ── Exchange balances result ─────────────────────────────────────────────────

/// One balance from [FireblocksConnect.getExchangeBalances] — an
/// account/currency pair, since a single exchange account can hold several
/// currencies and each is reported separately.
///
/// Deliberately carries no account id: this travels inside a callback URL
/// (a custom-scheme one on Android can land in system navigation/Intent
/// logs), and nothing on this read-only path ever needs to address a
/// specific account again — see the matching comment on the web side's
/// `ExchangeBalance` in `src/redirect.ts`.
final class ExchangeBalance {
  final String accountName;
  final String currency;
  final double balance;

  /// What's actually free to move — [balance] minus anything held/pending.
  /// Show this one if you're only showing a single number.
  final double available;

  const ExchangeBalance({
    required this.accountName,
    required this.currency,
    required this.balance,
    required this.available,
  });

  factory ExchangeBalance.fromJson(Map<String, dynamic> json) => ExchangeBalance(
        accountName: json['accountName'] as String,
        currency: json['currency'] as String,
        balance: (json['balance'] as num).toDouble(),
        available: (json['available'] as num).toDouble(),
      );
}

/// Result of [FireblocksConnect.getExchangeBalances] — the read-only sibling
/// of [ExchangeTransferResult]: same OAuth link step, but it never moves
/// money. Nothing here needs a destination address, an amount, MFA, or
/// travel-rule details — those only exist once a transfer is actually being
/// attempted.
sealed class ExchangeBalancesResult {
  const ExchangeBalancesResult();
}

final class ExchangeBalancesSuccess extends ExchangeBalancesResult {
  /// Which exchange these balances came from, e.g. `"coinbase"`.
  final String exchange;
  final List<ExchangeBalance> accounts;

  const ExchangeBalancesSuccess({required this.exchange, required this.accounts});
}

final class ExchangeBalancesFailure extends ExchangeBalancesResult {
  final SignError error;
  const ExchangeBalancesFailure(this.error);
}

View app_config.dart (copy-paste ready)

app_config.dart

/// Central configuration for the app's URL scheme and hosted engine URLs.
///
/// Kept in one place (rather than duplicated string literals across
/// `main.dart` / `example_screen.dart` / native manifests) because the
/// scheme in particular must match exactly in three other places:
///
///  - `ios/Runner/Info.plist`               → `CFBundleURLSchemes`
///  - `android/app/src/main/AndroidManifest.xml` → `<data android:scheme="…">`
///  - the hosted engine's `returnScheme` query param (baked into [engineUrl])
///
/// Override any of these at build/run time without touching source:
/// ```bash
/// flutter run \
///   --dart-define=WALLET_SCHEME=myapp \
///   --dart-define=ENGINE_BASE_URL=https://connect.dynamicauth.com/headless.html \
///   --dart-define=HOSTED_PAGE_URL=https://connect.dynamicauth.com/ \
///   --dart-define=DYNAMIC_ENVIRONMENT_ID=b1e3aca9-0646-411a-b4ab-c31ce49935b3
/// ```
abstract final class AppConfig {
  /// The app's registered custom URL scheme. Must be a valid RFC 3986 scheme:
  /// lowercase letters/digits/`+`/`-`/`.` only, starting with a letter — no
  /// underscores (required by `flutter_web_auth_2`'s `callbackUrlScheme`).
  static const scheme = String.fromEnvironment('WALLET_SCHEME', defaultValue: 'fbapp');

  static const _engineBaseUrl = String.fromEnvironment(
    'ENGINE_BASE_URL',
    defaultValue: 'https://connect.dynamicauth.com/headless.html',
  );

  /// The visible, hosted connect page used by the ASWebAuth / Chrome Custom
  /// Tabs fallback flow ([FireblocksConnect]).
  static const hostedPageUrl = String.fromEnvironment(
    'HOSTED_PAGE_URL',
    defaultValue: 'https://connect.dynamicauth.com/',
  );

  /// Which Dynamic environment the hosted pages should use, sent as
  /// `?environmentId=<uuid>` on both [engineUrl] and the visible flow URL.
  ///
  /// Empty (the default) means "don't send the param", and the hosted page falls
  /// back to the environment it was built with — so existing builds are
  /// unaffected. The page ignores anything that isn't a UUID.
  static const environmentId = String.fromEnvironment('DYNAMIC_ENVIRONMENT_ID');

  /// The no-UI engine page loaded into the hidden WebView. `returnScheme`
  /// is where Phantom's in-app browser sends the user back.
  ///
  /// Built through [Uri] rather than string interpolation so a custom
  /// `ENGINE_BASE_URL` that already carries a query string keeps its params
  /// instead of having them clobbered by a bare `?`.
  static String get engineUrl => withEnvironmentId(
        Uri.parse(_engineBaseUrl).replace(queryParameters: {
          ...Uri.parse(_engineBaseUrl).queryParameters,
          'returnScheme': scheme,
        }).toString(),
      );

  /// Add `environmentId` to [url] when one is configured, preserving any params
  /// already on it. A no-op when [environmentId] is empty.
  static String withEnvironmentId(String url) {
    if (environmentId.isEmpty) return url;
    final base = Uri.parse(url);
    return base.replace(queryParameters: {
      ...base.queryParameters,
      'environmentId': environmentId,
    }).toString();
  }
}

1. Add dependencies

pubspec.yaml

dependencies:
  webview_flutter: 4.10.0      # hidden engine WebView
  url_launcher: 6.3.1          # open wallet deeplinks
  flutter_web_auth_2: 4.0.1    # visible fallback flow
  app_links: ^6.0.0            # Phantom / deep-link returns

2. Register URL schemes

You need three hosts under your scheme, plus LSApplicationQueriesSchemes on iOS for the wallet schemes you open:

• wallet-callback carries the visible flow’s result.
• wallet-return is Phantom’s “Return to app” tap during the visible flow. It carries no connection data (at most the echoed nonce).
• phantom-headless is Phantom’s “Return to app” tap after a headless connect. It carries no data.

Turn off Flutter’s own deep linking on both platforms. app_links routes every incoming URL, and Flutter’s deep linking would also push each one as a route, stacking a second copy of your home screen on top.

Info.plist (iOS)

<key>CFBundleURLTypes</key>
<array><dict>
  <key>CFBundleURLSchemes</key>
  <array><string>myapp</string></array>
</dict></array>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>metamask</string><string>phantom</string>
  <string>rainbow</string><string>trust</string>
  <string>xverse</string>
</array>
<key>FlutterDeepLinkingEnabled</key>
<false/>

AndroidManifest.xml

<!-- inside your <activity> block -->
<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
<intent-filter android:autoVerify="false">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="myapp" android:host="wallet-callback" />
</intent-filter>
<intent-filter android:autoVerify="false">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="myapp" android:host="phantom-headless" />
</intent-filter>

On Android, wallet-return needs its own activity. It must not reach MainActivity, because resuming the Flutter app makes flutter_web_auth_2 cancel the pending authenticate() while the Custom Tab is still waiting for the WalletConnect approval. Declare it next to MainActivity, and give it its own taskAffinity so the launch does not bring MainActivity’s task forward.

AndroidManifest.xml

<!-- inside <application>, next to your <activity> block -->
<activity
    android:name=".WalletReturnActivity"
    android:exported="true"
    android:taskAffinity="${applicationId}.walletreturn"
    android:launchMode="singleTop"
    android:excludeFromRecents="true"
    android:theme="@android:style/Theme.Translucent.NoTitleBar">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="wallet-return" />
    </intent-filter>
</activity>

WalletReturnActivity.kt

package com.example.myapp // your app's package, next to MainActivity

import android.app.Activity
import android.os.Bundle

/**
 * Receives `myapp://wallet-return`, the zero-payload "Return to app" tap from
 * Phantom's in-app-browser bridge, and does nothing but finish.
 *
 * It must not start or reach MainActivity: flutter_web_auth_2 cancels its
 * pending authenticate() whenever the Flutter app resumes, which would drop the
 * WalletConnect approval still in flight to the open Custom Tab. That tab
 * finishes the flow itself via `myapp://wallet-callback` once the approval lands.
 */
class WalletReturnActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        finish()
    }
}

3. Mount the engine and connect

Wrap your home screen with FireblocksEngineHost. It keeps the hidden WebViewWidget alive at all times. Prewarm at launch and connect on tap. Set FireblocksHeadlessConnect.shared.locale / .theme before prewarm() to override the engine’s UI locale and theme; they are forwarded to the iframe app as query parameters alongside environmentId.

main.dart

MaterialApp(
  home: FireblocksEngineHost(child: ExampleScreen()),
)

example_screen.dart

// prewarm at app start
FireblocksHeadlessConnect.shared.prewarm();

// receive the live wallet list
FireblocksHeadlessConnect.shared.onWallets = (wallets) {
  setState(() => _wallets = wallets);
};

// connect on tap
final result = await FireblocksHeadlessConnect.shared.connect(
  walletKey: 'metamask',
  chain: 'evm', // 'evm', 'solana' or 'bitcoin'
);
switch (result) {
  case ConnectSuccess(:final wallet):
    setState(() => _connection = wallet);
  case ConnectFallbackRequired():
    final w = await FireblocksConnect.connect(
      hostedPageUrl: _hostedPageUrl,
      scheme: _scheme,
      environmentId: AppConfig.environmentId,
    );
    setState(() => _connection = w);
  case ConnectFailure(:final code, :final message):
    setState(() => _error = '[$code] $message');
}

A connection is chain-specific: one wallet gives you an EVM address or a Solana address or a Bitcoin address, never several at once. Read the chains a wallet offers from HeadlessWallet.chains and pass one of them as chain. For Bitcoin, see Bitcoin wallets.

Route deep links with app_links (getInitialLink + uriLinkStream). Ignore wallet-return (on iOS it reaches your app while the visible flow’s session is still waiting for the approval), then hand the URL to FireblocksHeadlessConnect.shared.handleReturnUrl(uri), which consumes phantom-headless. Do not rely on MaterialApp.onGenerateRoute for custom-scheme intents.

main.dart

void _route(Uri uri) {
  if (uri.host.toLowerCase() == 'wallet-return') return;
  if (FireblocksHeadlessConnect.shared.handleReturnUrl(uri)) return;
  // other hosts, e.g. FireblocksWalletBrowser.handleReturnUrl(uri)
}

4. Sign a message

After a successful headless connect, await sign() with any string.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.sign(
  message: 'Sign in to MyApp',
);
switch (result) {
  case SignSuccess(:final value):
    setState(() => _signature = value); // hex for EVM, base64 for Solana and Bitcoin
  case SignFailure(:final error):
    setState(() => _error = '[${error.code}] ${error.message}');
}

Signing is only available for wallets connected through the headless engine (connectedHeadlessly == true). Wallets connected via the visible fallback flow do not hold an open session.

5. Send a transaction (EVM)

sendTransaction() calls eth_sendTransaction: the wallet signs and broadcasts in one step. The result is an on-chain transaction hash. Prefer this over eth_signTransaction, which mobile wallets (including MetaMask) often reject.

The transaction argument is a JSON string whose shape depends on the connected wallet’s chain: EVM transaction fields here, a Bitcoin send request for a Bitcoin wallet (see Send bitcoin). signTransaction() is the sign-only sibling, used mainly for Bitcoin PSBTs.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.sendTransaction(
  transaction:
      '{"to":"${wallet.address}","value":"0x0","data":"0x","chainId":"0x1"}',
);
switch (result) {
  case SendSuccess(:final txHash):
    setState(() => _txHash = txHash); // already broadcast
  case SendFailure(:final error):
    setState(() => _error = '[${error.code}] ${error.message}');
}

chainId is required for send. The engine verifies it against the wallet’s active network and fails with chain_mismatch (or missing_chain_id) rather than silently using whatever network the wallet is on. Treat every send as final: confirm with the user before calling.

6. Bitcoin wallets

Bitcoin reuses the harness above: the same connect(), sign(), sendTransaction() and signTransaction() calls. What changes is the chain you connect with, and the JSON you hand to send and sign.

What you need: an engine deployment whose /headless.html build registers the Bitcoin extension, plus Xverse or Phantom installed on the device. Bitcoin runs on mainnet here, so every send moves real funds.

Connect a Bitcoin wallet

Two routes reach a Bitcoin address, and the wallet list decides between them per wallet:

1. Headless session (Xverse, Phantom). The engine opens a WalletConnect bip122 session and deep-links the wallet. You get a full session: message signing, sends, and PSBT signing all work.
2. Wallet browser (address only). Several Bitcoin wallets inject a provider only inside their own in-app browser and offer no relay path at all. The engine flags those in the wallets bridge message with inAppBrowserChain: 'bitcoin', and the sample offers them as a separate picker entry that runs the visible flow inside that browser. It returns an address and nothing else: there is no session behind it, so signing and sending are unavailable.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.connect(
  walletKey: 'xverse',
  chain: 'bitcoin',
);
switch (result) {
  case ConnectSuccess(:final wallet):
    setState(() => _connection = wallet); // wallet.chain == 'bitcoin'
  case ConnectFallbackRequired():
    // no relay path for this wallet: open the visible flow, or the wallet
    // browser route below
  case ConnectFailure(:final code, :final message):
    setState(() => _error = '[$code] $message');
}

The engine adds the headless bitcoin option itself for the wallets it has a verified bip122 deep link for (Xverse and Phantom today), so HeadlessWallet.chains already contains 'bitcoin' for them. The wallet browser route is the one your list has to offer, gated on the flag the engine sets:

wallet_list.dart

/// Synthetic picker value, never sent to the engine: the Bitcoin route that
/// runs inside the wallet's own in-app browser.
const _walletBrowserBitcoinChain = 'bitcoin-wallet-browser';

/// Offer it only when the engine named the chain for us, and the wallet has
/// no headless Bitcoin path already (Xverse has one, so it never shows here).
bool _offersWalletBrowserBitcoin(HeadlessWallet wallet) =>
    wallet.inAppBrowserUrl != null &&
    wallet.inAppBrowserChain == 'bitcoin' &&
    !wallet.chains.contains('bitcoin');

Wire this helper into your picker alongside the Phantom check in section 8, and route its rows to FireblocksWalletBrowser.connect with chain: 'bitcoin'.

inAppBrowserChain is set only when the wallet’s catalogue entry names a single unambiguous chain for its browser (Xverse: one injected config, chain: "btc"). It is null for a wallet like Phantom whose template is overloaded, which is why Phantom’s EVM browser route stays hand-picked in section 8. Never infer a chain from inAppBrowserUrl alone.

Once the deep link opens, connect() waits up to 3 minutes for the user to approve in the wallet, then fails with ConnectFailure(code: 'timeout'). Switching apps, unlocking a wallet and reading an approval screen takes real time, and a WalletConnect proposal stays valid for about five minutes.

iOS only opens a custom scheme your app has declared. Add xverse to LSApplicationQueriesSchemes (see section 2) or the deep link silently fails to open and the connect falls back.

Sign a message with a Bitcoin wallet

sign() is unchanged. The engine routes the request over the bip122 session, and the wallet returns a base64 signature rather than EVM’s hex string.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.sign(
  message: 'Sign in to MyApp',
);

Before each Bitcoin request the engine deep-links the bare wallet scheme (xverse://) to bring the wallet to the foreground. The request itself travels over the relay either way, but most wallets only render the approval sheet while they are open.

Send bitcoin

sendTransaction() takes a JSON send request instead of EVM transaction fields. The wallet signs and broadcasts, so SendSuccess.txHash is a transaction id that is already in the mempool.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.sendTransaction(
  transaction: json.encode({
    'recipientAddress': 'bc1qexampleaddress…',
    'amountSats': '12345',
  }),
);
switch (result) {
  case SendSuccess(:final txHash):
    setState(() => _txId = txHash); // https://mempool.space/tx/<txHash>
  case SendFailure(:final error):
    setState(() => _error = '[${error.code}] ${error.message}');
}

Field	Required	Description
recipientAddress	Yes	Destination address. The wallet validates it and shows its own confirmation screen before it signs.
amountSats	Yes	Amount in satoshis, as a decimal-digit string (JSON has no big integers). Must be a positive integer.

No chainId applies, and there is no network-switch step: unlike EVM, one Bitcoin wallet session speaks one network.

A Bitcoin send is final and mainnet. Confirm with the user in your own UI before you call, the way the sample does with an alert dialog, and rehearse with a few thousand satoshis rather than a full balance.

Sign a PSBT

signTransaction() signs without broadcasting. For Bitcoin it takes a PSBT and returns the signed PSBT in base64. Finalizing and broadcasting are yours: the engine never submits it.

example_screen.dart

final result = await FireblocksHeadlessConnect.shared.signTransaction(
  transaction: json.encode({
    'unsignedPsbtBase64': psbtBase64,
    'allowedSighash': [1], // 1 = SIGHASH_ALL
    'signature': [
      {
        'address': connection.address, // the connected wallet's own address
        'signingIndexes': [0],
      },
    ],
  }),
);
switch (result) {
  case SignTxSuccess(:final signedTransaction):
    setState(() => _signedPsbt = signedTransaction); // base64 PSBT
  case SignTxFailure(:final code, :final message):
    setState(() => _error = '[$code] $message');
}

Field	Required	Description
unsignedPsbtBase64	Yes	The PSBT to sign, base64.
allowedSighash	Yes	Sighash flags the wallet may sign with. [1] is SIGHASH_ALL. Only the code that built the PSBT knows which flags it used, so the engine never defaults it. Wallets reached over WalletConnect take it as a per-input hint instead of a hard requirement.
signature	Yes	Which inputs belong to the wallet: one entry per address, each with non-empty signingIndexes.

signature is not optional bookkeeping. Wallets derive the inputs to sign straight from it and sign nothing when it is empty, which returns a “signed” PSBT the wallet never touched. The engine parses no PSBTs of its own, so it rejects the request instead: every entry must name the connected wallet’s own address (its payment or ordinals address) with at least one index.

Bitcoin error codes

SignTxFailure.code and SendFailure.error.code carry these on the Bitcoin paths:

Code	Where	Meaning
missing_recipient	send	recipientAddress absent.
invalid_amount	send	amountSats is not a positive integer string.
missing_psbt	sign	unsignedPsbtBase64 absent.
missing_allowed_sighash	sign	allowedSighash absent, on a wallet the engine drives through the Dynamic SDK.
missing_signature_indexes	sign	signature names no owned address with a non-empty signingIndexes.
invalid_psbt	sign	The wallet or SDK rejected the PSBT itself.
transaction_required	sign, send	The request reached the wallet with no transaction attached.
broadcast_failed	send	Signed, but the network refused the broadcast (fees, conflicting spend).
unsupported_chain	sign, send	The connected wallet is not EVM, Solana, or Bitcoin.
no_wallet	sign, send	No live headless session. A wallet browser connection is address-only, so it lands here.
timeout	connect, sign, send	The wallet never answered: 3 minutes for a connect approval, 60 seconds to sign, 120 for a send.

7. Connect Phantom

Connect Phantom on EVM or Solana with the same call as any other wallet: FireblocksHeadlessConnect.shared.connect(walletKey: 'phantom', chain: 'evm') or chain: 'solana'. Phantom has no WalletConnect entry in Dynamic’s wallet book, so the engine bridges through Phantom’s own in-app browser:

1. The engine mints a WalletConnect pairing and sends a deeplink that opens your hosted page inside Phantom.
2. The page approves the pairing with Phantom’s injected provider, and the engine receives the connection over the WalletConnect relay.
3. Phantom’s “Return to app” button opens <scheme>://phantom-headless with no payload. FireblocksHeadlessConnect.shared.handleReturnUrl consumes it, and your connect future completes with the result from the engine.

No connection data comes back through your URL scheme. The engine offers a chain only when your Dynamic environment has a network enabled for it, and it fails with timeout if Phantom does not approve within 60 seconds.

8. Use a wallet’s own browser (Phantom on EVM)

Phantom injects its EVM provider (window.phantom.ethereum) only inside its own in-app browser. To sign or send with it, open your hosted page inside Phantom’s browser: connect there, then reopen the same browser for each sign or send.

Each operation is one round trip: Phantom comes to the foreground with your page in it, the user approves, and the result arrives on <scheme>://wallet-browser.

The engine reports each wallet’s in-app-browser template in the wallets bridge message as inAppBrowser. The template contains {{encodedDappURI}}, and you replace every occurrence (Phantom’s uses it twice). A template is not a chain: it only means the wallet can open a URL in its own browser, so you decide per wallet which chains that browser serves.

View fireblocks_wallet_browser.dart (copy-paste ready)

fireblocks_wallet_browser.dart

import 'dart:async';
import 'dart:math';

import 'package:flutter/foundation.dart';
import 'package:url_launcher/url_launcher.dart';

import 'fireblocks_connect.dart' show FireblocksConnectCancelled, FireblocksConnectError;
import 'models.dart';

/// Drives the hosted visible flow **inside a wallet's own in-app browser**.
///
/// ## Why this exists (and why it isn't [FireblocksConnect])
///
/// [FireblocksConnect] opens the hosted page in the SYSTEM browser
/// (`flutter_web_auth_2` → Chrome Custom Tabs / ASWebAuthenticationSession).
/// That works for any wallet reachable by WalletConnect, a deeplink, or an SDK
/// (Base Account). It cannot work for a wallet whose only mobile surface for a
/// given chain is the provider it injects into its OWN browser — because that
/// provider simply isn't there in the system browser.
///
/// Phantom on EVM is exactly that case, and it's why "Phantom EVM" never
/// worked here: no `phantom*` wallet-book entry has a WalletConnect block, and
/// `phantomevm` carries no mobile deeplink at all — its only surface is
/// `window.phantom.ethereum`, injected inside Phantom's in-app browser (see
/// `classifyChain`'s doc comment in `src/redirect.ts`). So the page has to be
/// opened THERE, and the result handed back to this app over its custom
/// scheme.
///
/// The example app no longer routes Phantom EVM connect here: the visible flow
/// now bridges into Phantom's in-app browser itself and gets the approval back
/// over WalletConnect (see `startPhantomInAppBrowserConnect` in `src/App.tsx`).
///
/// ## Mechanics
///
/// 1. Build the hosted-page URL (`?wallet=…&chain=evm`, or an
///    `?intent=signMessage|sendTx` variant) with
///    `redirect_uri=<scheme>://[callbackHost]` and a fresh nonce.
/// 2. Wrap it in the wallet's in-app-browser template (`{{encodedDappURI}}`,
///    replaced everywhere — Phantom's uses it twice) and hand it to the OS.
///    The template comes from the engine's wallet catalogue
///    ([HeadlessWallet.inAppBrowserUrl]), i.e. from Dynamic's wallet book —
///    never hard-coded here.
/// 3. The wallet opens its browser on the page, the user connects/signs with
///    the injected provider, and the page redirects to
///    `<scheme>://[callbackHost]?…`.
/// 4. That link arrives through `app_links` (NOT through `flutter_web_auth_2`,
///    which only intercepts callbacks inside its own session — this is why the
///    callback host must differ from the visible flow's `wallet-callback`, and
///    why [handleReturnUrl] has to be wired up in `main.dart`).
///
/// ## Caveats worth knowing before you ship this
///
/// - The hand-off in step 2 is an `https` universal/app link. It reaches the
///   wallet only if the OS routes that domain to the wallet app: iOS honours
///   universal links from `UIApplication.open`, but on Android an unverified
///   app link can land in Chrome instead — where the wallet injects nothing
///   and the page correctly reports that the wallet has no path for this
///   chain. "No connection path" seen in a browser that ISN'T the wallet means
///   the hand-off went to the wrong app, not that the wallet can't do it.
/// - Whether a wallet's browser honours a custom-scheme navigation is the
///   wallet's choice, not ours. The hosted page always ALSO renders a "Return
///   to the app" anchor for custom-scheme targets (a real tap is the reliable
///   path where a programmatic navigation is ignored), so the user has a way
///   back either way.
/// - Nothing here is silent: expect the wallet app to come to the foreground
///   with a web page in it, plus the wallet's own approval prompt.
abstract final class FireblocksWalletBrowser {
  /// Host of the callback URL this flow listens for — deliberately NOT
  /// `wallet-callback`, which `flutter_web_auth_2`'s `CallbackActivity` claims
  /// on Android for the system-browser flow. A link arriving from the wallet's
  /// app has no `flutter_web_auth_2` session to belong to, so it must be
  /// delivered as a plain app link and routed here instead.
  static const callbackHost = 'wallet-browser';

  /// How long to wait for the return link before giving up. The user is in
  /// another app for this whole window (connect, approve, come back), so this
  /// is generous by design; it exists so an abandoned flow can't leave a
  /// [Future] pending for the process lifetime.
  static const timeout = Duration(minutes: 5);

  static _Pending? _pending;

  /// Connect [walletKey] on [chain] inside the wallet's own browser.
  ///
  /// [walletBrowserUrl] — the wallet's in-app-browser template, from
  /// [HeadlessWallet.inAppBrowserUrl].
  /// [hostedPageUrl] / [scheme] / [environmentId] / [locale] / [theme] — as
  /// [FireblocksConnect.connect].
  ///
  /// The returned [WalletConnection] carries [WalletConnection.walletBrowserUrl]
  /// so later sign/send calls can be routed back into the same browser — the
  /// connection lives with that injected provider and nowhere else.
  static Future<WalletConnection> connect({
    required String hostedPageUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    String chain = 'evm',
    String environmentId = '',
    String locale = '',
    String theme = '',
  }) async {
    final callback = await _run(
      hostedPageUrl: hostedPageUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      locale: locale,
      theme: theme,
      params: {'wallet': walletKey, 'chain': chain},
    );
    final address = callback.uri.queryParameters['address'] ?? '';
    if (address.isEmpty) {
      throw const FireblocksConnectError('No address in callback URL');
    }
    return WalletConnection(
      address: address,
      chain: callback.uri.queryParameters['chain'] ?? chain,
      walletName: callback.uri.queryParameters['walletName'] ?? '',
      walletImage: callback.uri.queryParameters['walletImage'] ?? '',
      connectedHeadlessly: false,
      walletKey: walletKey,
      walletBrowserUrl: walletBrowserUrl,
    );
  }

  /// Sign [message] with a wallet connected through [connect].
  ///
  /// [expectedAddress] is REQUIRED and checked by the page itself: the page
  /// connects again inside the wallet's browser before signing, and without
  /// this it would sign with whatever account happens to connect.
  static Future<SignResult> signMessage({
    required String hostedPageUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    required String message,
    required String expectedAddress,
    String environmentId = '',
    String locale = '',
    String theme = '',
  }) async {
    final callback = await _run(
      hostedPageUrl: hostedPageUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      locale: locale,
      theme: theme,
      params: {
        'intent': 'signMessage',
        'walletKey': walletKey,
        'message': message,
        'expectedAddress': expectedAddress,
      },
    );
    if (callback.uri.queryParameters['error'] == '1') {
      return SignFailure(SignError(
        code: callback.uri.queryParameters['code'] ?? 'unknown',
        message: callback.uri.queryParameters['message'] ?? '',
      ));
    }
    final signature = callback.uri.queryParameters['signature'] ?? '';
    if (signature.isEmpty) {
      throw const FireblocksConnectError('No signature in callback URL');
    }
    return SignSuccess(signature);
  }

  /// Send an EVM transaction with a wallet connected through [connect].
  ///
  /// [to] / [chainId] / [value] / [data] / [gasLimit] are `0x`-prefixed hex,
  /// same contract as [FireblocksConnect.sendTransaction]. The wallet signs
  /// AND broadcasts: a [SendSuccess] is already on-chain.
  static Future<SendResult> sendTransaction({
    required String hostedPageUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String walletKey,
    required String to,
    required String chainId,
    required String expectedAddress,
    String value = '0x0',
    String data = '0x',
    String? gasLimit,
    String environmentId = '',
    String locale = '',
    String theme = '',
  }) async {
    final callback = await _run(
      hostedPageUrl: hostedPageUrl,
      scheme: scheme,
      walletBrowserUrl: walletBrowserUrl,
      environmentId: environmentId,
      locale: locale,
      theme: theme,
      params: {
        'intent': 'sendTx',
        'walletKey': walletKey,
        'to': to,
        'value': value,
        'data': data,
        'chainId': chainId,
        if (gasLimit != null) 'gasLimit': gasLimit,
        'expectedAddress': expectedAddress,
      },
    );
    if (callback.uri.queryParameters['error'] == '1') {
      return SendFailure(SignError(
        code: callback.uri.queryParameters['code'] ?? 'unknown',
        message: callback.uri.queryParameters['message'] ?? '',
      ));
    }
    final txHash = callback.uri.queryParameters['txHash'] ?? '';
    if (txHash.isEmpty) {
      throw const FireblocksConnectError('No txHash in callback URL');
    }
    return SendSuccess(txHash, chain: 'evm');
  }

  /// Feed an inbound deep link to this flow. Returns `true` when the URL was
  /// this flow's callback (consumed, whether or not a request was waiting for
  /// it), so callers can chain handlers:
  ///
  /// ```dart
  /// if (FireblocksHeadlessConnect.shared.handleReturnUrl(uri)) return;
  /// FireblocksWalletBrowser.handleReturnUrl(uri);
  /// ```
  static bool handleReturnUrl(Uri uri) {
    if (uri.host.toLowerCase() != callbackHost) return false;
    final pending = _pending;
    if (pending == null) {
      debugPrint('[FireblocksWalletBrowser] callback with no request in flight: $uri');
      return true;
    }
    // Nonce mismatch is NOT completed as a failure: a stale callback (the
    // user re-opened an old page in the wallet's browser) must not resolve
    // the request that IS in flight. Drop it and keep waiting.
    if (uri.queryParameters['nonce'] != pending.nonce) {
      debugPrint('[FireblocksWalletBrowser] dropped callback with mismatched nonce');
      return true;
    }
    _pending = null;
    pending.timer.cancel();
    if (!pending.completer.isCompleted) {
      pending.completer.complete(_Callback(uri));
    }
    return true;
  }

  /// Abandon the in-flight request (e.g. the user navigated away in this app).
  /// Its [Future] completes with [FireblocksConnectCancelled].
  static void cancel() => _abandon(const FireblocksConnectCancelled());

  // MARK: – Private

  static Future<_Callback> _run({
    required String hostedPageUrl,
    required String scheme,
    required String walletBrowserUrl,
    required String environmentId,
    String locale = '',
    String theme = '',
    required Map<String, String> params,
  }) async {
    // One request at a time — the callback carries no request id beyond its
    // nonce, and two overlapping flows in the same wallet browser would race
    // for the same return link.
    _abandon(const FireblocksConnectCancelled());

    final nonce = _randomHex(16);
    final base = Uri.parse(hostedPageUrl);
    final pageUrl = base.replace(queryParameters: {
      ...base.queryParameters,
      ...params,
      'redirect_uri': '$scheme://$callbackHost',
      'nonce': nonce,
      // The page runs inside a wallet's WebView here — tell it so explicitly
      // rather than leaving it to user-agent guessing (see `getEnvInfo` in
      // `src/env.ts`): among other things this stops it offering a deeplink
      // connector that would try to bounce out of that browser.
      'embedded': '1',
      // Tells the page it's ALREADY inside walletKey's own browser (see
      // App.tsx's openedInsideWalletBrowser doc comment) — so if the
      // provider still isn't detected, it shows a clear message on THIS
      // load instead of re-offering the same in-app-browser link (which,
      // tapped from inside that browser, is a dead loop).
      'walletBrowser': '1',
      if (environmentId.isNotEmpty) 'environmentId': environmentId,
      if (locale.isNotEmpty) 'locale': locale,
      if (theme.isNotEmpty) 'theme': theme,
    }).toString();

    // Some templates (Phantom's) use the placeholder more than once — as both
    // the browse target and the `ref` — so replace every occurrence.
    final target = Uri.tryParse(
      walletBrowserUrl.replaceAll('{{encodedDappURI}}', Uri.encodeComponent(pageUrl)),
    );
    if (target == null) {
      throw FireblocksConnectError('Unusable in-app-browser URL: $walletBrowserUrl');
    }

    final completer = Completer<_Callback>();
    final timer = Timer(timeout, () => _abandon(const FireblocksConnectCancelled()));
    _pending = _Pending(nonce: nonce, completer: completer, timer: timer);

    var opened = false;
    try {
      opened = await launchUrl(target, mode: LaunchMode.externalApplication);
    } catch (_) {
      opened = false;
    }
    if (!opened) {
      _abandon(FireblocksConnectError(
        'Could not open the wallet app for $target — is it installed?',
      ));
    }
    return completer.future;
  }

  /// Fail/cancel the in-flight request, if any, with [error].
  static void _abandon(Exception error) {
    final pending = _pending;
    if (pending == null) return;
    _pending = null;
    pending.timer.cancel();
    if (!pending.completer.isCompleted) {
      pending.completer.completeError(error);
    }
  }

  static String _randomHex(int bytes) {
    final rng = Random.secure();
    return List.generate(bytes, (_) => rng.nextInt(256))
        .map((b) => b.toRadixString(16).padLeft(2, '0'))
        .join();
  }
}

class _Pending {
  final String nonce;
  final Completer<_Callback> completer;
  final Timer timer;
  const _Pending({required this.nonce, required this.completer, required this.timer});
}

class _Callback {
  final Uri uri;
  const _Callback(this.uri);
}

Carry the two extra fields

HeadlessWallet needs the template, and WalletConnection needs to remember it. Add both to your models, and keep walletBrowserUrl in copyWith, or sign and send fall back to the engine. inAppBrowserChain marks a wallet’s in-app browser as Bitcoin-only, as described in section 6.

models.dart

class HeadlessWallet {
  /// The wallet's own in-app-browser template, or `null` if it has none.
  final String? inAppBrowserUrl;

  /// The chain [inAppBrowserUrl] is for, when the engine can identify one.
  final String? inAppBrowserChain;

  // …parsed from the bridge message:
  // inAppBrowserUrl: json['inAppBrowser'] as String?,
  // inAppBrowserChain: json['inAppBrowserChain'] as String?,
}

class WalletConnection {
  /// Set when the connection was made inside the wallet's browser.
  final String? walletBrowserUrl;
}

Register the callback host

Add another host to your scheme, next to wallet-callback, wallet-return, and phantom-headless. On iOS your existing CFBundleURLSchemes entry already covers it.

AndroidManifest.xml

<intent-filter android:autoVerify="false">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="myapp" android:host="wallet-browser" />
</intent-filter>

Route the link in your app_links listener, for both the cold start link and the stream. flutter_web_auth_2 never picks this up, because there is no session it belongs to.

main.dart

void _route(Uri uri) {
  if (uri.host.toLowerCase() == 'wallet-return') return;
  if (FireblocksHeadlessConnect.shared.handleReturnUrl(uri)) return;
  FireblocksWalletBrowser.handleReturnUrl(uri);
}

Offer the option only for Phantom

Do not derive EVM support from the presence of a template. Phantom’s template comes from its Sui wallet-book entry, so a template on its own says nothing about EVM. The evidence for Phantom specifically is phantomevm.injectedConfig.windowLocations: ["phantom.ethereum"], an EIP-1193 provider inside its browser.

wallet_list.dart

List<String> _chains(HeadlessWallet wallet) => [
      ...wallet.chains,
      if (_offersWalletBrowserEvm(wallet)) 'evm',
    ];

/// Scoped to Phantom on purpose, and NOT derived from "has an in-app-browser
/// template" — a template only means the wallet can open a URL in its own
/// browser; it says nothing about which chains that browser injects a
/// provider for. The evidence for Phantom specifically is
/// `phantomevm.injectedConfig.windowLocations: ["phantom.ethereum"]`.
bool _offersWalletBrowserEvm(HeadlessWallet wallet) =>
    wallet.key.toLowerCase() == 'phantom' &&
    wallet.inAppBrowserUrl != null &&
    !wallet.chains.contains('evm');

Show it as its own chain row with “Opens in the wallet’s own browser” underneath. The current engine already lists evm in Phantom’s chains and connects it headlessly (Connect Phantom), so the !wallet.chains.contains('evm') guard keeps the synthetic row from doubling it: it only appears for engines that predate the headless bridge, or if you want the row to route into the wallet-browser connect below instead, which is what signing needs. A headless Phantom connection is connect-only.

Connect, sign, and send

example_screen.dart

// connect inside the wallet's browser: the connection carries
// walletBrowserUrl, which is what sign and send reopen
final connection = await FireblocksWalletBrowser.connect(
  hostedPageUrl: hostedPageUrl,
  scheme: scheme,
  walletBrowserUrl: wallet.inAppBrowserUrl!,
  walletKey: wallet.key,
);

// sign and send: reopen the SAME browser
final template = connection.walletBrowserUrl;
if (template != null) {
  final signed = await FireblocksWalletBrowser.signMessage(
    hostedPageUrl: hostedPageUrl,
    scheme: scheme,
    walletBrowserUrl: template,
    walletKey: connection.walletKey!,
    message: 'Hello from Flutter',
    expectedAddress: connection.address,  // the page refuses a mismatch
  );

  final sent = await FireblocksWalletBrowser.sendTransaction(
    hostedPageUrl: hostedPageUrl,
    scheme: scheme,
    walletBrowserUrl: template,
    walletKey: connection.walletKey!,
    to: '0xRecipientAddress',
    chainId: '0x1',
    value: '0x2386f26fc10000',      // 0.01 ETH, hex wei
    expectedAddress: connection.address,
  );
}

What travels on the URL

Parameter	Value
wallet and chain=evm	connect, or intent=signMessage / intent=sendTx with walletKey
redirect_uri	<scheme>://wallet-browser
nonce	random per attempt, verified on return, mismatches dropped
embedded=1	the page is inside a wallet web view, so it must not offer a connector that bounces out of it
environmentId	optional Dynamic environment ID

The callback carries address and chain (connect), signature (sign), or txHash (send), or error=1&code=&message=, always with the nonce echoed back. A send is already broadcast when the hash arrives. One request is in flight at a time, a new one supersedes the previous, and an abandoned one times out after five minutes.

Phantom pitfalls

• Keep the template on the connection. Sign and send must reopen the same browser, because the account exists nowhere else. Losing the stored template sends the request to the engine, which reports no wallet connected.
• Use a separate callback host. wallet-callback is claimed by the visible flow, so a link arriving from Phantom would be dropped or complete an unrelated request.
• Watch where the template lands on Android. The template is an https app link and reaches Phantom only if its app links are verified. Otherwise Android can hand it to Chrome, where nothing is injected and the page correctly reports no EVM path. That message in a browser that is not Phantom means the hand-off went to the wrong app.
• Offer the return anchor. The page renders a “Return to the app” link for browsers that ignore a programmatic redirect.

9. Disconnect

Clears localStorage in the hidden WebView and reloads the engine so stale SDK state does not bleed into the next connect.

example_screen.dart

await FireblocksHeadlessConnect.shared.disconnect();
setState(() => _connection = null);

10. The bridge (for reference)

Flutter uses addJavaScriptChannel('walletNative', …) which creates window.walletNative.postMessage(json). The channel name must match exactly.

bridge messages

// web → app (connect)   request-scoped messages carry requestId
ready                                      engine initialized
wallets    { wallets: […] }                the wallet menu (live)
deeplink   { requestId, url }              app opens the wallet
openWallet { requestId?, url }             wakes the wallet for a pending request
connected  { requestId, address, chain, … } success
fallback   { requestId, reason }           can't go headless → visible flow
error      { requestId, code, message }    failed
event      { requestId?, event, sessionId, t }  diagnostic timeline

// web → app (sign)
signed     { requestId, signature }        message signed (hex string)
signFailed { requestId, code, message }    sign failed
signedTx   { requestId, signedTransaction, chain }  EVM, Solana, or Bitcoin tx signed; Bitcoin returns a signed PSBT
signTxFailed { requestId, code, message }           tx sign failed

// app → web
window.headlessConnect.connect({ requestId, walletKey, chain })
window.headlessConnect.cancel(requestId)
window.headlessConnect.sign({ requestId, message })
window.headlessConnect.signTx({ requestId, transaction }) // EVM, Solana, or Bitcoin sign-only; Bitcoin returns a signed PSBT
window.headlessConnect.sendTx({ requestId, transaction }) // EVM, Solana, or Bitcoin sign+broadcast

Common pitfalls

• Match the channel name exactly: walletNative. A mismatch is invisible; the channel just never receives anything.
• Use app_links for Phantom returns, not onGenerateRoute.
• Test on a physical device.
• Serve over HTTPS.