Embedded wallets let users sign in with email, Google, or X. Users can also connect an existing external wallet. Show the wallet flow in the SDK modal or inline with WalletConnectEmbed.

Defaults#

With only your registered DogeOS clientId, the SDK offers email, Google, X, and external wallet connections. DogeOS manages social authentication and the SDK uses production services automatically.

Configure Login Methods#

Use login.basicLogins and login.socialLogins to control which login methods appear.

import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
 
export const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  login: {
    basicLogins: ["email", "externalWallets"],
    socialLogins: [{ type: "google" }, { type: "x" }],
  },
}

Each omitted array retains its default methods. Set an array to [] to hide those methods. The example above explicitly lists all default choices; omit login if that is what you need.

Native-First Connection in MyDoge#

SDK 4.0.4 selects the injected MyDoge wallet before initializing embedded-wallet services inside the MyDoge dApp browser. Use your normal WalletConnectProvider configuration and openModal() connection control. You can keep email and social login enabled for ordinary browsers; no user-agent check or native-only configuration flag is needed.

If native startup times out, the SDK displays a readiness message and Retry action. In 4.0.4 it continues checking and automatically resumes when the native wallet becomes ready, including readiness that arrives after the timeout. Your app does not need to remount the provider or implement its own polling.

Use isConnected and useAccount()’s current account, chain and provider for native actions. walletStatus can be "disabled" and isWalletReady can be false while the native wallet is connected: those fields describe embedded readiness. Do not gate native signing on them, start a second embedded wallet, or silently fall back to hosted login after a native rejection.

Native wallet requests belong to the approved top-level dApp page. An embedded child frame cannot call the native wallet bridge directly. Ordinary chart/content frames can remain alongside top-page wallet use.

External-Wallet-Only Mode#

To disable embedded wallet login, set both arrays explicitly:

import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
 
const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  login: {
    basicLogins: ["externalWallets"],
    socialLogins: [],
  },
}

When embedded login is disabled this way, walletStatus becomes "disabled".

Use this mode when your app only needs injected wallets or WalletConnect. The SDK will not initialize an embedded wallet.

In ordinary browsers with embedded login enabled, the SDK keeps external wallet connection available while the embedded wallet initializes. Social-login buttons remain disabled until the embedded wallet reports ready. Inside MyDoge, native-first selection skips embedded initialization.

Render Inline#

WalletConnectEmbed renders the same SDK wallet flow inline instead of as an overlay. It must be inside WalletConnectProvider.

"use client"
 
import { WalletConnectEmbed, WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
}
 
export function EmbeddedWalletPanel() {
  return (
    <WalletConnectProvider config={dogeConfig}>
      <section>
        <h2>Connect to DogeOS</h2>
        <WalletConnectEmbed className="wallet-embed" style={{ width: "100%", maxWidth: 448 }} />
      </section>
    </WalletConnectProvider>
  )
}

The component accepts:

The SDK gives the embed a default width of 448px. Override that with className or style if your layout needs a different size.

Track Readiness#

Use useWalletConnect() for embedded wallet readiness. Readiness is separate from account connection: isWalletReady means the embedded wallet can accept login, while isConnected means the user has connected a wallet.

Neither state proves an authenticated application session. Your backend must verify the sign-in challenge before creating a session.

import { useWalletConnect } from "@dogeos/dogeos-sdk"
 
export function EmbeddedReadiness() {
  const { walletStatus, isWalletReady, isWalletLoading } = useWalletConnect()
 
  if (isWalletLoading) return <p>Preparing wallet...</p>
  if (walletStatus === "error") return <p>Wallet could not initialize.</p>
  if (walletStatus === "unavailable") return <p>Embedded wallet unavailable.</p>
 
  return <p>{isWalletReady ? "Wallet ready" : walletStatus}</p>
}

Theme Mode#

The provider passes the configured SDK theme mode into the embedded wallet. Set theme.defaultTheme to "light" or "dark" to choose the initial mode.

import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
 
const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  theme: {
    defaultTheme: "dark",
  },
}

See Configuration for color overrides.

Content Security Policy#

If your app sets a Content Security Policy, include the production SDK origins in the relevant directives:

Add these to your existing policy. Keep any additional origins required by your app, chain RPCs, or WalletConnect. This table is not a complete CSP for your application.