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:

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

​
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