SDK Overview

The KEA Wallet SDK is a suite of TypeScript packages (@kea-wallet/*) that lets dApps integrate KEA Wallet for user authentication and transaction signing on the Thru blockchain. It provides a seamless, non-custodial experience using Passkeys (WebAuthn) — no browser extension or seed phrases required.

What Is the KEA Wallet SDK?

The SDK connects your application to KEA Wallet through a secure iframe. Users authenticate with their device's passkey (biometric or hardware key), authorize your dApp, and sign transactions — all without exposing private keys to your code.

Key benefits:

• No extension required — works in any modern browser via a secure iframe hosted at keawallet.com
• Passkey authentication — industry-standard WebAuthn for phishing-resistant, passwordless auth
• Thru-native — built-in chain adapter for Thru L1 transaction signing and account management
• Multi-layered — choose the level of abstraction that fits your project, from pre-built React components to low-level iframe control

Architecture

The SDK is organized into a 4-layer stack. Each layer builds on the one below it, so you only need to import the highest layer your project requires.

Package	Version	Description	Key Exports
@kea-wallet/react-ui	0.2.0	Pre-built React components for common wallet interactions	KeaConnectButton, KeaAccountSwitcher, KeaLogo
@kea-wallet/react-sdk	0.2.2	React context provider and hooks for automatic state management	KeaProvider, useWallet, useAccounts, useKea
@kea-wallet/browser-sdk	0.2.3	Framework-agnostic core SDK — events, accounts, chain adapters	BrowserSDK, SDKEvent, IThruChain
@kea-wallet/embedded-provider	0.2.3	Low-level iframe/postMessage transport via IframeManager	EmbeddedProvider, IframeManager

tip

Most React apps should start with @kea-wallet/react-ui — it re-exports everything from react-sdk. Non-React apps should use @kea-wallet/browser-sdk directly. See Integration Options for a detailed comparison.

How It Works

When your app calls connect(), the SDK orchestrates a secure handshake between your dApp, the wallet iframe, and the user's passkey:

Step by step:

1. Initialization — KeaProvider (or new BrowserSDK()) creates a hidden iframe pointing to keawallet.com/embedded. The iframe sends an IFRAME_READY event once loaded.
2. Connect — Your app calls connect(). This must be triggered by a user gesture (click/tap) to avoid popup blockers.
3. Authentication — The SDK displays the wallet as a popup window. The user authenticates via passkey (WebAuthn) inside the iframe.
4. Approval — After authentication, the wallet sends the authorized account data back to the SDK via postMessage.
5. Connected — The SDK emits a connect event. Accounts are available via useWallet() or sdk.getAccounts().

tip

Call initialize() before connect() to pre-load the iframe for a faster first connection. In React, KeaProvider does this automatically.

Security

The SDK's iframe architecture provides strong security guarantees:

• Origin isolation — The wallet runs in a separate origin (keawallet.com). Your dApp never sees private keys or sensitive credentials.
• Message validation — Every postMessage is checked against the expected origin and a unique frameId generated per session, preventing cross-frame spoofing.
• Passkey auth — Users authenticate with WebAuthn passkeys. Credentials are hardware-bound and never leave the device — no passwords, no seed phrases.
• Sandboxed iframe — The wallet iframe runs with publickey-credentials-get and publickey-credentials-create permissions only.

Display Modes

The SDK supports two ways to present the wallet interface.

Modal (Default)

A simple popup window appears over your app when connect() is called. This is the default and simplest approach — no configuration needed.

React

import { KeaProvider } from '@kea-wallet/react-sdk';
import { KeaConnectButton } from '@kea-wallet/react-ui';

const config = {
  rpcUrl: 'https://grpc-web.alphanet.thruput.org',
  autoConnect: true,
};

function App() {
  return (
    <KeaProvider config={config}>
      <KeaConnectButton />
    </KeaProvider>
  );
}

Vanilla JS

import { BrowserSDK } from '@kea-wallet/browser-sdk';

const sdk = new BrowserSDK({
  rpcUrl: 'https://grpc-web.alphanet.thruput.org',
  autoConnect: true,
});

// Opens wallet popup
const result = await sdk.connect({
  metadata: { appName: 'My dApp' },
});

console.log('Connected:', sdk.getSelectedAccount()?.address);

Inline

Embed the wallet UI directly into a container in your page using mountInline(). The wallet responds to the container's size and does not create an overlay.

React

import { useRef, useEffect } from 'react';
import { useWallet } from '@kea-wallet/react-sdk';

function InlineWallet() {
  const { mountInline } = useWallet();
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (containerRef.current) {
      mountInline(containerRef.current);
    }
  }, [mountInline]);

  return <div ref={containerRef} style={{ width: '100%', height: 600 }} />;
}

Vanilla JS

const container = document.getElementById('wallet-container');
sdk.mountInline(container);

Feature	Modal	Inline
Trigger	connect()	mountInline(container)
Display	Popup window over your app	Embedded inside a DOM container
Default	Yes	No
Best for	Quick connect flows, auth popups	Dashboard-embedded wallet views

note

Once mounted inline, calling connect() shows the wallet inside the inline container instead of opening a modal.

What's Next

• Quickstart — Get a working integration in under 5 minutes
• Integration Options — Choose the right SDK package for your project
• Connect Wallet — Handle connection states, session persistence, and disconnection
• Sign Transactions — Build and sign transactions using the Thru chain adapter
• Handle Accounts — Work with multiple accounts and switch the active account
• SDK Events — Subscribe to connection, account change, and error events
• Error Handling — Handle user rejection, timeouts, and connection failures