Sequence Web SDK 🧰

Easily integrate web3 wallets in your app with Sequence Web SDK 🧰. Based on wagmi, and supporting all wagmi features.

• Connect via social logins eg: facebook, google, discord, etc...! 🔐🪪
• Connect to popular web3 wallets eg: walletConnect, metamask ! 🦊 ⛓️
• Full-fledged embedded wallet for coins and collectibles 👛 🖼️ 🪙

View the demo! 👀

Migration Guide from kit v4 to web-sdk v5

Quick Start

Installing the Library

@0xsequence/connect is the core package. Any extra modules require this package to be installed first. To install this package:

npm install @0xsequence/connect @0xsequence/hooks wagmi ethers@6.13.0 viem 0xsequence @tanstack/react-query

Setting up the Library

The 'easy' way

• createConfig(walletType, options) method is used to create your initial config and prepare sensible defaults that can be overridden

walletType is either 'waas' or 'universal'

interface CreateConfigOptions {
  appName: string
  projectAccessKey: string
  chainIds?: number[]
  defaultChainId?: number
  disableAnalytics?: boolean
  defaultTheme?: Theme
  position?: ModalPosition
  customCSS?: string // Injected into shadow dom
  signIn?: {
    logoUrl?: string
    projectName?: string
    useMock?: boolean
  }
  displayedAssets?: Array<{
    contractAddress: string
    chainId: number
  }>
  ethAuth?: EthAuthSettings

  wagmiConfig?: WagmiConfig // optional wagmiConfig overrides

  waasConfigKey?: string
  enableConfirmationModal?: boolean

  walletConnect?:
    | false
    | {
        projectId: string
      }

  guest?: boolean

  google?:
    | false
    | {
        clientId: string
      }

  apple?:
    | false
    | {
        clientId: string
        redirectURI: string
      }

  X?:
    | boolean
    | {
        clientId: string
        redirectURI: string
      }
      
  email?:
    | boolean
    | {
        legacyEmailAuth?: boolean
      }
}

import { SequenceConnect, createConfig } from '@0xsequence/connect'

import Content from './components/Content'

const config = createConfig('waas', {
  projectAccessKey: '<your-project-access-key>',
  chainIds: [1, 137],
  defaultChainId: 1,
  appName: 'Demo Dapp',
  waasConfigKey: '<your-waas-config-key>',

  guest: true,

  google: {
    clientId: '<your-google-client-id>'
  },

  apple: {
    clientId: '<your-apple-client-id>',
    redirectURI: '...'
  },

  X: {
    clientId: '<your-X-client-id>',
    redirectURI: '...'
  },


  walletConnect: {
    projectId: '<your-wallet-connect-id>'
  },

  email: true
})

function App() {
  return (
    <SequenceConnect config={config}>
      <Content />
    </SequenceConnect>
  )
}

Note about X (formerly Twitter) authentication. X authentication specifically needs a callback route; either a frontend page or a backend endpoint. An frontend example callback page is below:

Please ensure that the redirect uri and the callback page route is identical or X will refuse the authentication

export function XAuthCallback() {
  useEffect(() => {
    const query = new URLSearchParams(window.location.search)

    const payload = {
      code: query.get('code'),
      state: query.get('state')
    }

    if (window.opener) {
      window.opener.postMessage({ type: 'OAUTH_RETURN', data: payload }, '*')
    }

    window.close()
  }, [])

  return (
    <h3>
      you may now close this window.
    </h3>
  )
}

Need more customization?

React apps must be wrapped by a WagmiProvider and the SequenceConnectProvider components. It is important that the Wagmi wrapper comes before the SequenceConnectProvider wrapper.

import Content from './components/Content'
import { SequenceConnectProvider, getDefaultConnectors, getDefaultChains } from '@0xsequence/connect'
import { SequenceWalletProvider } from '@0xsequence/wallet-widget'
import { SequenceCheckoutProvider } from '@0xsequence/checkout'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { createConfig, http, WagmiProvider } from 'wagmi'
import { mainnet, polygon, Chain } from 'wagmi/chains'

const projectAccessKey = '<your-project-access-key>'

const chains = getDefaultChains(/* optional array of chain ids to filter */)

const transports = {}

chains.forEach(chain => {
  transports[chain.id] = http()
})

// Universal wallet configuration
const connectors = getDefaultConnectors('universal', {
  projectAccessKey,
  appName: 'Demo Dapp',
  defaultChainId: 137,

  walletConnect: {
    projectId: '<your-wallet-connect-id>'
  }
})

/*
  const connectors = getDefaultWaasConnectors('{
    projectAccessKey,
    defaultChainId: 137,
    appName: 'Demo Dapp',

    waasConfigKey: '<your-waas-config-key>',

    guest: true

    google: {
      clientId
    },

    apple: {
      clientId,
      redirectUrl
    },

    walletConnect: {
      projectId: '<your-wallet-connect-id>'
    }

    email: true
  })
  */

const wagmiConfig = createConfig({
  chains,
  transports,
  connectors
})

const connectConfig = {
  projectAccessKey: '...'
}

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SequenceConnectProvider config={connectConfig}>
          {/* If you want to use wallet modal to show assets etc. */}
          <SequenceWalletProvider>
            {/* If you want to use checkout functionalities */}
            <SequenceCheckoutProvider>
              <Content />
            </SequenceCheckoutProvider>
          </SequenceWalletProvider>
        </SequenceConnectProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Opening the Sign in Modal

Wallet selection is done through a modal which can be called programmatically. Kit allows multiple connection, so it can be called again to connect more wallets.

import { useOpenConnectModal } from '@0xsequence/connect'
import { useDisconnect, useAccount } from 'wagmi'

const MyReactComponent = () => {
  const { setOpenConnectModal } = useOpenConnectModal()

  const { wallets } = useWallets()

  const onClick = () => {
    setOpenConnectModal(true)
  }

  return <>{!wallets.length && <button onClick={onClick}>Sign in</button>}</>
}

Hooks

useOpenConnectModal

Use the useOpenConnectModal to change to open or close the connection modal.

import { useOpenConnectModal } from '@0xsequence/connect'
// ...
const { setOpenConnectModal } = useOpenConnectModal()
setOpenConnectModal(true)

useWallets

Use the useWallets hook to manage multiple connected wallets in your application and see linked wallets of the connected embedded wallet. This hook is particularly useful when working with a combination of embedded and external wallets.

import { useWallets } from '@0xsequence/connect'

const {
  wallets, // Array of connected wallets
  linkedWallets, // Array of linked wallets (for embedded wallets)
  setActiveWallet, // Function to set a wallet as active
  disconnectWallet // Function to disconnect a wallet
} = useWallets()

/**
 * Interface representing a connected wallet
 */
interface ConnectedWallet {
  /** Unique identifier */
  id: string
  /** Display name of the wallet */
  name: string
  /** Wallet address */
  address: string
  /** Whether this is the currently active wallet */
  isActive: boolean
  /** Whether this is an embedded wallet */
  isEmbedded: boolean
}

// Switch to a different connected wallet
await setActiveWallet(walletAddress)

// Disconnect a specific wallet
await disconnectWallet(walletAddress)

useTheme

Use the useTheme hook to get information about the current theme, such as light or dark.

import { useTheme } from '@0xsequence/connect'
const { theme, setTheme } = useTheme()

setTheme('light')

Customization

The SequenceConnectProvider wrapper can accept an optional config object.

The settings are described in more detailed in the Sequence Web SDK documentation.

  const connectConfig = {
    defaultTheme: 'light',
    position: 'top-left',
    signIn: {
      logoUrl: 'https://logo-dark-mode.svg',
      projectName: 'my app',
    },
    // limits the digital assets displayed on the assets summary screen
    displayedAssets: [
      {
        contractAddress: zeroAddress,
        chainId: 137,
      },
      {
        contractAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
        chainId: 137
      }
    ],
    readOnlyNetworks: [10], // Display assets in wallet from Optimism (chain ID 10) in addition to the networks specified in chainIds
  }

  <SequenceConnectProvider config={connectConfig}>
    <App />
  <SequenceConnectProvider>

Packages

Package	Description	Docs
@0xsequence/connect	Core package for Sequence Web SDK	Read more
@0xsequence/wallet-widget	Embedded wallets for viewing and sending coins and collectibles	Read more
@0xsequence/checkout	Checkout modal with fiat onramp	Read more

Examples

Application	Description	Docs
example-react	React example application showing sign in, wallet and checkout	Read more
example-next	Next example application showing sign in, wallet and checkout with SSR	Read more

Local Development

The React example can be used to test the library locally.

1. Replace the web-sdk dependencies to the ones of the workspace in order to use hot reload.:

"@0xsequence/connect": "workspace:*",
"@0xsequence/checkout": "workspace:*",
"@0xsequence/wallet-widget": "workspace:*",

2. pnpm install
3. From the root folder, run pnpm build to build the packages OR optionally run pnpm dev in a separate terminal to develop in watch mode.
4. From the root folder, run pnpm dev:react or pnpm dev:next to run the examples. If you want to run the examples in debug mode, run pnpm debug:react

What to do next?

Now that the core package is installed, you can install the embedded wallet or take a look at the checkout.

LICENSE

Apache-2.0

Copyright (c) 2017-present Horizon Blockchain Games Inc. / https://horizon.io