Skip to Content
SDKGetting Started

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.

The package published by the SDK repository is @dogeos/dogeos-sdk. These docs describe the current public source surface in dogeos-connect-kit and focus on the DogeOS application path: connect a wallet, support DogeOS Chikyū Testnet as an EVM chain, support Dogecoin wallets, and use embedded wallet login when your app needs it.

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 wagmi
pnpm add @dogeos/dogeos-sdk wagmi
yarn add @dogeos/dogeos-sdk wagmi

Get a Client ID

Every app must pass clientId to WalletConnectProvider. Request one through the Partner Interest Form .

The SDK runs in the browser, so the value must be available to your client bundle. Keep separate values for development, staging, and production if your integration is registered per environment.

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>
}
// 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

The SDK can load chains dynamically with getChains(), but most DogeOS apps should make the supported DogeOS networks explicit. DogeOS Chikyū Testnet is an EVM chain, so list it under chains.evm. Dogecoin belongs under chains.dogecoin.

import type { Chain, 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 Blockscout",
      url: "https://blockscout.testnet.dogeos.com",
    },
  },
  testnet: true,
} satisfies Chain
 
const dogecoin = {
  id: 1,
  name: "Dogecoin",
  nativeCurrency: { name: "DOGE", symbol: "DOGE", decimals: 8 },
  rpcUrls: { default: { http: [] } },
} satisfies Chain
 
export const dogeConfig: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  defaultConnectChain: "evm",
  chains: {
    evm: [dogeOSChikyuTestnet],
    dogecoin: [dogecoin],
  },
  metadata: {
    name: "Your App",
    description: "Your DogeOS application",
    url: "https://your-app.example",
    icons: ["https://your-app.example/icon.png"],
  },
}

What the SDK Gives You

  • A modal connection flow through openModal() and closeModal().
  • Embedded wallet login with email, Google, X, and external wallets.
  • Account state through useAccount().
  • Wallet readiness and connection state through useWalletConnect().
  • Runtime provider access for EVM 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

Configuration