SDK Reference

This page documents the public React SDK exports from @zerodev/wallet-react. Use the guide pages for complete workflows, and use this page when you need exact parameters and return values.

Import

import {
  OAUTH_PROVIDERS,
  createZeroDevWalletStore,
  generateOAuthNonce,
  getZeroDevConnector,
  getZeroDevStore,
  getZeroDevWallet,
  useAuthenticateOAuth,
  useAuthenticators,
  useExportPrivateKey,
  useExportWallet,
  useLoginPasskey,
  useRefreshSession,
  useRegisterPasskey,
  useSendMagicLink,
  useSendOTP,
  useVerifyMagicLink,
  useVerifyOTP,
  verifyGoogleLoginUrl,
  zeroDevWallet,
  type GetOAuthSessionIdFn,
  type OAuthProvider,
  type WalletMode,
  type ZeroDevProvider,
  type ZeroDevWalletConnectorParams,
  type ZeroDevWalletState,
} from "@zerodev/wallet-react";

Connector

zeroDevWallet(params)

Creates the Wagmi connector used by createConfig.

import { zeroDevWallet } from "@zerodev/wallet-react";
 
const connector = zeroDevWallet({
  projectId: "<your-project-id>",
  aaUrl: "<your-chain-specific-zerodev-rpc-url>",
  chains: [arbitrumSepolia],
  mode: "7702",
});

Parameters

Returns

CreateConnectorFn, suitable for Wagmi createConfig({ connectors: [...] }).

Account modes

Hook options

All authentication, session, and export hooks are TanStack Query hooks. Mutation hooks return UseMutationResult, so you can use mutate, mutateAsync, isPending, error, data, and reset.

Most hooks accept an optional config field when you need to pass a specific Wagmi config instead of using the nearest WagmiProvider.

const { mutateAsync, isPending, error } = useRegisterPasskey({
  mutation: {
    onSuccess: () => console.log("signed in"),
  },
});

Passkeys

useRegisterPasskey(options?)

Registers a new passkey and authenticates the user. On success, the hook stores the session, derives the wallet account, and connects the ZeroDev connector in Wagmi.

Mutation variables

Returns

UseMutationResult<void, Error, void | { connector?: Connector }>

const registerPasskey = useRegisterPasskey();
 
<button onClick={() => registerPasskey.mutateAsync()}>
  Register passkey
</button>;

useLoginPasskey(options?)

Authenticates with an existing passkey. On success, it stores the session, derives the wallet account, and connects the ZeroDev connector in Wagmi.

Mutation variables

Returns

UseMutationResult<void, Error, void | { connector?: Connector }>

const loginPasskey = useLoginPasskey();
 
<button onClick={() => loginPasskey.mutateAsync()}>
  Login with passkey
</button>;

Email OTP

useSendOTP(options?)

Sends an email OTP code.

Mutation variables

Returns

UseMutationResult<{ otpId: string; otpEncryptionTargetBundle: string }, Error, SendOTPVariables>

Store both returned values. useVerifyOTP needs the matching otpId and otpEncryptionTargetBundle.

const sendOTP = useSendOTP();
const verifyOTP = useVerifyOTP();
 
const sent = await sendOTP.mutateAsync({ email });
 
await verifyOTP.mutateAsync({
  otpId: sent.otpId,
  otpEncryptionTargetBundle: sent.otpEncryptionTargetBundle,
  code,
});

useVerifyOTP(options?)

Verifies an OTP code and authenticates the user. On success, it stores the session, derives the wallet account, and connects the ZeroDev connector in Wagmi.

Mutation variables

Returns

UseMutationResult<void, Error, VerifyOTPVariables>

Magic links

useSendMagicLink(options?)

Sends a magic link email.

Mutation variables

Returns

UseMutationResult<{ otpId: string; otpEncryptionTargetBundle: string }, Error, SendMagicLinkVariables>

Store both returned values. useVerifyMagicLink needs the matching otpId and otpEncryptionTargetBundle.

const sendMagicLink = useSendMagicLink();
 
const sent = await sendMagicLink.mutateAsync({
  email,
});

useVerifyMagicLink(options?)

Verifies the magic link code and authenticates the user.

Mutation variables

Returns

UseMutationResult<void, Error, VerifyMagicLinkVariables>

OAuth

useAuthenticateOAuth(options?)

Starts the web OAuth flow using a popup and authenticates the user after the popup returns a session ID. The web hook uses window.location.href as the redirect URI and window.location.origin for popup polling.

Options

Mutation variables

Returns

UseMutationResult<void, Error, { provider: OAuthProvider }>

const google = useAuthenticateOAuth();
 
<button
  onClick={() => google.mutateAsync({ provider: OAUTH_PROVIDERS.GOOGLE })}
>
  Continue with Google
</button>;

OAUTH_PROVIDERS

Supported OAuth provider constants.

OAuthProvider

Type union of supported OAuth provider values. Currently "google".

GetOAuthSessionIdFn

Function type for custom OAuth adapters.

type GetOAuthSessionIdFn = (params: {
  oauthUrl: string;
  provider: OAuthProvider;
}) => Promise<string>;

The web hook supplies this automatically. Custom platform flows use this shape to open the OAuth URL and return a session ID.

Sessions

useRefreshSession(options?)

Refreshes the current authenticated session and updates connector state.

Mutation variables

Returns

UseMutationResult<unknown, Error, { connector?: Connector }>

Throws when there is no active session to refresh.

const refreshSession = useRefreshSession();
 
await refreshSession.mutateAsync({});

Authenticators

useAuthenticators(options?)

Reads authenticators associated with the current user in the connected project/sub-organization. The result can include OAuth authenticators, passkeys, email contacts, and API keys.

Options

Returns

UseQueryResult<GetAuthenticatorsReturnType, Error>

const authenticators = useAuthenticators({
  query: { enabled: isConnected },
});

Wallet export

useExportWallet(options?)

Renders the secure Turnkey export iframe into a container element and injects the wallet export bundle.

Mutation variables

Returns

UseMutationResult<void, Error, ExportWalletVariables>

const exportWallet = useExportWallet();
 
await exportWallet.mutateAsync({
  iframeContainerId: "export-wallet",
  iframeStyles: {
    width: "100%",
    height: "260px",
  },
});

useExportPrivateKey(options?)

Renders the secure Turnkey export iframe into a container element and injects a private key export bundle.

Mutation variables

Returns

UseMutationResult<void, Error, ExportPrivateKeyVariables>

const exportPrivateKey = useExportPrivateKey();
 
await exportPrivateKey.mutateAsync({
  iframeContainerId: "export-private-key",
  keyFormat: "Hexadecimal",
});

Store and connector helpers

These helpers are lower-level escape hatches. Most apps should use Wagmi hooks and ZeroDev auth hooks instead.

getZeroDevConnector(config)

Finds the ZeroDev connector in a Wagmi config.

Returns the ZeroDev connector, including rpId and getStore(). Throws if the connector is not found.

getZeroDevStore(connector)

Gets the Zustand store associated with a ZeroDev connector.

Returns Promise<ReturnType<typeof createZeroDevWalletStore>>.

getZeroDevWallet(store)

Reads the initialized wallet SDK instance from the ZeroDev store.

Returns ZeroDevWalletSDK. Throws "Wallet not initialized" if connector setup has not completed.

createZeroDevWalletStore(options?)

Creates the internal Zustand store used by the connector.

The store persists only session and activeChainId under the zerodev-wallet key.

OAuth utilities

generateOAuthNonce(publicKey)

Computes the nonce expected in a Google OAuth URL for a wallet public key.

Returns a lowercase hex SHA-256 hash string without 0x.

verifyGoogleLoginUrl(loginUrl, publicKey)

Verifies that a Google OAuth URL is valid for the wallet public key.

Returns void. Throws if the URL is malformed, the host is not accounts.google.com, the nonce is missing, or the nonce does not match generateOAuthNonce(publicKey).

Types

WalletMode

type WalletMode = "4337" | "7702";

ZeroDevWalletConnectorParams

Connector parameter type for zeroDevWallet. It matches the connector parameters above.

ZeroDevProvider

ZeroDev EIP-1193 provider type returned by the connector's getProvider() method.

ZeroDevWalletState

Zustand store state type used internally by the connector.

Important fields include:

Related guides

• Quickstart
• Passkeys
• Email OTP
• Magic Link
• Google OAuth
• Session Management
• Send a Transaction
• Export Wallet