DogeOS SDK

Connect your React app to DogeOS wallets. Let users sign in with email, Google or X, connect an external wallet, and use their MyDoge wallet inside the MyDoge dApp browser.

Quickstart · API reference · Developer console

Install

Use React 18 or later and React DOM 18 or later. Install wagmi, a required peer dependency, even if you use only the SDK hooks. TypeScript is supported.

npm install @dogeos/dogeos-sdk wagmi

pnpm add @dogeos/dogeos-sdk wagmi

Get a client ID

Create a project in the developer console and copy its client ID into your app. A project has separate Sandbox and Live client IDs.

Use a Sandbox client ID during development. Your project overview shows whether automatic access from localhost and 127.0.0.1 is ready. Add your hosted application origins to the matching environment before connecting from those domains. An origin includes the scheme, hostname and port, such as https://app.example.com.

Your client ID is public and belongs in the browser bundle. Your app needs one client ID to configure the SDK.

Connect a wallet

Wrap your app with WalletConnectProvider and import the stylesheet once. Components under the provider can use the SDK hooks.

"use client";

import {
  WalletConnectProvider,
  useAccount,
  useWalletConnect,
  type WalletConnectKitConfig,
} from "@dogeos/dogeos-sdk";
import "@dogeos/dogeos-sdk/style.css";

const config: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
};

function WalletButton() {
  const { openModal, isConnected, isConnecting, error } = useWalletConnect();
  const { address } = useAccount();

  return (
    <div>
      <button type="button" disabled={isConnecting} onClick={openModal}>
        {isConnecting ? "Connecting..." : isConnected ? address : "Connect wallet"}
      </button>
      {error ? <p role="alert">{error}</p> : null}
    </div>
  );
}

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

The stylesheet only styles SDK UI: the modal, toasts and WalletConnectEmbed. Your page keeps its own reset, fonts and colors. If you leave out the import, the provider adds the same stylesheet when it mounts. It adds its stylesheets as constructed stylesheets, which a Content Security Policy without 'unsafe-inline' in style-src allows. Browsers without constructed stylesheets (before Safari 16.4) get <style> elements instead, which such a policy blocks; importing style.css covers the stylesheet there, but not config.theme colors. To restyle SDK UI, target elements inside .dogeos-sdk.

openModal() opens the connection flow. Once connected, it opens the account view. Use disconnect() from useWalletConnect() to disconnect the active wallet.

In Next.js App Router, put the provider in a client component, as above. See the Next.js setup guide for a layout example.

Read the connected account

useAccount() exposes the active address, chain, wallet and provider.

"use client";

import { useAccount, useWalletConnect } from "@dogeos/dogeos-sdk";

export function AccountDetails() {
  const { isConnected } = useWalletConnect();
  const { address, chainType, chainId } = useAccount();

  if (!isConnected) return <p>Connect a wallet to continue.</p>;

  return (
    <div>
      <p>{address}</p>
      <p>{chainType}: {chainId}</p>
    </div>
  );
}

The same hook provides switchChain(), signMessage() and signInWithWallet(). Use currentProvider for chain-specific requests, or useConnectors() to access the connected wallet's other chain providers. See account actions and signing examples.

A wallet connection or signature alone does not create an authenticated session for your backend. For wallet-based sign-in, have your server issue and verify a fresh challenge before creating a session. Follow the sign-in guide.

Connection and readiness

Use the state that matches what your app needs.

WalletConnectProvider renders your app straight away outside MyDoge. In an Android in-app browser (a WebView), the embedded wallet, and with email or social sign-in configured also restoring a saved connection, wait until the page finishes loading, for up to 5 seconds, before they start: MyDoge's in-app browser can still identify itself until then. walletStatus reports initializing meanwhile. Inside MyDoge the provider shows a short "Preparing wallet connection…" status in place of your app while the native wallet gets ready, with a Retry button if it takes longer than 5 seconds. On some older Android devices MyDoge identifies itself late, so your app can render once in browser mode and then mount again in native mode.

Inside MyDoge, the SDK selects the native wallet automatically. Keep your normal provider configuration and connection button. A native or external wallet can be connected while the embedded wallet is disabled, so do not require isWalletReady for all wallet actions. See native wallet connections.

Inside the MyDoge app

In MyDoge's dApp browser the native app answers every wallet request, and the SDK shows none of its own wallet UI and opens no popups. The same code works in a browser and in MyDoge:

• openModal() asks MyDoge to connect. When a wallet is already connected, it opens MyDoge's account sheet on MyDoge builds that support it; on builds without it, including 3.1.1 (build 652) and earlier, it does nothing and logs a warning, so give users a Disconnect button and, if you support several networks, a switchChain() control.
• WalletConnectEmbed shows a small MyDoge card with Connect, Account and Disconnect buttons instead of the wallet list. Its Account button needs the same account-sheet support.
• A first visit does not prompt on page load. A saved connection is restored, and MyDoge builds that support it also reconnect a dApp the user already approved; otherwise the SDK waits for the user to tap connect.
• disconnect() also revokes the dApp's approval in MyDoge.
• DogeOS email and social sign-in (useDogeOSAuth().login()) reject with DogeOSHostError. Use signInWithWallet() and verify the signature on your server.

useWalletHost() tells you where the dApp is running and gives you a connect call that returns the account in both places:

import { isWalletError, useWalletHost, WalletErrorCode } from "@dogeos/dogeos-sdk";

function ConnectButton() {
  const { isNativeHost, connect } = useWalletHost();

  const onClick = async () => {
    try {
      const { address } = await connect();
      console.log("Connected", address);
    } catch (error) {
      if (isWalletError(error, WalletErrorCode.UserRejected)) return;
      throw error;
    }
  };

  return <button type="button" onClick={onClick}>{isNativeHost ? "Connect MyDoge" : "Connect wallet"}</button>;
}

Configure your app

Pass optional settings alongside clientId in WalletConnectKitConfig.

See configuration for examples, including DogeOS Chikyū Testnet.

WalletConnect

To enable WalletConnect, create a project in the Reown dashboard and pass its project ID. It is separate from your DogeOS client ID.

import type { WalletConnectKitConfig } from "@dogeos/dogeos-sdk";

const config: WalletConnectKitConfig = {
  clientId: "YOUR_DOGEOS_CLIENT_ID",
  walletConnectProjectId: "YOUR_WALLETCONNECT_PROJECT_ID",
  metadata: {
    name: "My DogeOS app",
    description: "My DogeOS application",
    url: "https://app.example.com",
    icons: ["https://app.example.com/icon.png"],
  },
};

Without walletConnectProjectId, WalletConnect is hidden. Email, social login and supported injected wallets remain available. Add your app's origins to your Reown project if you use its origin allowlist.

Render the wallet UI inline

Use WalletConnectEmbed inside your existing provider when the wallet flow belongs in a page instead of a modal.

"use client";

import { WalletConnectEmbed } from "@dogeos/dogeos-sdk";

export function WalletPanel() {
  return <WalletConnectEmbed style={{ width: "100%", maxWidth: 448 }} />;
}

WalletConnectEmbed also takes these props:

• initialView: the picker it starts on and returns to, "walletList" or "walletSearch". By default it follows config.login.
• hideHeader: leaves out the starting view's title, for a page that gives the embed its own heading. Controls in that row, such as a link to the wallet list, stay. Later views keep their titles.
• keepPickerAfterConnect: keeps the picker on screen after a wallet connects, instead of showing the account view. Connecting another wallet, its errors and the install guide still show.

Inside MyDoge the embed is always the MyDoge card, whatever these props say.

Link a second wallet

To let a signed-in user prove they own another wallet, for example to link it to their account, render a second WalletConnectProvider around an embed. Configure it so it doesn't take over the page's main connection:

"use client";

import { WalletConnectEmbed, WalletConnectProvider, type WalletConnectKitConfig } from "@dogeos/dogeos-sdk";

const linkConfig: WalletConnectKitConfig = {
  clientId: process.env.NEXT_PUBLIC_DOGEOS_CLIENT_ID!,
  login: { basicLogins: ["externalWallets"], socialLogins: [] },
  // Connect only when the user picks a wallet, and save nothing.
  autoRestore: false,
  persistConnection: false,
  // Ask an EVM wallet to show its account picker even for a site it already approved.
  forceAccountSelection: { blockedAddresses: alreadyLinkedAddresses },
};

export function LinkWallet() {
  return (
    <WalletConnectProvider config={linkConfig}>
      <WalletConnectEmbed initialView="walletSearch" hideHeader keepPickerAfterConnect />
    </WalletConnectProvider>
  );
}

• autoRestore: false skips restoring a saved connection on load, and inside MyDoge the silent reconnect too. It does not cover the DogeOS sign-in: on a page where the user is signed in, a provider that offers social logins connects their Social Wallet on load. The login line above keeps the link provider to external wallets, so that doesn't happen.
• persistConnection: false saves no reconnect hint, and leaves the main provider's alone.
• forceAccountSelection applies to EVM browser wallets; MyDoge and the embedded wallet ignore it. Before connecting it asks the wallet for the site's account permission again (EIP-2255), which makes most wallets show their picker. If the wallet supports no such request and returns one of blockedAddresses, the connection fails with a message asking the user to disconnect the site in their wallet. revokePermissions: true revokes the permission first, for wallets that skip their picker otherwise. The permission is per site, so that also disconnects a main connection to the same wallet on the page.

Ask for a signature from the connected wallet to prove ownership, and check it on your server.

Link to another dApp from inside MyDoge

In MyDoge's in-app browser, a plain https link to another dApp loads in your dApp's browser session. The wallet stays bound to your dApp's origin, so the other dApp can't connect. Link to it with a mydoge://dapp URL instead: MyDoge then opens the target as its own dApp with its own wallet session. The user sees the target's details screen and taps Open; your dApp closes only then.

isInMyDogeBrowser() detects MyDoge's in-app browser through its EIP-6963 announcement (rdns com.mydoge.wallet). It resolves false after a timeout (500 ms by default) and during server rendering. getDappHref() returns the mydoge://dapp link inside MyDoge and the plain URL everywhere else.

"use client";

import { useEffect, useState } from "react";
import { getDappHref, isInMyDogeBrowser } from "@dogeos/dogeos-sdk";

const BUY_MOON_URL = "https://muchfi.example/buy?token=MOON";

export function BuyMoonLink() {
  // null until detection finishes, so no plain link can be tapped inside MyDoge first.
  const [inMyDoge, setInMyDoge] = useState<boolean | null>(null);

  useEffect(() => {
    void isInMyDogeBrowser().then(setInMyDoge);
  }, []);

  const href = inMyDoge === null ? undefined : getDappHref(BUY_MOON_URL, { inMyDoge });
  return <a href={href}>Buy MOON</a>;
}

Leave the link without an href until detection finishes. A server-rendered plain link can be tapped inside MyDoge before your page hydrates, which loads the target in your dApp's session. Outside MyDoge, detection takes up to 500 ms after hydration.

getMyDogeDappLink(targetUrl) builds the link directly: mydoge://dapp?url= followed by the complete target URL, encoded once with encodeURIComponent. Pass the raw https URL, not an already encoded one. It normalizes the URL first, as a browser would (for example, a space becomes %20), because MyDoge rejects raw spaces and similar characters. It throws a TypeError for anything other than an absolute https URL, for a URL with a username or password, and for a URL over MyDoge's 8 KiB limit. getDappHref() applies the same checks in every browser, so a bad URL shows up in ordinary testing.

These rules come from MyDoge's dApp deep-link partner guide:

• Set the href before the tap. Detect MyDoge first, then put the link in the element the user taps. A plain link, a target="_blank" link, or window.open called synchronously in the tap handler all work. Setting location.href doesn't work on iOS, and navigation after an await or a timer may be blocked.
• Only top-level pages work. Links inside an iframe are ignored on iOS and may be ignored on Android.
• The target must be listed in MyDoge. Its origin must exactly match the destination dApp's published CMS projectLink origin. Subdomains such as www and non-default ports count as different origins. Path, query and fragment are passed through unchanged.
• MyDoge 3.1.1 (build 652) or later is required. Earlier builds ignore a tapped mydoge:// link, so nothing happens. They announce the same com.mydoge.wallet provider, so a page can't tell them apart from 652.
• MyDoge ignores a second link within two seconds.

Documentation

• Quickstart for installation and provider setup.
• Configuration for chains, login options and themes.
• Core workflows for signing, network changes and provider requests.
• Embedded wallets for inline UI and native MyDoge behavior.
• Wagmi integration for apps that already use Wagmi hooks.
• API reference for components, hooks and helpers.
• Troubleshooting for connection errors and browser requirements.