Getting started with React Wallet Kit

Prerequisites

Node.js 18+
A 0xkey organization (Dashboard or local stack via ./local-dev.sh start)
Auth Proxy enabled for your organization (Dashboard → Auth / Wallet Kit)

Step 1 — Configure Auth Proxy in the Dashboard

Enable Auth Proxy

Open the Dashboard Auth (Wallet Kit) section and turn Auth Proxy on.

Choose auth methods

Enable the methods you need (e.g. Email OTP and Passkeys for a typical embedded wallet).

Copy IDs

Copy your Organization ID and Auth Proxy config ID — you will pass them to the SDK.

See Auth Proxy for endpoint details and CORS / allowed-origins configuration.

Step 2 — Create a Next.js app (optional)

npx create-next-app@latest my-embedded-wallet
cd my-embedded-wallet
pnpm add @0xkey-io/react-wallet-kit

Step 3 — Environment variables

Create .env.local:

NEXT_PUBLIC_ORGANIZATION_ID=<your-org-id>
NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID=<your-auth-proxy-config-id>

# Optional overrides (defaults shown)
NEXT_PUBLIC_BASE_URL=https://api.0xkey.io
NEXT_PUBLIC_AUTH_PROXY_URL=https://authproxy.0xkey.io

Local development (super-repo stack)

When running ./local-dev.sh start with local-gateway:

Variable	Local value
`NEXT_PUBLIC_BASE_URL`	`https://api.0xkey.com`
`NEXT_PUBLIC_AUTH_PROXY_URL`	`https://authproxy.0xkey.com`
`NEXT_PUBLIC_ORGANIZATION_ID`	From `/tmp/0xkey-local-dev/pids/dev-org-id.txt` after bootstrap
`NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID`	Fixed dev ID `00000000-0000-4000-8000-0000000000b1` (see local-dev skill)

Add

127.0.0.1 0xkey.com api.0xkey.com authproxy.0xkey.com app.0xkey.com docs.0xkey.com export.0xkey.com import.0xkey.com demo.0xkey.com

to /etc/hosts and trust the local-gateway CA certificate.

Step 4 — Wrap your app with `ZeroXKeyProvider`

With the App Router, keep layout.tsx as a server component and add a client providers.tsx:

app/providers.tsx

"use client";

import {
  ZeroXKeyProvider,
  type ZeroXKeyProviderConfig,
} from "@0xkey-io/react-wallet-kit";

const config: ZeroXKeyProviderConfig = {
  organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!,
  authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID!,
  baseUrl: process.env.NEXT_PUBLIC_BASE_URL,
  authProxyUrl: process.env.NEXT_PUBLIC_AUTH_PROXY_URL,
};

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ZeroXKeyProvider
      config={config}
      callbacks={{
        onError: (error) => console.error("0xkey error:", error),
      }}
    >
      {children}
    </ZeroXKeyProvider>
  );
}

app/layout.tsx

import "@0xkey-io/react-wallet-kit/styles.css";
import "./globals.css";
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

"use client";

import { useZeroXKey } from "@0xkey-io/react-wallet-kit";

export function AuthButton() {
  const { handleLogin, user, wallets } = useZeroXKey();

  if (user) {
    return (
      <p>
        Signed in as {user.userName} — {wallets.length} wallet(s)
      </p>
    );
  }

  return <button onClick={handleLogin}>Log in / Sign up</button>;
}

handleLogin opens a modal with every auth method enabled in your Auth Proxy config.

Step 6 — Sign a message or transaction

After login, use handleSignMessage, handleSignTransaction, or the lower-level clients documented in signing examples.

Phase 1 limits. On-chain broadcast and gas sponsorship are not production-ready — eth_send_raw_transaction returns a mock receipt today. Design signing-first flows and check the Roadmap before relying on send helpers.

Reference implementations

react-wallet-kit example — comprehensive EWK demo
demo-embedded-wallet — minimal integration sample

Troubleshooting

Issue	Check
CORS / origin rejected	Auth Proxy allowed origins in Dashboard
Passkey fails locally	`rpId` must match page hostname; use `https://app.0xkey.com` via local-gateway
Auth Proxy 404	`NEXT_PUBLIC_AUTH_PROXY_URL` and config ID
API stamp errors	Organization ID matches the org that owns the proxy config

​Prerequisites

​Step 1 — Configure Auth Proxy in the Dashboard

​Step 2 — Create a Next.js app (optional)

​Step 3 — Environment variables

​Local development (super-repo stack)

​Step 4 — Wrap your app with ZeroXKeyProvider

​Step 5 — Log in or sign up

​Step 6 — Sign a message or transaction

​Reference implementations

​Troubleshooting

Prerequisites

Step 1 — Configure Auth Proxy in the Dashboard

Step 2 — Create a Next.js app (optional)

Step 3 — Environment variables

Local development (super-repo stack)

Step 4 — Wrap your app with `ZeroXKeyProvider`

Step 5 — Log in or sign up

Step 6 — Sign a message or transaction

Reference implementations

Troubleshooting