Silk Wallet SDK

npm link

Installation

npm install @silk-wallet/silk-wallet-sdk
# or
yarn add @silk-wallet/silk-wallet-sdk
# or
pnpm add @silk-wallet/silk-wallet-sdk

Usage

Basic Integration (WaaP)

import { initWaaP } from '@silk-wallet/silk-wallet-sdk'

// Initialize Human Wallet. This will set window.waap with all necessary methods
initWaaP()

// Request accounts (prompts user to connect)
const accounts = await window.waap.request({ method: 'eth_requestAccounts' })
console.log('Connected accounts:', accounts)

// Send a transaction
const txHash = await window.waap.request({
  method: 'eth_sendTransaction',
  params: [
    {
      from: accounts[0],
      to: '0xRecipientAddress',
      value: '0x123' // hex value in wei
    }
  ]
})

Basic Integration (Legacy Silk - Backwards Compatible)

import { initSilk } from '@silk-wallet/silk-wallet-sdk'

// Initialize Human Wallet. This will set window.silk with all necessary methods
initSilk()

// Request accounts (prompts user to connect)
const accounts = await window.silk.request({ method: 'eth_requestAccounts' })
console.log('Connected accounts:', accounts)

// Send a transaction
const txHash = await window.silk.request({
  method: 'eth_sendTransaction',
  params: [
    {
      from: accounts[0],
      to: '0xRecipientAddress',
      value: '0x123' // hex value in wei
    }
  ]
})

Configuration Options

Both initWaaP and initSilk functions accept the same configuration options:

// WaaP (recommended)
initWaaP({
  // Optional: Your WalletConnect project ID (REQUIRED for WalletConnect functionality)
  walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID',

  // Optional: Human Wallet points referral code
  referralCode: 'YOUR_REFERRAL_CODE',

  // Optional: Custom UI configuration
  config: {
    // See documentation or the Developer Portal for more style options
    authenticationMethods: [],
    allowedSocials: [],
    styles: {
      darkMode: true
    }
  },

  // Optional: Project configuration
  project: {
    name: 'Your App Name', // Project name used throughout the SDK
    entryTitle: 'Log in to Your App', // Optional: Custom entry title (defaults to "Log in to {name}")
    logo: 'Your app logo in base64 (see docs or portal)',
    projectId: '' // See documentation or the Developer Portal to learn how to set up a gastank for your users
  },

  // Optional: If you want to accept external wallets (by passing 'wallet' to the authenticationMethods array)
  walletConnectProjectId: ''
})

// Legacy Silk (backwards compatible)
initSilk({
  // Same options as initWaaP
})

WalletConnect Support

To use WalletConnect functionality, you must provide a WalletConnect project ID. This ID can be obtained from WalletConnect Cloud.

You can provide the project ID in several ways (in order of precedence):

1. Pass it directly when initializing (recommended):

   // WaaP
   initWaaP({
     walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID'
   })
   
   // Legacy Silk
   initSilk({
     walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID'
   })

2. Set it programmatically:

   // WaaP
   import { initWaaP, WaaPWalletConnect } from '@silk-wallet/silk-wallet-sdk'
   
   WaaPWalletConnect.setProjectId('YOUR_WALLETCONNECT_PROJECT_ID')
   initWaaP()
   
   // Legacy Silk
   import { initSilk, SilkWalletConnect } from '@silk-wallet/silk-wallet-sdk'
   
   SilkWalletConnect.setProjectId('YOUR_WALLETCONNECT_PROJECT_ID')
   initSilk()

3. Set it as an environment variable:

   • Set NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID in your .env.local file (Next.js)
   • Or set WALLET_CONNECT_PROJECT_ID for other environments

API Reference

The SDK implements the standard Ethereum Provider API (EIP-1193) with some additional methods. Both window.waap and window.silk provide the same interface:

• enable(): Alias for request({ method: 'eth_requestAccounts' })
• isConnected(): Returns whether the provider is connected
• login(): Prompt the user to connect an external wallet
• logout(): Disconnect the current session
• getLoginMethod(): Returns the current login method ('human', 'injected', 'walletconnect', or null)
• requestEmail(): Request the user's email address
• requestSBT(type): Request a Soulbound Token of the specified type
• toggleDarkMode(): Toggle between light and dark mode

Auto-Connect Functionality

The SDK automatically attempts to reconnect users when they refresh the page or return to your application. This works seamlessly in the background when you call eth_requestAccounts.

How Auto-Connect Works

1. When a user successfully logs in via login(), their choice is remembered
2. On subsequent page loads, calling eth_requestAccounts (before login()) will automatically attempt to reconnect using their previous method
3. If the previous method is no longer available or connected, the auto-connect will fail gracefully

Checking the Current Login Method

You can check which login method is currently active without triggering a connection:

// WaaP
const loginMethod = window.waap.getLoginMethod()

// Legacy Silk
const loginMethod = window.silk.getLoginMethod()

if (loginMethod === 'human') {
  console.log('User is connected via Human Wallet')
} else if (loginMethod === 'injected') {
  console.log('User is connected via injected wallet (e.g., MetaMask)')
} else if (loginMethod === 'walletconnect') {
  console.log('User is connected via WalletConnect')
} else {
  console.log('User is not connected')
}

Note: getLoginMethod() verifies that the connection is actually still valid. If the wallet extension is disabled, WalletConnect session expired, or any other connection issue exists, it will return null and automatically clean up the stored state.

Implementing Auto-Connect

// WaaP
import { initWaaP } from '@silk-wallet/silk-wallet-sdk'

initWaaP()

try {
  const accounts = await window.waap.request({
    method: 'eth_requestAccounts'
  })
  console.log('Auto-connected with accounts:', accounts)

  if (accounts.length === 0) {
    await window.waap.login()
  }
} catch (error) {
  console.log('Auto-connect failed, user needs to login again')
}

// Legacy Silk
import { initSilk } from '@silk-wallet/silk-wallet-sdk'

initSilk()

try {
  const accounts = await window.silk.request({
    method: 'eth_requestAccounts'
  })
  console.log('Auto-connected with accounts:', accounts)

  if (accounts.length === 0) {
    await window.silk.login()
  }
} catch (error) {
  console.log('Auto-connect failed, user needs to login again')
}

Logout and Cleanup

When you call logout(), the stored login method is automatically cleared:

// WaaP
await window.waap.logout()
console.log(window.waap.getLoginMethod()) // Returns null

// Legacy Silk
await window.silk.logout()
console.log(window.silk.getLoginMethod()) // Returns null

Error Handling

// WaaP
try {
  const accounts = await window.waap.request({ method: 'eth_requestAccounts' })
} catch (error) {
  console.error('Error connecting:', error)
}

// Legacy Silk
try {
  const accounts = await window.silk.request({ method: 'eth_requestAccounts' })
} catch (error) {
  console.error('Error connecting to Silk:', error)
}

Events

Both providers emit the same events you can listen to:

// WaaP
window.waap.on('connect', () => {
  console.log('Connected')
})

window.waap.on('accountsChanged', (accounts) => {
  console.log('Active account changed:', accounts[0])
})

window.waap.on('chainChanged', (chainId) => {
  console.log('Chain changed to:', chainId)
})

// Legacy Silk
window.silk.on('connect', () => {
  console.log('Connected to Silk')
})

window.silk.on('accountsChanged', (accounts) => {
  console.log('Active account changed:', accounts[0])
})

window.silk.on('chainChanged', (chainId) => {
  console.log('Chain changed to:', chainId)
})

TypeScript Support

The SDK includes TypeScript definitions. You can import them like this:

// WaaP
import { initWaaP, WaaPProvider } from '@silk-wallet/silk-wallet-sdk'

const waap: WaaPProvider = initWaaP()

// Legacy Silk
import { initSilk, SilkProvider } from '@silk-wallet/silk-wallet-sdk'

const silk: SilkProvider = initSilk()

Support

If you encounter any issues or have questions, please reach out to our support team or file an issue in our GitHub repository.

Migrating from pre-v0.5.0

If you're migrating from a pre-v0.5.0 version, please note that event emitter fields like uiMessageManager have been removed from the SilkEthereumProviderInterface. For event handling, you should now use methods directly on the provider instance.

For example, if you were previously disconnecting with:

async disconnect(): Promise<void> {
  const provider = await this.getProvider();
  provider.uiMessageManager.removeListener('accountsChanged', this.onAccountsChanged);
  provider.uiMessageManager.removeListener('chainChanged', this.onChainChanged);
  provider.uiMessageManager.removeListener('disconnect', this.onDisconnect);
}

You should now use:

async disconnect(): Promise<void> {
  const provider = await this.getProvider();
  provider.removeListener('accountsChanged', this.onAccountsChanged);
  provider.removeListener('chainChanged', this.onChainChanged);
  provider.removeListener('disconnect', this.onDisconnect);
}

This follows the EIP-1193 standard for Ethereum providers.