Class: EmbeddedProvider

Defined in: EmbeddedProvider.ts:76

Embedded wallet provider that communicates with the KEA Wallet via a hidden iframe and the postMessage protocol.

Manages the full wallet lifecycle: iframe creation, user connection/disconnection, account selection, event propagation, and chain adapter instantiation.

Example

const provider = new EmbeddedProvider({ iframeUrl: 'https://keawallet.com/embedded' });
await provider.initialize();

const { accounts } = await provider.connect();
console.log('Connected account:', accounts[0].address);

provider.on('accountChanged', (data) => {
  console.log('Account switched:', data.account.address);
});

Constructors

Constructor

new EmbeddedProvider(config: EmbeddedProviderConfig): EmbeddedProvider;

Defined in: EmbeddedProvider.ts:91

Create a new EmbeddedProvider instance.

Parameters

Parameter	Type	Description
config	EmbeddedProviderConfig	Provider configuration including iframe URL and address types

Returns

EmbeddedProvider

Lifecycle

destroy()

destroy(): void;

Defined in: EmbeddedProvider.ts:471

Tear down the provider — removes the iframe, clears all event listeners, and resets connection state.

Returns

void

---

initialize()

initialize(): Promise<void>;

Defined in: EmbeddedProvider.ts:146

Initialize the provider by creating the wallet iframe and waiting for it to signal readiness. Must be called before connect or mountInline.

Returns

Promise<void>

---

mountInline()

mountInline(container: HTMLElement): Promise<void>;

Defined in: EmbeddedProvider.ts:165

Mount the wallet iframe inline inside a DOM container instead of as a modal overlay. Once mounted inline, all subsequent connect calls render within the container.

Parameters

Parameter	Type	Description
container	HTMLElement	The DOM element to embed the wallet iframe into

Returns

Promise<void>

Example

const container = document.getElementById('wallet-container');
await provider.mountInline(container);
await provider.connect(); // renders inside container instead of modal

Connection

connect()

connect(options?: ConnectOptions): Promise<ConnectResult>;

Defined in: EmbeddedProvider.ts:192

Connect to the KEA Wallet. Shows the iframe (modal or inline) and requests user authorization.

Parameters

Parameter	Type	Description
options?	ConnectOptions	Optional connection options including dApp metadata for the consent screen

Returns

Promise<ConnectResult>

The connection result containing the authorized wallet accounts

Remarks

Concurrent calls are deduplicated — if a connection is already in flight, subsequent calls await the same promise rather than opening multiple modals.

Throws

Error if the user rejects the connection or the iframe response is invalid

Example

const result = await provider.connect({
  metadata: { appName: 'My dApp', appUrl: 'https://mydapp.com' },
});
console.log(result.accounts);

---

disconnect()

disconnect(): Promise<void>;

Defined in: EmbeddedProvider.ts:255

Disconnect from the wallet. Clears all account state and hides the iframe.

Returns

Promise<void>

Throws

Error if the disconnect message fails to send

---

isConnected()

isConnected(): boolean;

Defined in: EmbeddedProvider.ts:288

Check whether the wallet is currently connected.

Returns

boolean

true if a wallet session is active

Accounts

getAccounts()

getAccounts(): WalletAccount[];

Defined in: EmbeddedProvider.ts:338

Get all accounts from the current wallet session.

Returns

WalletAccount[]

A shallow copy of the connected accounts array

---

getSelectedAccount()

getSelectedAccount(): WalletAccount | null;

Defined in: EmbeddedProvider.ts:349

Get the currently selected (active) account.

Returns

WalletAccount | null

The selected account, or null if no account is selected

---

selectAccount()

selectAccount(publicKey: string): Promise<WalletAccount>;

Defined in: EmbeddedProvider.ts:369

Switch the active account by public key.

Parameters

Parameter	Type	Description
publicKey	string	The public key of the account to select

Returns

Promise<WalletAccount>

The newly selected account

Throws

Error if the wallet is not connected

Example

const accounts = provider.getAccounts();
const newAccount = await provider.selectAccount(accounts[1].address);
console.log('Switched to:', newAccount.address);

Chain

thru

Get Signature

get thru(): EmbeddedThruChain;

Defined in: EmbeddedProvider.ts:394

Access the Thru chain adapter for signing transactions and messages via the wallet iframe.

Throws

Error if Thru chain was not enabled in the provider config

Returns

EmbeddedThruChain

The iframe-backed Thru chain signer

Events

emit()

emit(event: string, data?: unknown): void;

Defined in: EmbeddedProvider.ts:447

Emit an event to all registered listeners.

Parameters

Parameter	Type	Description
event	string	The event name to emit
data?	unknown	Optional payload passed to each listener

Returns

void

---

off()

off(event: string, callback: (data?: unknown) => void): void;

Defined in: EmbeddedProvider.ts:435

Unsubscribe from a provider event.

Parameters

Parameter	Type	Description
event	string	The event name to unsubscribe from
callback	(data?: unknown) => void	The specific listener to remove

Returns

void

---

on()

on(event: string, callback: (data?: unknown) => void): void;

Defined in: EmbeddedProvider.ts:420

Subscribe to a provider event.

Parameters

Parameter	Type	Description
event	string	The event name (see EMBEDDED_PROVIDER_EVENTS for available events)
callback	(data?: unknown) => void	The listener function invoked when the event fires

Returns

void

Example

provider.on('accountChanged', (data) => {
  console.log('New account:', data.account.address);
});

provider.on('disconnect', () => {
  console.log('Wallet disconnected');
});