> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xkey.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started with React Wallet Kit
> Set up @0xkey-io/react-wallet-kit with Auth Proxy, environment variables, and your first login.
## Prerequisites
* Node.js 18+
* A 0xkey organization ([Dashboard](https://app.0xkey.io) 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
Open the Dashboard **Auth** (Wallet Kit) section and turn **Auth Proxy** on.
Enable the methods you need (e.g. **Email OTP** and **Passkeys** for a typical embedded wallet).
Copy your **Organization ID** and **Auth Proxy config ID** — you will pass them to the SDK.
See [Auth Proxy](/reference/auth-proxy) for endpoint details and CORS / allowed-origins configuration.
## Step 2 — Create a Next.js app (optional)
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
NEXT_PUBLIC_ORGANIZATION_ID=
NEXT_PUBLIC_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](/0xkey/roadmap):
| 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`:
```tsx app/providers.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
"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 (
console.error("0xkey error:", error),
}}
>
{children}
);
}
```
```tsx app/layout.tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import "@0xkey-io/react-wallet-kit/styles.css";
import "./globals.css";
import { Providers } from "./providers";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
## Step 5 — Log in or sign up
```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
"use client";
import { useZeroXKey } from "@0xkey-io/react-wallet-kit";
export function AuthButton() {
const { handleLogin, user, wallets } = useZeroXKey();
if (user) {
return (
Signed in as {user.userName} — {wallets.length} wallet(s)
);
}
return ;
}
```
`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](/embedded-wallets/code-examples/signing-transactions).
**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](/0xkey/roadmap) before relying on send helpers.
## Reference implementations
* [react-wallet-kit example](https://github.com/0xkey-io/sdk-js/tree/main/examples/react-wallet-kit) — comprehensive EWK demo
* [demo-embedded-wallet](https://github.com/0xkey-io/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 |