@0xsequence/connect

Sequence Web SDK 🧰

Sequence Web SDK 🧰 is a library enabling developers to easily integrate web3 wallets in their app. It is based on wagmi and supports 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 👛 🖼️ 🪙
• Fiat onramp 💵 💶 💴 💷
• Inline connect UI for custom layouts and embedded experiences 🎨

View the demo! 👀

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
# or
pnpm install @0xsequence/connect @0xsequence/hooks wagmi ethers@6.13.0 viem 0xsequence @tanstack/react-query
# or
yarn add @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
  trailsCustomCSS?: string | { light?: string; dark?: string }
  signIn?: {
    logoUrl?: string
    projectName?: string
    useMock?: boolean
  }
  displayedAssets?: Array<{
    contractAddress: string
    chainId: number
  }>
  ethAuth?: EthAuthSettings
  onConnectSuccess?: (address: string) => void // callback fired when wallet connects

  wagmiConfig?: WagmiConfig // optional wagmiConfig overrides

  waasConfigKey: string
  enableConfirmationModal?: boolean

  walletConnect?:
    | boolean
    | {
        projectId: string
      }

  guest?: boolean

  google?:
    | boolean
    | {
        clientId: string
      }

  apple?:
    | boolean
    | {
        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 Wagmi client and the SequenceWalletProvider components. It is important that the Wagmi wrapper comes before the Sequence Web SDK wrapper.

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

const projectAccessKey = 'xyz'

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

const transports = {}

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

const connectors = getDefaultConnectors('universal', {
  projectAccessKey,
  appName: 'demo app',
  defaultChainId: 137,

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

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

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <SequenceConnectProvider>
          <Content />
        </SequenceConnectProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Opening the Sign in Modal

Wallet selection is done through a modal which can be called programmatically.

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

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

  const { isConnected } = useAccount()

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

  return <>{!isConnected && <button onClick={onClick}>Sign in</button>}</>
}

Inline Connect UI

Instead of using a modal, you can render the connect UI inline within your layout using the SequenceConnectInline component. This is perfect for custom layouts, embedded wallet experiences, or when you want the connect UI to be part of your page flow.

import { SequenceConnectInline, createConfig } from '@0xsequence/connect'
import { useNavigate } from 'react-router-dom'

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

  // Optional: callback fired when wallet connects successfully
  onConnectSuccess: (address) => {
    console.log('Connected wallet:', address)
    // Redirect or perform other actions
  },

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

function InlinePage() {
  return (
    <div className="my-custom-layout">
      <h1>Connect Your Wallet</h1>
      <SequenceConnectInline config={config} />
    </div>
  )
}

Key Differences from Modal UI:

• No padding/margins: The inline UI removes the default padding designed for modal display
• Full width: The component fills its container width
• No modal backdrop: Renders directly in your layout
• Custom positioning: You control the placement with your own CSS/layout

Advanced: Using SequenceConnectInlineProvider

For more control, you can use the lower-level SequenceConnectInlineProvider:

import { SequenceConnectInlineProvider } from '@0xsequence/connect'
import { WagmiProvider } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <SequenceConnectInlineProvider config={connectConfig}>
          <YourContent />
        </SequenceConnectInlineProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Hooks

useOpenConnectModal

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

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

useTheme

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

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],
    // callback fired when wallet connects successfully
    onConnectSuccess: (address) => {
      console.log('Wallet connected:', address)
      // Perform actions like redirecting, analytics tracking, etc.
    },
  }

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

Packages

Local Development

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

1. pnpm install
2. From the root folder, run pnpm build to build the packages.
3. From the root folder, run pnpm dev:react or pnpm dev:next to run the examples.

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 Sequence Platforms ULC. / https://sequence.xyz