Global Wallet Native API

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

The Global Wallet Native API provides a direct interface for interacting with and managing global wallets without requiring any wallet SDK. This API is designed for:

App developers who want to integrate global wallet functionality
Wallet developers who need to create custom wallet interfaces

Quick Start

The API is available through the @dynamic-labs/global-wallet-client/features entry point. Here’s a simple example to get started:

import { createGlobalWalletClient } from '@dynamic-labs/global-wallet-client';
import { connect, onEvent } from '@dynamic-labs/global-wallet-client/features'

// Initialize your wallet client
const Wallet = createGlobalWalletClient({ ... });

// Listen for connection events
onEvent(Wallet, 'connect', () => {
  console.log("Wallet connected successfully!");
});

// Connect the wallet
connect(Wallet);

Implementation Options

When creating your global wallet package, you have two implementation approaches:

1. Native API Interface (Recommended)

This approach leverages the @dynamic-labs/global-wallet-client package to re-export all native APIs through the features entry point. Benefits include:

Simpler maintenance
Automatic feature updates
Consistent API across the ecosystem

To implement this approach, follow the package creation guide.

2. Custom Interface

You can create a custom interface using the Global Wallet Native API. This gives you complete control over the API design:

// <your package>/src/index.ts
import { createGlobalWalletClient } from '@dynamic-labs/global-wallet-client';
import { connect, disconnect } from '@dynamic-labs/global-wallet-client/features'

const Wallet = createGlobalWalletClient({ ... });

const MyCustomWalletInterface = {
  connect() {
    return connect(Wallet);
  },
  disconnect() {
    return disconnect(Wallet);
  },
  get wallets() {
    return Wallet.wallets;
  },
  // Add your custom methods here
}

Complete Integration Example

Let’s walk through a complete React integration example using a fictional wallet called “Droplet”:

import Droplet, { connect, disconnect } from 'droplet-wallet';
import { createEIP1193Provider } from 'droplet-wallet/ethereum'
import { useState, useEffect } from 'react';
import { createWalletClient, custom, Hex } from 'viem';

const App = () => {
  const [isConnected, setIsConnected] = useState<boolean>(!!Droplet.wallets.length);

  // Handle connection events
  useEffect(() => {
    return onEvent(Droplet, 'connect', () => setIsConnected(true))
  }, [setIsConnected]);

  useEffect(() => {
    return onEvent(Droplet, 'disconnect', () => setIsConnected(false))
  }, [setIsConnected]);

  // Display connect button when disconnected
  if (!isConnected) {
    return (
      <button onClick={() => connect(Droplet)}>
        Connect with Droplet
      </button>
    )
  }

  // Display connected wallet interface
  return (
    <div>
      {Droplet.wallets.map(wallet => {
        const provider = createEIP1193Provider(wallet);

        const walletClient = createWalletClient({
          account: wallet.address as Hex,
          transport: custom(provider)
        });

        return (
          <button
            key={wallet.id}
            onClick={() => {
              walletClient.signMessage({
                message: 'Hello from Droplet'
              })
            }}
          >
            Sign message "Hello from Droplet"
          </button>
        )
      })}
    </div>
  )
}

Provider Integration

Viem Integration

import Droplet from 'droplet-wallet';
import { createWalletClient, custom, Hex } from 'viem';

const provider = createEIP1193Provider(wallet);

const walletClient = createWalletClient({
  account: wallet.address as Hex,
  transport: custom(provider)
});

Ethers.js Integration

import Droplet from 'droplet-wallet';
import { ethers } from 'ethers';

const provider = createEIP1193Provider(wallet);
const ethersProvider = new ethers.BrowserProvider(provider);

API Reference

Core Methods

`connect`

Connects the global wallet to your dapp via a pop-up interface.

import Wallet, { connect } from 'wallet';

const connectedWallets = await connect(Wallet);

Parameters:

client: GlobalWalletClient – The global wallet client instance

Returns:

Promise<Array<BaseWallet>> – List of connected wallet objects

`disconnect`

Disconnects the global wallet and emits a disconnect event.

import Wallet, { disconnect, onEvent } from 'wallet';

onEvent(Wallet, 'disconnect', () => {
  console.log('Wallet disconnected');
});

disconnect(wallet);

Parameters:

client: GlobalWalletClient – The global wallet client instance

Wallet Management

`getEthereumWallets`

Retrieves all connected Ethereum wallets. Parameters:

client: GlobalWalletClient – The global wallet client instance

Returns:

Array<BaseWallet> – Array of Ethereum wallets

`getSolanaWallets`

Retrieves all connected Solana wallets. Parameters:

client: GlobalWalletClient – The global wallet client instance

Returns:

Array<BaseWallet> – Array of Solana wallets

Network Management

`getSupportedEthereumNetworks`

Returns supported Ethereum networks. Parameters:

client: GlobalWalletClient – The global wallet client instance

Returns:

Array<{ chainId: number; rpcUrl?: string }> – Supported networks

`getWalletNetwork`

Returns the current network for a specific wallet. Parameters:

wallet: BaseWallet – The wallet to check

Returns:

number | string | null – Network ID or name

Account Abstraction

`createKernelClient`

Creates a kernel account client for a given wallet. Parameters:

wallet: BaseWallet – The smart wallet to create the kernel account client for
chainId?: number – The chain ID to use for the kernel account client
bundlerProvider?: ZerodevBundlerProvider – The bundler provider to use for the kernel account client
bundlerRpc?: string – The bundler RPC URL to use for the kernel account client
paymasterRpc?: string – The paymaster RPC URL to use for the kernel account client
paymaster?: PaymasterType (‘SPONSOR’ | ‘NONE’) – The paymaster to use for the kernel account client

Returns:

KernelAccountClient<Transport, ViemChain, SmartAccount, Client, RpcSchema> – The kernel account client

`getEoaWalletForSmartWallet`

Retrieves the EOA wallet for a given smart address address. Parameters:

smartWallet: BaseWallet – The smart wallet to get the EOA for

Returns:

BaseWallet – The EOA wallet

Utility Methods

`isEthereumWallet`

Checks if a wallet is Ethereum-based. Parameters:

wallet: BaseWallet – The wallet to check

Returns:

boolean – true if Ethereum-based

`isSolanaWallet`

Checks if a wallet is Solana-based. Parameters:

wallet: BaseWallet – The wallet to check

Returns:

boolean – true if Solana-based

`onEvent`

Attaches an event listener to the global wallet client.

import Wallet, { onEvent } from 'wallet';

const unsubscribe = onEvent(Wallet, 'connect', () => {
  console.log('Connected!');
});

// Clean up
unsubscribe();

Parameters:

client: GlobalWalletClient – The global wallet client instance
eventName: keyof ClientEventEmitterEvents – Event name
callback: Function – Event handler

Returns:

VoidFunction – Unsubscribe function

`signMessage`

Signs a message using the wallet.

import Wallet from 'wallet';

const { signature, signedMessage } = await signMessage(Wallet.wallets[0], {
  message: 'Hello, world!',
});

Parameters:

wallet: BaseWallet – The wallet to use
message: string – Message to sign

Returns:

Promise<{ signature: string; signedMessage: string }> – Signature details

`switchNetwork`

Switches an Ethereum wallet’s network.

import Wallet from 'wallet';

const wallet = Wallet.wallets[0];
switchNetwork(wallet, { networkId: 1 });

Parameters:

wallet: BaseWallet – The wallet to switch
networkId: number – Target network ID

Implementation Guides

SDK Reference

Global Wallet Native API

Recommended: JavaScript SDK with React Hooks

Quick Start

Implementation Options

1. Native API Interface (Recommended)

2. Custom Interface

Complete Integration Example

Provider Integration

Viem Integration

Ethers.js Integration

API Reference

Core Methods

`connect`

`disconnect`

Wallet Management

`getEthereumWallets`

`getSolanaWallets`

Network Management

`getSupportedEthereumNetworks`

`getWalletNetwork`

Account Abstraction

`createKernelClient`

`getEoaWalletForSmartWallet`

Utility Methods

`isEthereumWallet`

`isSolanaWallet`

`onEvent`

`signMessage`

`switchNetwork`

Recommended: JavaScript SDK with React Hooks

​Quick Start

​Implementation Options

​1. Native API Interface (Recommended)

​2. Custom Interface

​Complete Integration Example

​Provider Integration

​Viem Integration

​Ethers.js Integration

​API Reference

​Core Methods

​connect

​disconnect

​Wallet Management

​getEthereumWallets

​getSolanaWallets

​Network Management

​getSupportedEthereumNetworks

​getWalletNetwork

​Account Abstraction

​createKernelClient

​getEoaWalletForSmartWallet

​Utility Methods

​isEthereumWallet

​isSolanaWallet

​onEvent

​signMessage

​switchNetwork

Quick Start

Implementation Options

1. Native API Interface (Recommended)

2. Custom Interface

Complete Integration Example

Provider Integration

Viem Integration

Ethers.js Integration

API Reference

Core Methods

`connect`

`disconnect`

Wallet Management

`getEthereumWallets`

`getSolanaWallets`

Network Management

`getSupportedEthereumNetworks`

`getWalletNetwork`

Account Abstraction

`createKernelClient`

`getEoaWalletForSmartWallet`

Utility Methods

`isEthereumWallet`

`isSolanaWallet`

`onEvent`

`signMessage`

`switchNetwork`