Quickstart

Connect your dApp to KEA Wallet and display a user's Thru address in under 5 minutes.

tip

No browser extension required — KEA Wallet runs entirely in a secure iframe and authenticates users with Passkeys (WebAuthn).

Prerequisites

• Node.js 18+
• React 18+ (for the React path)
• A package manager (npm / yarn / pnpm)

Secure Context Required

KEA Wallet uses WebAuthn Passkeys, which require a Secure Context — your app must be served over localhost or HTTPS. Plain http:// will not work.

Step 1: Install

React

npm install @kea-wallet/react-ui

tip

@kea-wallet/react-ui re-exports everything from @kea-wallet/react-sdk — one install gives you components, hooks, and the provider.

Vanilla JS

npm install @kea-wallet/browser-sdk

Step 2: Connect the Wallet

React

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

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

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

function Dashboard() {
  const { isConnected, selectedAccount } = useWallet();

  return (
    <div>
      <KeaConnectButton />
      {isConnected && <p>Address: {selectedAccount?.address}</p>}
    </div>
  );
}

export default App;

• KeaProvider initializes the SDK and provides wallet state to all child components.
• KeaConnectButton handles connect/disconnect and displays the connection state automatically.
• useWallet() gives you access to accounts, connection flags, and wallet methods.

Vanilla JS

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

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

// Pre-load the iframe for a faster first connection
await sdk.initialize();

document.getElementById('connect-btn').addEventListener('click', async () => {
  try {
    await sdk.connect({ metadata: { appName: 'My dApp' } });
    const account = sdk.getSelectedAccount();
    document.getElementById('address').textContent = account.address;
  } catch (err) {
    console.error('Connection failed:', err);
  }
});

• initialize() pre-loads the wallet iframe. This is optional — connect() calls it automatically if needed.
• connect() opens the wallet modal where the user authenticates with their Passkey.
• getSelectedAccount() returns the active WalletAccount with the user's Thru address.

Cleanup required

Call sdk.destroy() when your app unloads to tear down the iframe and remove event listeners.

Step 3: Run and Verify

Start your dev server and test the integration:

1. Click "Connect Wallet" — a secure modal opens over your app
2. Authenticate with your Passkey (TouchID / FaceID / security key)
3. The modal closes — your app displays the connected Thru address
4. Refresh the page — the session restores automatically (no modal shown)

tip

autoConnect: true stores a session hint in localStorage. On reload, the SDK silently restores the session without showing the modal. See Session Persistence for details.

What's Next

• Connect Wallet — Session persistence, reconnection states, and building a custom connect UI with the useWallet() hook
• Sign Transactions — Build and sign Thru L1 transactions using the wallet's chain adapter
• Handle Accounts — Multi-account switching with <KeaAccountSwitcher /> or hooks
• Events — Subscribe to connection, disconnect, and account change events
• Error Handling — Handle user rejection, timeouts, and iframe errors
• SDK Reference — Full API documentation for all packages