SDK Hooks & Components

This page documents the hooks and components exported by the DogeOS SDK. For type definitions, see Types & Enums.

Components

WalletConnectProvider

Provider component that initializes the SDK. Wrap your app with this component to enable wallet connections.

import { WalletConnectProvider } from "@dogeos/dogeos-sdk"
import "@dogeos/dogeos-sdk/style.css"
const config = { clientId: "YOUR_CLIENT_ID" }
export function Providers({ children }: { children: React.ReactNode }) {
return <WalletConnectProvider config={config}>{children}</WalletConnectProvider>
}

Props:

PropTypeRequiredDescription
configWalletConnectKitConfigYesSDK configuration
childrenReact.ReactNodeYesChild components

WalletConnectEmbed

Embeds the wallet UI inline instead of using a modal overlay. Useful for custom onboarding flows.

import { WalletConnectEmbed, ModalView } from "@dogeos/dogeos-sdk"
export function EmbeddedLogin() {
return <WalletConnectEmbed className="wallet-embed" />
}
// Force a specific view
export function EmbeddedWalletList() {
return <WalletConnectEmbed view={ModalView.WalletList} />
}

Props:

PropTypeRequiredDescription
classNamestringNoCSS class for the container
styleReact.CSSPropertiesNoInline styles for the container
viewModalViewNoForce a specific view

See also: Embedded Wallets guide


Hooks

useWalletConnect

Controls the connection modal and wallet state.

import { useWalletConnect } from "@dogeos/dogeos-sdk"
const { isOpenModal, isConnected, isConnecting, error, connect, disconnect, openModal, closeModal } = useWalletConnect()

Return Type:

interface UseWalletConnectReturn {
isOpenModal: boolean
isConnected: boolean
isConnecting: boolean
error: string
connect: (variables: ConnectVariables) => Promise<ConnectData>
disconnect: () => Promise<void>
openModal: () => void
closeModal: () => void
}

Fields:

FieldTypeDescription
isOpenModalbooleanWhether the connection modal is visible
isConnectedbooleanWhether a wallet is currently connected
isConnectingbooleanWhether a connection attempt is in progress
errorstringError message from last failed connection
connectfunctionProgrammatically connect to a wallet
disconnectfunctionDisconnect the current wallet
openModalfunctionOpen the connection modal
closeModalfunctionClose the connection modal

Example:

import { useWalletConnect } from "@dogeos/dogeos-sdk"
export function ConnectButton() {
const { openModal, isConnected, isConnecting, disconnect, error } = useWalletConnect()
if (isConnecting) return <button disabled>Connecting...</button>
if (isConnected) return <button onClick={disconnect}>Disconnect</button>
return (
<>
<button onClick={openModal}>Connect Wallet</button>
{error && <p style={{ color: "red" }}>{error}</p>}
</>
)
}

Type References:

useAccount

Provides account info and actions once connected.

import { useAccount } from "@dogeos/dogeos-sdk"
const {
address,
balance,
chainType,
chainId,
currentWallet,
currentProvider,
switchChain,
signMessage,
signInWithWallet,
} = useAccount()

Return Type:

interface UseAccountReturn {
address: string
balance?: string
chainType?: ChainType
chainId?: string
currentWallet?: Connector | null
currentProvider?: any
switchChain: (options: SwitchChainOptions) => Promise<boolean>
signMessage?: (params: SignMessageParams) => Promise<string | Uint8Array>
signInWithWallet: (params?: SignInParams) => Promise<string | Uint8Array>
}

Fields:

FieldTypeDescription
addressstringConnected wallet address
balancestring | undefinedCurrent balance (if available)
chainTypeChainType | undefinedActive chain type (e.g., "evm")
chainIdstring | undefinedActive chain ID (hex string for EVM)
currentWalletConnector | nullConnected wallet metadata
currentProvideranyEIP-1193 compatible provider for EVM RPC calls
switchChainfunctionSwitch to a different chain. Returns true on success
signMessagefunction | undefinedSign a message. Returns signature
signInWithWalletfunctionSign-in with wallet (SIWE). Returns token

Important Notes:

  • signMessage may be undefined when no wallet is connected
  • switchChain() returns Promise<boolean> - check return value for success
  • signMessage() and signInWithWallet() return Promise<string | Uint8Array>
  • currentProvider follows the EIP-1193 interface for EVM RPC calls

Example - Display Address:

import { useAccount } from "@dogeos/dogeos-sdk"
export function AccountInfo() {
const { address, chainId, balance } = useAccount()
if (!address) return <div>Not connected</div>
return (
<div>
<p>
Address: {address.slice(0, 6)}...{address.slice(-4)}
</p>
<p>Chain: {chainId}</p>
<p>Balance: {balance ?? "Loading..."}</p>
</div>
)
}

Example - Sign Message:

import { useAccount } from "@dogeos/dogeos-sdk"
export function SignButton() {
const { signMessage } = useAccount()
const handleSign = async () => {
// Always check if function exists
const signature = await signMessage?.({
message: "Hello, DogeOS!",
nonce: crypto.randomUUID(),
})
console.log("Signature:", signature)
}
return (
<button onClick={handleSign} disabled={!signMessage}>
Sign Message
</button>
)
}

Example - Switch Chain:

import { useAccount } from "@dogeos/dogeos-sdk"
import { base } from "viem/chains"
export function SwitchToBase() {
const { switchChain } = useAccount()
const handleSwitch = async () => {
const success = await switchChain({
chainType: "evm",
chainInfo: base,
})
if (!success) {
console.error("Chain switch failed")
}
}
return <button onClick={handleSwitch}>Switch to Base</button>
}

Example - EVM Provider Calls:

import { useAccount } from "@dogeos/dogeos-sdk"
export function SendTransaction() {
const { currentProvider, address } = useAccount()
const handleSend = async () => {
if (!currentProvider || !address) return
const txHash = await currentProvider.request({
method: "eth_sendTransaction",
params: [
{
from: address,
to: "0x...",
value: "0x0",
data: "0x",
},
],
})
console.log("Transaction:", txHash)
}
return (
<button onClick={handleSend} disabled={!currentProvider}>
Send
</button>
)
}

Type References:

useEmbeddedWallet

Returns the embedded wallet state when using inline wallets.

import { useEmbeddedWallet } from "@dogeos/dogeos-sdk"
const { wallet, isAvailable, message, connectedInfo, isLoading } = useEmbeddedWallet()

Return Type:

interface UseEmbeddedWalletReturn {
wallet: any | undefined
isAvailable: boolean
message: string | null
connectedInfo: ConnectData | undefined
isLoading: boolean
}

Fields:

FieldTypeDescription
walletany | undefinedEmbedded wallet instance
isAvailablebooleanWhether embedded wallet is available
messagestring | nullStatus or error message
connectedInfoConnectData | undefinedConnection data when connected
isLoadingbooleanWhether wallet is loading

Example:

import { useEmbeddedWallet } from "@dogeos/dogeos-sdk"
export function EmbeddedStatus() {
const { wallet, isAvailable, message, connectedInfo, isLoading } = useEmbeddedWallet()
if (isLoading) return <div>Loading embedded wallet...</div>
if (!isAvailable) return <div>Unavailable: {message}</div>
return (
<div>
<div>Embedded wallet ready: {Boolean(wallet)}</div>
{connectedInfo && <div>Connected: {connectedInfo.address}</div>}
</div>
)
}

Type References:

See also: Embedded Wallets guide


TypeScript Best Practices

Check Function Availability

Hook functions may be undefined when no wallet is connected:

const { signMessage } = useAccount()
// Wrong - may throw error
await signMessage({ message: "Hello" })
// Correct - use optional chaining
await signMessage?.({ message: "Hello" })
// Or explicit check
if (signMessage) {
await signMessage({ message: "Hello" })
}

Handle Return Values

Functions return specific types - handle them correctly:

// switchChain returns boolean
const success = await switchChain({ chainType: "evm", chainInfo: base })
if (!success) handleError()
// signMessage returns string or Uint8Array
const signature = await signMessage?.({ message: "Hello" })
if (typeof signature === "string") {
console.log("Hex signature:", signature)
} else if (signature) {
console.log("Uint8Array signature:", signature)
}

Type Inference

Let TypeScript infer types from hooks:

// Good - TypeScript infers types
const { address, chainId, signMessage } = useAccount()
// Unnecessary - manual annotation not needed
const result: UseAccountReturn = useAccount()