Getting Started

The DogeOS SDK is the official React library for building on DogeOS. It provides a configurable wallet connection modal, account actions, and EVM-focused chain support for fast integration into modern dApps.

Installation

npm install @dogeos/dogeos-sdk

Obtain Client ID (Required)

To use the DogeOS SDK, you must supply a clientId:

Submit your project details via the Partner Interest Form.
Once approved, you will receive a clientId.
Add the clientId to your SDK configuration.

Setup Provider

Wrap your application with WalletConnectProvider to initialize the SDK.

import React from "react"
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk"

const config: WalletConnectKitConfig = {
  clientId: "YOUR_CLIENT_ID",
}

export default function App() {
  return (
    <WalletConnectProvider config={config}>
      <YourApp />
    </WalletConnectProvider>
  )
}

Next.js Usage (Client-Side Only)

The SDK relies on browser APIs and must run on the client. Use "use client" for App Router or dynamic imports for Pages Router.

App Router Example

"use client"

import React from "react"
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"

const config = {
  clientId: "YOUR_CLIENT_ID",
}

export default function Providers({ children }: { children: React.ReactNode }) {
  return <WalletConnectProvider config={config}>{children}</WalletConnectProvider>
}

Pages Router Example

"use client"

import React from "react"
import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"

const config = {
  clientId: "YOUR_CLIENT_ID",
}

export default function WalletProvider() {
  return <WalletConnectProvider config={config}>{/* app UI */}</WalletConnectProvider>
}

import dynamic from "next/dynamic"

const WalletProvider = dynamic(() => import("../components/WalletProvider"), {
  ssr: false,
})

export default function Page() {
  return <WalletProvider />
}

Configuration Overview

clientId (required): obtain from https://sdk.dogeos.com/register.
connectors (optional): array of custom wallets (see Types & Enums for required fields).
chains (optional): map chain types to arrays of chains (for EVM, use viem Chain objects). See viem chain reference: https://viem.sh/docs/chains/introduction/.
walletConnectConfig (optional): WalletConnect v2 settings if you need to override defaults (see Types & Enums for field details).

Example with EVM chains:

import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import { mainnet, base } from "viem/chains"

const config = {
  clientId: "YOUR_CLIENT_ID",
  chains: {
    evm: [mainnet, base],
  },
}

export default function App() {
  return (
    <WalletConnectProvider config={config}>
      <YourApp />
    </WalletConnectProvider>
  )
}

Core Hooks

Use these hooks in your app to drive connection state and account actions.

const { isOpenModal, isConnected, isConnecting, error, connect, disconnect, openModal, closeModal } = useWalletConnect()

const {
  address,
  balance,
  chainType,
  chainId,
  currentWallet,
  currentProvider,
  switchChain,
  signMessage,
  signInWithWallet,
} = useAccount()

chainType returns the active network type (documented here for EVM). Use the literal "evm" whenever you need to specify a chain type in code.

useWalletConnect Fields

isOpenModal: whether the modal is visible.
isConnected: true when a wallet is connected.
isConnecting: true while a connection is in progress.
error: last connection error message, if any.
openModal / closeModal: show or hide the modal.
connect: request a connection programmatically.
disconnect: disconnect the active wallet.

useAccount Fields

address: active account address.
balance: current balance (if available).
chainType: active chain type (evm for EVM wallets).
chainId: active chain ID (hex string for EVM).
currentWallet: connected wallet metadata.
currentProvider: EIP-1193 provider for EVM RPC calls.
switchChain: switch to a configured chain.
signMessage: sign a message with the active wallet.
signInWithWallet: sign a login payload and return a token/signature.

Support

For more help or if you encounter issues, please visit:

License

Please check the project’s LICENSE file for details.