Quickstart

1. Install the SDK

npm install @ckb-keyway/react

pnpm add @ckb-keyway/react

yarn add @ckb-keyway/react

2. Register your application

Open the KeyWay developer console, create an application, and add every exact browser origin that will use it. Add local development origins separately from production origins, then copy the public app ID.

3. Add the provider

Render KeyWayProvider in a client component above every component that uses KeyWay.

app/providers.tsx

"use client";

import { KeyWayProvider } from "@ckb-keyway/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <KeyWayProvider appId="keyway_..." appName="Acme Pay" theme="light">
      {children}
    </KeyWayProvider>
  );
}

app/layout.tsx

import { Providers } from "./providers";

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

app/wallet.tsx

"use client";

import { KeyWayLoginButton, useKeyWay } from "@ckb-keyway/react";

export function Wallet() {
  const { ready, authenticated, connection, status, error } = useKeyWay();

  if (!ready) return <p>Loading login...</p>;

  return (
    <section>
      <KeyWayLoginButton />
      {authenticated && status === "connecting" ? <p>Recovering wallet...</p> : null}
      {connection ? <p>CKB address: {connection.wallet.ckbAddress}</p> : null}
      {error ? <p role="alert">{error.message}</p> : null}
    </section>
  );
}

autoConnect defaults to true. After OTP verification, the provider recovers the wallet, connects its persistent managed Fiber node, and then sets connection. Managed mode is the default from SDK 0.0.7 and requires no WASM isolation headers.

The app ID is public. It identifies the integration and lets KeyWay enforce its registered origins; it is not a secret credential.

5. Open the application

Select Log in, enter an email address, and submit the six-digit code. The same email recovers the same CKB account.

Optional browser mode

Set nodeMode="browser" on the provider to run Fiber WASM locally. This requires cross-origin isolation. For Next.js, add these response headers in next.config.ts:

export default {
  async headers() {
    return [{
      source: "/(.*)",
      headers: [
        { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
        { key: "Cross-Origin-Embedder-Policy", value: "require-corp" },
      ],
    }];
  },
};

For Vite, configure the same headers under server.headers for local development and on your production host. Verify window.crossOriginIsolated === true before startup. Browser state moves between devices only after a successful explicit logout backup. Switching between browser and managed mode does not migrate channels.

Next: activate Fiber payments

Open a channel and make the account ready to send and receive.

Get started

Build

Reference

1. Install the SDK

2. Register your application

3. Add the provider

5. Open the application

Optional browser mode

Next: activate Fiber payments

​1. Install the SDK

​2. Register your application

​3. Add the provider

​4. Add login and wallet state

​5. Open the application

​Optional browser mode

Next: activate Fiber payments

1. Install the SDK

2. Register your application

3. Add the provider

4. Add login and wallet state

5. Open the application

Optional browser mode