tessl/npm-coinbase--wallet-sdk

TypeScript SDK for connecting web applications to Coinbase Wallet with support for Smart Wallet, mobile wallet, and browser extension connections

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration

Name: tessl/npm-coinbase--wallet-sdk
Author: tessl

Configuration types define app metadata and wallet connection preferences for customizing the Coinbase Wallet SDK behavior.

Capabilities

App Metadata

Core application metadata for wallet integration and display.

interface AppMetadata {
  /** Application name displayed in wallet UI */
  appName: string;
  /** Application logo image URL; favicon is used if unspecified */
  appLogoUrl: string | null;
  /** Array of chainIds your dapp supports */
  appChainIds: number[];
}

Usage Examples:

import { createCoinbaseWalletSDK } from "@coinbase/wallet-sdk";

// Basic metadata
const basicMetadata: AppMetadata = {
  appName: "My DeFi App",
  appLogoUrl: "https://myapp.com/logo.png",
  appChainIds: [1, 8453] // Ethereum mainnet and Base
};

// Metadata with favicon fallback
const metadataWithFavicon: AppMetadata = {
  appName: "Simple Dapp",
  appLogoUrl: null, // Will use page favicon
  appChainIds: [1]
};

// Multi-chain support
const multiChainMetadata: AppMetadata = {
  appName: "Cross-Chain DApp",
  appLogoUrl: "https://example.com/multichain-logo.svg",
  appChainIds: [1, 137, 8453, 42161] // Ethereum, Polygon, Base, Arbitrum
};

const sdk = createCoinbaseWalletSDK(basicMetadata);

Wallet Preferences

Configuration for wallet connection behavior and options.

type Preference = {
  /** The URL for the keys popup (default: https://keys.coinbase.com/connect) */
  keysUrl?: string;
  /** Connection options controlling which wallet types are available */
  options: 'all' | 'smartWalletOnly' | 'eoaOnly';
  /** Smart Wallet attribution configuration (optional) */
  attribution?: Attribution;
} & Record<string, unknown>;

type Attribution =
  | { 
      /** Automatically generate attribution from app origin */
      auto: boolean; 
      dataSuffix?: never; 
    }
  | { 
      auto?: never; 
      /** Custom 16-byte hex string for attribution */
      dataSuffix: `0x${string}`; 
    };

Usage Examples:

// Allow all wallet types (default)
const allWalletsPreference: Preference = {
  options: "all"
};

// Smart Wallet only with auto attribution
const smartWalletPreference: Preference = {
  options: "smartWalletOnly",
  attribution: {
    auto: true
  }
};

// EOA (Externally Owned Account) only
const eoaOnlyPreference: Preference = {
  options: "eoaOnly"
};

// Custom keys URL for development
const devPreference: Preference = {
  options: "all",
  keysUrl: "https://keys-dev.coinbase.com/connect"
};

// Smart Wallet with custom attribution
const customAttributionPreference: Preference = {
  options: "smartWalletOnly",
  attribution: {
    dataSuffix: "0x1234567890abcdef1234567890abcdef" // 16 bytes
  }
};

// Create SDK with preferences
const sdk = createCoinbaseWalletSDK({
  appName: "My App",
  preference: smartWalletPreference
});

Constructor Options

Combined configuration interface used internally by the provider.

interface ConstructorOptions {
  /** Application metadata */
  metadata: AppMetadata;
  /** Wallet connection preferences */
  preference: Preference;
}

SDK Creation Options

Options interface for the modern createCoinbaseWalletSDK function.

type CreateCoinbaseWalletSDKOptions = Partial<AppMetadata> & {
  /** Optional wallet connection preferences */
  preference?: Preference;
};

Usage Examples:

// Minimal configuration
const minimalSdk = createCoinbaseWalletSDK({
  appName: "Minimal App"
  // appLogoUrl defaults to favicon
  // appChainIds defaults to []
  // preference defaults to { options: "all" }
});

// Full configuration
const fullSdk = createCoinbaseWalletSDK({
  appName: "Full Featured App",
  appLogoUrl: "https://app.com/logo.png",
  appChainIds: [1, 8453],
  preference: {
    options: "smartWalletOnly",
    keysUrl: "https://keys.coinbase.com/connect",
    attribution: {
      auto: true
    }
  }
});

Connection Options

All Wallets (`'all'`)

Default option that supports all available wallet connection methods:

Coinbase Smart Wallet (popup-based)
Coinbase Wallet mobile app (QR code/deeplink)
Coinbase Wallet browser extension (injected provider)

const sdk = createCoinbaseWalletSDK({
  appName: "Universal App",
  preference: {
    options: "all" // Supports all connection methods
  }
});

Smart Wallet Only (`'smartWalletOnly'`)

Restricts connections to Coinbase Smart Wallet only:

Uses popup-based connection flow
Supports attribution for transaction tracking
Optimized for web applications

const sdk = createCoinbaseWalletSDK({
  appName: "Smart Wallet App",
  preference: {
    options: "smartWalletOnly",
    attribution: {
      auto: true // Generate attribution from app origin
    }
  }
});

EOA Only (`'eoaOnly'`)

Restricts connections to Externally Owned Accounts (traditional wallets):

Coinbase Wallet mobile app
Coinbase Wallet browser extension
Excludes Smart Wallet connections

const sdk = createCoinbaseWalletSDK({
  appName: "Traditional Wallet App",
  preference: {
    options: "eoaOnly"
  }
});

Attribution Configuration

Attribution is used with Smart Wallet to append custom data to transactions.

Auto Attribution

Automatically generates a 16-byte identifier from the application's origin:

const sdk = createCoinbaseWalletSDK({
  appName: "Auto Attribution App",
  preference: {
    options: "smartWalletOnly",
    attribution: {
      auto: true
    }
  }
});

Custom Attribution

Provides a custom 16-byte hex string for attribution:

const sdk = createCoinbaseWalletSDK({
  appName: "Custom Attribution App",
  preference: {
    options: "smartWalletOnly",
    attribution: {
      dataSuffix: "0x1234567890abcdef1234567890abcdef"
    }
  }
});

Environment Configuration

Production Environment

Default configuration for production applications:

const prodSdk = createCoinbaseWalletSDK({
  appName: "Production App",
  appLogoUrl: "https://myapp.com/logo.png",
  appChainIds: [1, 8453],
  preference: {
    options: "all",
    keysUrl: "https://keys.coinbase.com/connect" // Default
  }
});

Development Environment

Configuration for development with dev keys URL:

const devSdk = createCoinbaseWalletSDK({
  appName: "Development App",
  appChainIds: [11155111], // Sepolia testnet
  preference: {
    options: "all",
    keysUrl: "https://keys-dev.coinbase.com/connect"
  }
});