Core Workflows

This guide shows the workflows you will use after mounting WalletConnectProvider.

Use the modal-first flow unless you are building a custom wallet picker from SDK internals. The public connect() method expects a runtime wallet connector, not the configuration object returned by getConnectors().


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

openModal() opens the account view when a wallet is already connected, and opens the wallet home view otherwise.

Show Connection Status


import { useWalletConnect } from "@dogeos/dogeos-sdk"
 
export function WalletStatusBadge() {
  const { connectionStatus, walletStatus, isWalletReady } = useWalletConnect()
 
  return (
    <span>
      {connectionStatus} / {isWalletReady ? "wallet ready" : walletStatus}
    </span>
  )
}

connectionStatus is "disconnected", "connecting", or "connected". walletStatus describes the embedded wallet lifecycle: "disabled", "initializing", "ready", "unavailable", or "error".

Display the Connected Account


import { useAccount } from "@dogeos/dogeos-sdk"
 
export function ConnectedAccount() {
  const { address, chainType, chainId, currentWallet } = useAccount()
 
  if (!address) {
    return <p>Connect a wallet to continue.</p>
  }
 
  return (
    <div>
      <p>
        {address.slice(0, 6)}...{address.slice(-4)}
      </p>
      <p>
        {currentWallet?.info?.name ?? "Wallet"} on {chainType}:{chainId}
      </p>
    </div>
  )
}

balance is currently present in the return type but should not be treated as a source of truth for app balances. Fetch balances with your chain client or indexer.

Switch to DogeOS Chikyū Testnet

Use switchChain() from useAccount(). Pass the same Chain shape you used in provider configuration.


import { useAccount, type Chain } 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
 
export function SwitchNetworkButton() {
  const { switchChain } = useAccount()
 
  async function onSwitch() {
    await switchChain({
      chainType: "evm",
      chainInfo: dogeOSChikyuTestnet,
    })
  }
 
  return <button onClick={onSwitch}>Switch to DogeOS Chikyū</button>
}

If the wallet does not know the target EVM chain, the SDK asks the wallet adapter to add it.

Sign a Message


import { useAccount } from "@dogeos/dogeos-sdk"
 
export function SignMessageButton() {
  const { address, signMessage } = useAccount()
 
  async function onSign() {
    if (!address || !signMessage) return
 
    const signature = await signMessage({
      message: "Welcome to DogeOS",
      nonce: crypto.randomUUID(),
    })
 
    console.log(signature)
  }
 
  return (
    <button disabled={!address || !signMessage} onClick={onSign}>
      Sign message
    </button>
  )
}

The SDK requires a non-empty message. If you omit nonce, the SDK generates one.

signInWithWallet() creates a wallet-auth signature using the active provider. If you omit parameters, the SDK builds a default payload with the current domain, a standard statement, version 1, a random nonce, and issuedAt.


import { useAccount } from "@dogeos/dogeos-sdk"
 
export function SignInButton() {
  const { address, signInWithWallet } = useAccount()
 
  async function onSignIn() {
    if (!address) return
 
    const signature = await signInWithWallet({
      scheme: "https",
      domain: window.location.host,
      statement: "Sign in to Your App",
      version: "1",
      nonce: crypto.randomUUID(),
      issuedAt: new Date().toISOString(),
      resources: ["https://docs.dogeos.com"],
    })
 
    console.log(signature)
  }
 
  return (
    <button disabled={!address} onClick={onSignIn}>
      Sign in
    </button>
  )
}

Send the signed payload to your backend and verify it before creating an app session.

Call the Current Provider

currentProvider is the provider for the active chain type. For EVM wallets, use it like an EIP-1193 provider.


import { useAccount } from "@dogeos/dogeos-sdk"
 
export function SendEvmTransactionButton() {
  const { address, chainType, currentProvider } = useAccount()
 
  async function onSend() {
    if (!address || !currentProvider || chainType !== "evm") return
 
    const txHash = await currentProvider.request({
      method: "eth_sendTransaction",
      params: [
        {
          from: address,
          to: "0x0000000000000000000000000000000000000000",
          value: "0x0",
        },
      ],
    })
 
    console.log(txHash)
  }
 
  return <button onClick={onSend}>Send transaction</button>
}

For Dogecoin wallets, the SDK preserves the connected Dogecoin provider on currentProvider. Method names are provider-specific, so check the wallet provider you support before calling Dogecoin methods directly.

Access Current Wallet Connectors

useConnectors() returns connector providers for the current wallet and the active provider. This is useful when you need to inspect whether the connected wallet exposes EVM, Dogecoin, Solana, or Aptos provider entries.


import { useConnectors } from "@dogeos/dogeos-sdk"
 
export function ProviderFamilies() {
  const { connectors, currentProvider } = useConnectors()
 
  if (!connectors) {
    return <p>No wallet connected.</p>
  }
 
  return (
    <ul>
      <li>EVM: {connectors.evm ? "available" : "unavailable"}</li>
      <li>Dogecoin: {connectors.dogecoin ? "available" : "unavailable"}</li>
      <li>Current provider: {currentProvider ? "ready" : "missing"}</li>
    </ul>
  )
}

Programmatic Connect

useWalletConnect().connect() is available for advanced custom flows, but it takes a runtime WalletConnector that includes live providers:


await connect({
  wallet,
  chainType: "evm",
})

Do not pass an entry returned by getConnectors() to connect(). getConnectors() returns WalletConfig[] for provider configuration; connect() requires the initialized wallet object used by the SDK modal and adapter layer.

If you are not already managing those runtime connectors, call openModal() instead.

Connect With the Modal