Skip to main content

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.

​
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

1

Enable Auth Proxy

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

Choose auth methods

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

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.com

​
Local development (super-repo stack)

When running ./local-dev.sh start with local-gateway:
VariableLocal value
NEXT_PUBLIC_BASE_URLhttps://api.0xkey.com
NEXT_PUBLIC_AUTH_PROXY_URLhttps://auth.0xkey.com
NEXT_PUBLIC_ORGANIZATION_IDFrom /tmp/0xkey-local-dev/pids/dev-org-id.txt after bootstrap
NEXT_PUBLIC_AUTH_PROXY_CONFIG_IDFixed dev ID 00000000-0000-4000-8000-0000000000b1 (see local-dev skill)
Add 127.0.0.1 0xkey.com api.0xkey.com auth.0xkey.com app.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>
  );
}

​
Step 5 — Log in or sign up

"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

​
Troubleshooting

IssueCheck
CORS / origin rejectedAuth Proxy allowed origins in Dashboard
Passkey fails locallyrpId must match page hostname; use https://app.0xkey.com via local-gateway
Auth Proxy 404NEXT_PUBLIC_AUTH_PROXY_URL and config ID
API stamp errorsOrganization ID matches the org that owns the proxy config