Skip to Content
On this page

The DogeOS SDK is the React wallet connection package for DogeOS applications. It exports a provider, a hosted wallet modal, an inline embedded-wallet view, account hooks, chain/connector helpers, and optional Wagmi integration.

These docs cover @dogeos/dogeos-sdk v4.0.4, the latest stable release on npm as of October 19, 2026. The published SDK uses DogeOS production services automatically, including when you develop locally or connect to a testnet.

Use the SDK demo repository  for a working integration. Inside MyDoge, the SDK selects the injected native wallet before embedded initialization; see Native-First Connection.

Requirements#

  • React >=18
  • React DOM >=18
  • Wagmi >=2.0.0
  • A DogeOS SDK clientId

wagmi is a peer dependency of the SDK package. Install it even if you only use the SDK hooks directly.

Install#

npm install @dogeos/dogeos-sdk@^4.0.4 wagmi
pnpm add @dogeos/dogeos-sdk@^4.0.4 wagmi
yarn add @dogeos/dogeos-sdk@^4.0.4 wagmi

When upgrading, run the matching command above, commit the updated lockfile, and rebuild your deployed app. Verify the resolved SDK version with npm ls @dogeos/dogeos-sdk or your package manager’s equivalent; an older lockfile can retain an older version even when the declared range allows 4.0.4.

Upgrading from Earlier v4 Releases#

Keep your existing provider and hook integration. When upgrading to 4.0.4:

  • Supply your own walletConnectProjectId if you need WalletConnect. Omitted or blank IDs disable WalletConnect; the SDK no longer supplies a fallback. Email, social login, and supported injected wallets remain available.
  • Inside MyDoge, native startup can recover when wallet readiness arrives after the initial timeout. Keep the standard connection flow; see native readiness and retry.
  • Keep authentication and wallet connection state separate. Completing social sign-in does not mean wallet setup or recovery has finished; use isConnected and the active account/provider before starting wallet actions.

Get a Client ID#

Every app must pass clientId to WalletConnectProvider. Create a project in the developer console  and copy its client ID. Your project has separate Sandbox and Live client IDs.

Use the Sandbox client ID during development. Your project overview shows whether automatic access from localhost and 127.0.0.1 is ready. Register hosted application origins in the matching environment. Origins include the scheme, hostname, and port, such as https://app.example.com.

The client ID is public and must be available to your browser bundle. It is separate from the optional WalletConnect project ID described in WalletConnect configuration.

const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
}

Add the Provider#

Wrap the interactive part of your app with WalletConnectProvider. Import the SDK stylesheet once near the provider or app root.

"use client"
 
import type { ReactNode } from "react"
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
const dogeConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
}
 
export function DogeOSProvider({ children }: { children: ReactNode }) {
  return <WalletConnectProvider config={dogeConfig}>{children}</WalletConnectProvider>
}

Next.js#

WalletConnectProvider uses browser APIs and returns null during server rendering. In the App Router, put it in a client component.

// app/providers.tsx
"use client"
 
import type { ReactNode } from "react"
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
 
const dogeConfig = {
  clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID!,
}
 
export function Providers({ children }: { children: ReactNode }) {
  return <WalletConnectProvider config={dogeConfig}>{children}</WalletConnectProvider>
}

Set NEXT_PUBLIC_DOGEOS_CLIENT_ID to your registered client ID before starting or building your app.

// app/layout.tsx
import { Providers } from "./providers"
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

For the Pages Router, load the provider component with next/dynamic and ssr: false.

Open the Wallet Modal#

Use the SDK modal for the normal wallet connection flow. It knows how to list available wallets, embedded wallet login methods, WalletConnect options, and chain choices from your configuration.

"use client"
 
import { useWalletConnect } from "@dogeos/dogeos-sdk"
 
export function ConnectWalletButton() {
  const { isConnected, isConnecting, openModal, disconnect } = useWalletConnect()
 
  if (isConnecting) {
    return <button disabled>Connecting...</button>
  }
 
  return <button onClick={isConnected ? disconnect : openModal}>{isConnected ? "Disconnect" : "Connect wallet"}</button>
}

Read Account State#

Use useAccount() for the active address, chain, wallet, provider, and signing helpers.

"use client"
 
import { useAccount } from "@dogeos/dogeos-sdk"
 
export function AccountSummary() {
  const { address, chainType, chainId } = useAccount()
 
  if (!address) {
    return <p>No wallet connected.</p>
  }
 
  return (
    <dl>
      <dt>Address</dt>
      <dd>
        {address.slice(0, 6)}...{address.slice(-4)}
      </dd>
      <dt>Chain</dt>
      <dd>
        {chainType}:{chainId}
      </dd>
    </dl>
  )
}

Configure DogeOS Chikyū Testnet#

For an app on DogeOS Chikyū Testnet, add the following chains configuration to the provider. Chikyū is an EVM chain, so it belongs under chains.evm. Choosing a blockchain testnet does not change the SDK’s production login and wallet services.

import { ChainTypeEnum, type Chain, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk"
 
const dogeOSChikyuTestnet = {
  id: 6281971,
  name: "DogeOS Chikyū Testnet",
  nativeCurrency: { name: "DOGE", symbol: "DOGE", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.testnet.dogeos.com/"] } },
  blockExplorers: {
    default: {
      name: "DogeOS L2Scan",
      url: "https://dogeos-testnet.l2scan.co",
    },
  },
  testnet: true,
} satisfies Chain
 
export const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  defaultConnectChain: ChainTypeEnum.EVM,
  chains: {
    evm: [dogeOSChikyuTestnet],
  },
}

What the SDK Gives You#

  • A modal connection flow through openModal() and closeModal().
  • Embedded wallet login with email, Google, or X, and connections to external wallets.
  • Account state through useAccount().
  • Wallet readiness and connection state through useWalletConnect().
  • Runtime provider access for EVM, Solana, and Dogecoin wallet methods.
  • switchChain(), signMessage(), and signInWithWallet().
  • getChains() and getConnectors() helpers for dynamic configuration.
  • Optional Wagmi synchronization when WalletConnectProvider is mounted inside WagmiProvider.

Next Steps#