React SDK

`KeyWayProvider`

Wrap the part of the React tree that uses KeyWay.

<KeyWayProvider
  appId="keyway_..."
  appName="Your app"
  theme="light"
  autoConnect
  onError={(error) => console.error(error)}
  onLifecycle={(event) => console.log(event.stage, event.elapsedMs)}
>
  <App />
</KeyWayProvider>

string

Public application ID from the KeyWay developer console. SDK requests are accepted only from origins registered to this application.

string

default:"CKB KeyWay"

Name displayed in the embedded login UI. Limited to 64 characters.

"light" | "dark"

default:"light"

Appearance of KeyWay’s login and funding confirmation modals.

boolean

default:"true"

Recover the wallet and start Fiber automatically after authentication.

"browser" | "managed"

default:"managed"

Select the Fiber runtime. From SDK 0.0.7, managed mode uses KeyWay’s persistent native testnet node by default, subject to host capacity limits. Browser mode runs WASM locally. Switching modes does not migrate channels.

ConfirmFunding

Optional callback for approving the validated on-chain channel funding transaction. Return true to continue to Lit-authorized signing or false to abort. When omitted, KeyWay renders its styled built-in confirmation modal.

(error: Error) => void

Receives connection and device-lease failures.

(event: KeyWayLifecycleEvent) => void

Receives structured wallet recovery, lease, database restore, WASM startup, peer connection, synchronization, and ready events with elapsed milliseconds.

`useKeyWay()`

const {
  ready,
  authenticated,
  user,
  connection,
  wallet,
  walletReady,
  fiberStarting,
  fiberReady,
  fiberError,
  lifecycleStage,
  lifecycleTimings,
  status,
  error,
  login,
  logout,
  connect,
  disconnect,
} = useKeyWay();

Field	Type	Purpose
`ready`	`boolean`	Stored session validation has finished.
`authenticated`	`boolean`	The user has a valid KeyWay session.
`user`	`{ id: string }`	Stable authenticated user identity.
`connection`	`ConnectedKeyWay \| ConnectedManagedKeyWay \| undefined`	Recovered wallet and active browser or managed Fiber client.
`wallet`	`PublicWallet \| undefined`	Recovered CKB identity, available before Fiber finishes starting.
`walletReady`	`boolean`	Wallet recovery has completed.
`fiberStarting`	`boolean`	Fiber startup is still in progress.
`fiberReady`	`boolean`	Fiber is ready for channels, invoices, and payments.
`fiberError`	`Error \| undefined`	Fiber-specific startup or lease failure.
`lifecycleStage`	`KeyWayLifecycleStage \| undefined`	Current structured startup stage.
`lifecycleTimings`	`Partial<Record<KeyWayLifecycleStage, number>>`	Elapsed milliseconds recorded for reached stages.
`status`	`KeyWayStatus`	`idle`, `authenticating`, `connecting`, `connected`, `disconnecting`, or `error`.
`error`	`Error \| undefined`	Latest provider connection error.
`login()`	`() => void`	Open the email OTP modal.
`logout()`	`() => Promise<void>`	Clear the session; browser mode first backs up and stops Fiber.
`connect()`	`() => Promise<KeyWayConnection>`	Recover and connect the selected runtime manually.
`disconnect()`	`() => Promise<void>`	Disconnect the client; stop Fiber only in browser mode.

`connection`

type ConnectedKeyWay = {
  keyway: KeyWay;
  wallet: PublicWallet;
  node: NodeInfoResult;
  peers: ListPeersResult["peers"];
  balanceShannons: bigint;
};

Use connection.wallet.ckbAddress for the recovered address and connection.keyway for Fiber operations. Both connection modes implement the recommended methods below. Inspect connection.mode when an application needs runtime-specific UI. Browser mode requires cross-origin isolation and explicit-logout database handoff. Managed mode stays online outside the page lifecycle and does not migrate existing browser channels. The managed host holds operational node keys and state; it is a different trust model from a local browser node.

Recommended client methods

Method	Purpose
`getCkbBalance()`	Read indexed on-chain capacity in shannons.
`activateCkbChannel(options?, onProgress?)`	Fund a channel with safe defaults or an explicit amount, peer, visibility, and fee rates.
`waitForChannelReady(channelId, options?)`	Wait until a funding transaction becomes a usable channel.
`listChannels(options)`	Read channels, state, local balance, and remote balance.
`getChannels(options?)`	Read normalized lifecycle state and bigint local/remote balances.
`closeChannel(channelId, options?)`	Cooperatively or forcibly close a channel with typed failures.
`newInvoice(params)`	Create a Fiber invoice.
`parseInvoice(params)`	Decode and validate an invoice before payment.
`sendPayment(params)`	Start a routed Fiber payment.
`preflightPayment(params)`	Dry-run a payment and return route/fee readiness or a typed failure.
`waitForPayment(paymentHash, options?)`	Wait for payment success or failure.
`listPeers()`	Inspect connected Fiber peers.
`nodeInfo()`	Read the local Fiber node identity.
`stop()`	Disconnect the client; browser mode also stops the node and releases device guards. Prefer provider `disconnect()`.

Buttons

KeyWayLoginButton toggles login/logout. KeyWayConnectButton starts or stops Fiber and opens login first when needed. Both accept normal button attributes and label overrides.

<KeyWayLoginButton loginLabel="Continue with email" />
<KeyWayConnectButton connectLabel="Start payments" />

Get started

Build

Reference

`KeyWayProvider`

`useKeyWay()`

`connection`

Recommended client methods

Buttons

​KeyWayProvider

​useKeyWay()

​connection

​Recommended client methods

​Buttons

`KeyWayProvider`

`useKeyWay()`

`connection`

Recommended client methods

Buttons