Quickstart - CKB KeyWay

1. Install the SDK

npm install @ckb-keyway/react

pnpm add @ckb-keyway/react

yarn add @ckb-keyway/react

2. Enable cross-origin isolation

Fiber runs a multithreaded WASM node in the browser. A Next.js application must send these headers:

next.config.ts

import type { NextConfig } from "next";

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

export default nextConfig;

After deployment, window.crossOriginIsolated must be true.

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 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, starts the Fiber node, connects testnet relays, and then sets connection.

The managed API currently uses an origin allowlist. A new application will receive a CORS error until its exact production and development origins are registered with KeyWay.

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.

Next: activate Fiber payments

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

​1. Install the SDK

​2. Enable cross-origin isolation

​3. Add the provider

​4. Add login and wallet state

​5. Open the application

Next: activate Fiber payments

1. Install the SDK

2. Enable cross-origin isolation

3. Add the provider

4. Add login and wallet state

5. Open the application