@reown/appkit-controllers/dist/types/src/utils/HeadlessWalletUtil.d.ts

The full stack toolkit to build onchain app UX.

import type { ChainNamespace } from '@reown/appkit-common';
import { type WalletItem } from './ConnectUtil.js';
/** Options for {@link HeadlessWalletUtil.fetchWallets}. */
export interface FetchWalletsOptions {
    /** Page number to fetch (default: 1) */
    page?: number;
    /** @deprecated Use `search` instead */
    query?: string;
    /** Search query to filter wallets. When provided, switches to search mode. */
    search?: string;
    /** Number of entries per page. Defaults to 40 for list mode, 100 for search mode. */
    entries?: number;
    /** Filter wallets by badge type ('none' | 'certified') */
    badge?: 'none' | 'certified';
    /** Wallet IDs to include. Overrides the global includeWalletIds config when provided. */
    include?: string[];
    /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
    exclude?: string[];
    /**
     * Include wallets that support WalletConnect Pay but are not v2-compatible.
     * By default these are filtered out. Enable for WalletConnect Pay surfaces.
     */
    includePayOnly?: boolean;
    /** Sort mode. 'wcpay' bubbles WalletConnect Pay-supporting wallets to the top. */
    sort?: 'default' | 'wcpay';
}
/** Options for {@link HeadlessWalletUtil.connect} / {@link HeadlessWalletUtil.prefetchWalletConnectUri}. */
export interface ConnectOptions {
    /**
     * A WalletConnect Pay deeplink appended to the WC URI, so a WCPay-capable wallet
     * returns to — and processes — this payment after pairing.
     */
    wcPayUrl?: string;
}
/** The headless wallet list, read imperatively. */
export interface WalletListSnapshot {
    /** Initial connect-view wallets: installed extensions + top-ranked WalletConnect wallets. */
    wallets: WalletItem[];
    /** The full WalletGuide WalletConnect list (with the current search results applied). */
    wcWallets: WalletItem[];
    /** Current page of the WalletConnect list. */
    page: number;
    /** Total number of available WalletConnect wallets for the current parameters. */
    count: number;
}
/** The WalletConnect URI + connection-attempt signals, read imperatively. */
export interface WalletConnectUriSnapshot {
    /** Active WalletConnect pairing URI (for rendering a QR / deeplink), or undefined when none. */
    wcUri: string | undefined;
    /** Whether the last WalletConnect URI fetch / connection attempt errored. */
    wcError: boolean;
    /** Whether a WalletConnect URI is currently being fetched. */
    wcFetchingUri: boolean;
}
/**
 * Framework-agnostic headless wallet-list logic — the imperative core behind the
 * `useAppKitWallets` React hook and the `AppKit` client's wallet methods.
 *
 * AppKit runs headless (no modal): the host renders its own picker and connects a
 * chosen wallet programmatically. That orchestration (list / search / paginate the
 * WalletGuide wallets, fetch the WalletConnect URI, and connect injected / API / mobile
 * wallets) lived only inside the React hook; lifting it here lets a non-React host
 * (e.g. `@walletconnect/pay-appkit`) drive the same flow through `appKit.*` methods,
 * with the hook and the client sharing one tested code path.
 *
 * Reads/writes the global controllers directly (valtio singletons), so it takes no
 * AppKit instance — exactly like {@link ConnectionControllerUtil}.
 */
export declare const HeadlessWalletUtil: {
    /**
     * Fetch / search / paginate the WalletConnect wallet list from the explorer API.
     * With a `search` (or the deprecated `query`), switches to search mode; otherwise
     * lists/paginates. Reads results from `ApiController.state` (see {@link getWalletList}).
     */
    fetchWallets(fetchOptions?: FetchWalletsOptions): Promise<void>;
    /** Read the current wallet list (initial view + WalletConnect list + pagination). */
    getWalletList(): WalletListSnapshot;
    /** Subscribe to wallet-list changes (the WalletGuide list + search results). */
    subscribeWalletList(callback: () => void): () => void;
    /**
     * Pre-fetch the WalletConnect URI. Read the result with {@link getWalletConnectUri};
     * subscribe with {@link subscribeWalletConnectUri}. Call when a wallet is selected so a
     * later connect can deeplink synchronously (required for iOS Safari) or render a QR. Uses
     * 'auto' cache to reuse a valid URI or fetch a new one.
     */
    prefetchWalletConnectUri(_options?: ConnectOptions): Promise<void>;
    /**
     * Read the current WalletConnect URI state (the QR / deeplink URI plus the fetch/error
     * signals) — the symmetric read for {@link prefetchWalletConnectUri}. Reads
     * `ConnectionController` directly, so a headless host gets it ungated through the AppKit
     * instance without importing the controllers package.
     */
    getWalletConnectUri(): WalletConnectUriSnapshot;
    /**
     * Subscribe to WalletConnect URI state changes (wcUri / wcError / wcFetchingUri). The
     * callback receives no arguments — read the current values with {@link getWalletConnectUri}.
     * Returns an unsubscribe.
     */
    subscribeWalletConnectUri(callback: () => void): () => void;
    /**
     * Connect a chosen wallet programmatically (headless — no modal).
     *
     * Handles injected wallets, API wallets (from the "all wallets" list), and mobile
     * deeplinks. For API wallets without pre-populated connectors, falls back to a lookup
     * by the wallet's ID via `explorerId` matching (e.g. Coinbase/Base from "all wallets").
     */
    connect(wallet: WalletItem, namespace?: ChainNamespace, options?: ConnectOptions): Promise<void>;
    /** Reset the WalletConnect URI + linking state (e.g. when a QR is closed). */
    resetWcUri(): void;
    /** Clear the `connectingWallet` state. */
    resetConnectingWallet(): void;
};