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:
| Prop | Type | Required | Description |
|---|---|---|---|
config | WalletConnectKitConfig | Yes | SDK configuration |
children | React.ReactNode | Yes | Child 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 viewexport function EmbeddedWalletList() { return <WalletConnectEmbed view={ModalView.WalletList} />}Props:
| Prop | Type | Required | Description |
|---|---|---|---|
className | string | No | CSS class for the container |
style | React.CSSProperties | No | Inline styles for the container |
view | ModalView | No | Force 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:
| Field | Type | Description |
|---|---|---|
isOpenModal | boolean | Whether the connection modal is visible |
isConnected | boolean | Whether a wallet is currently connected |
isConnecting | boolean | Whether a connection attempt is in progress |
error | string | Error message from last failed connection |
connect | function | Programmatically connect to a wallet |
disconnect | function | Disconnect the current wallet |
openModal | function | Open the connection modal |
closeModal | function | Close 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:
ConnectVariables- Parameters forconnect()ConnectData- Return value ofconnect()
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:
| Field | Type | Description |
|---|---|---|
address | string | Connected wallet address |
balance | string | undefined | Current balance (if available) |
chainType | ChainType | undefined | Active chain type (e.g., "evm") |
chainId | string | undefined | Active chain ID (hex string for EVM) |
currentWallet | Connector | null | Connected wallet metadata |
currentProvider | any | EIP-1193 compatible provider for EVM RPC calls |
switchChain | function | Switch to a different chain. Returns true on success |
signMessage | function | undefined | Sign a message. Returns signature |
signInWithWallet | function | Sign-in with wallet (SIWE). Returns token |
Important Notes:
signMessagemay beundefinedwhen no wallet is connectedswitchChain()returnsPromise<boolean>- check return value for successsignMessage()andsignInWithWallet()returnPromise<string | Uint8Array>currentProviderfollows 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:
| Field | Type | Description |
|---|---|---|
wallet | any | undefined | Embedded wallet instance |
isAvailable | boolean | Whether embedded wallet is available |
message | string | null | Status or error message |
connectedInfo | ConnectData | undefined | Connection data when connected |
isLoading | boolean | Whether 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 errorawait signMessage({ message: "Hello" })
// Correct - use optional chainingawait signMessage?.({ message: "Hello" })
// Or explicit checkif (signMessage) { await signMessage({ message: "Hello" })}Handle Return Values
Functions return specific types - handle them correctly:
// switchChain returns booleanconst success = await switchChain({ chainType: "evm", chainInfo: base })if (!success) handleError()
// signMessage returns string or Uint8Arrayconst 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 typesconst { address, chainId, signMessage } = useAccount()
// Unnecessary - manual annotation not neededconst result: UseAccountReturn = useAccount()