The DogeOS SDK gives your app one way to connect a wallet, whatever wallet the user has and wherever your page is open. Behind that one connect button there are three quite different kinds of wallet, and a few distinctions that are easy to blur. This page explains them.
Three Kinds of Wallet#
Embedded wallets are created for the user when they sign in with email, Google or X. DogeOS runs the sign-in, and the wallet lives in a frame from embedded-wallet.mydoge.com that the SDK loads into your page. The user never handles a recovery phrase. In MyDoge these are called social wallets, and each sign-in method has its own wallet with its own address: signing in with X and signing in with email give two different addresses.
External wallets are wallets the user already has: a browser extension the SDK finds through EIP-6963, or a mobile wallet connected through WalletConnect when you supply a WalletConnect project ID. The SDK talks to them through each wallet’s own provider. A MyDoge classic wallet, one made from a recovery phrase, is an external wallet to the SDK in an ordinary browser, where it connects through WalletConnect.
The MyDoge app’s own wallet answers inside MyDoge’s in-app browser. There, MyDoge injects a provider into your page, and the SDK uses it directly instead of showing its wallet list or loading the embedded wallet. See About the MyDoge In-App Browser.
Your app sees all three through the same hooks. useAccount() gives the address, chain and provider; useWalletConnect() gives the connection state. That’s deliberate: most of your code shouldn’t care which kind of wallet is behind the account.
Connected, Ready and Signed In#
Three states are easy to confuse because they often change at the same moment.
Connected (isConnected, connectionStatus) means a wallet has given your app an account. It’s the state wallet actions depend on.
Ready (walletStatus, isWalletReady) describes only the embedded wallet: whether its frame has loaded and can accept a sign-in. It says nothing about external wallets or the MyDoge wallet, which don’t need it. That’s why walletStatus is "disabled" when you turn off embedded sign-in, and inside MyDoge, even while a wallet is connected.
Signed in belongs to your app, not to the SDK. A connected wallet proves nothing to your server, and neither does a signature on its own: anyone can replay a signature they’ve seen. A session starts only when your server issues a fresh challenge, the user signs it, and your server verifies that exact signature. The SDK helps with the signing half (signMessage(), and signInWithWallet() for a Sign-In with Ethereum message on EVM chains), but the verification is yours. See Sign Messages and Sign In Users.
Chain Families#
The SDK groups networks into chain families: evm, solana and dogecoin. A wallet can support more than one family, and the user is connected on one family at a time, which useAccount().chainType reports.
DogeOS Chikyū Testnet is an EVM chain, so it sits under evm, next to Ethereum and other EVM networks. It isn’t part of the dogecoin family, which is the Dogecoin network itself. An app built on DogeOS usually needs only evm.
If you don’t configure any chains, the SDK offers its own defaults: several EVM mainnets (Ethereum, BNB Smart Chain, Optimism, Arbitrum, Linea, Base and Polygon), Solana and Dogecoin. DogeOS Chikyū isn’t among them, which is why most apps set chains themselves.
Testnets and Production Services#
Choosing a testnet changes which blockchain your app talks to. It doesn’t change where the SDK signs users in or loads the embedded wallet: the published SDK always uses DogeOS production services. Your client ID’s Sandbox and Live environments control which origins may use those services, not which services they are.