Keythings Wallet API Reference

const provider = window.keeta;
provider.on('accountsChanged', (accounts) => console.log(accounts));
provider.on('chainChanged', (chainId) => console.log(chainId));

await provider.requestCapabilities(['sign', 'transact']);

type KeetaTransaction = {
  to: string;                // required recipient account on Keeta
  amount: string;            // required amount as a string (decimal or raw, depending on integration)
  from?: string;             // optional explicit sender; usually omitted so the active account is used
  token?: string;            // optional token account; omitted for base token transfers
  data?: string;             // optional external payload (anchors, contract calls, protocol metadata)
  gasLimit?: string;         // optional network fee hint
  nonce?: string;            // optional client nonce
  operations?: unknown[];    // reserved for advanced builder-style operations
}

const client = await provider.getUserClient();
const builder = client.initBuilder();

// Generate a STORAGE or TOKEN identifier
const storage = builder.generateIdentifier('STORAGE');

// Example: send on behalf of a storage account
builder.send(
  'keeta_recipient_address',
  '1000000',
  client.baseToken,
  undefined,
  { account: storage.account }
);

// Compute and publish
await client.publishBuilder(builder);

const provider = window.keeta;
if (!provider) throw new Error('Keythings Wallet not detected');
const accounts = await provider.requestAccounts();

const [account] = await provider.getAccounts();
const balance = await provider.getBalance(account);
const normalized = await provider.getNormalizedBalances();

const network = await provider.getNetwork();
await provider.switchNetwork('test');

// packages/wallet-core/src/index.ts
export interface WalletCoreConfig { }
export function createWalletCore(config: WalletCoreConfig = {}): WalletCoreConfig;
export * from './keeta-sdk';

import * as KeetaNet from '@keetanetwork/keetanet-client';
import type { UserClient } from '@keetanetwork/keetanet-client';

// Permission helpers
export type PermissionsAcceptedInput = Parameters<(typeof KeetaNet.lib.Permissions)['FromAcceptedTypes']>[0];
export type PermissionFlagNames = Extract<
  Parameters<(typeof KeetaNet.lib.Permissions)['BaseSet']['Create']>[0],
  string[]
>;
export type PermissionsInput =
  | InstanceType<typeof KeetaNet.lib.Permissions>
  | PermissionsAcceptedInput
  | PermissionFlagNames
  | null
  | undefined;

export function permissionsFromAcceptedTypes(value?: PermissionsInput):
  InstanceType<typeof KeetaNet.lib.Permissions> | undefined;

export function ensurePermissions(
  value?: PermissionsInput,
  fallback?: PermissionsAcceptedInput,
): InstanceType<typeof KeetaNet.lib.Permissions>;

export async function fetchAccountDefaultPermissions(
  client: UserClient,
  account: InstanceType<typeof KeetaNet.lib.Account> | string,
): Promise<InstanceType<typeof KeetaNet.lib.Permissions>>;

export function permissionFlags(permission?:
  InstanceType<typeof KeetaNet.lib.Permissions> | null
): string[];

// Seed and account helpers
export const seedBytesToString: (bytes: Uint8Array) => string;
export const hexStringToBytes: (hex: string) => Uint8Array;
export async function accountFromSeed(
  seed: string | Uint8Array | ArrayBuffer,
  index?: number,
): Promise<KeetaNet.lib.Account.AccountInstance>;
export async function seedToBytes(seed: string): Promise<Uint8Array>;
export const deriveAccountPublicKeys: (seedBytes: Uint8Array, count?: number, startIndex?: number) => string[];

// History helpers
export interface HistoryRecord extends Record<string, unknown> {
  id?: string;
  block?: string;
  to?: unknown;
  from?: unknown;
  amount?: string | bigint | number;
  token?: unknown;
  tokenAddress?: unknown;
  timestamp?: number;
  operationType?: string;
  type?: unknown;
}
export interface HistoryPageOptions { cursor?: string | null; depth?: number; }
export interface HistoryPageResult { records: HistoryRecord[]; cursor: string | null; hasMore: boolean; }
export const normaliseBalances: (payload: unknown) => HistoryRecord[];
export async function fetchHistoryPage(
  client: UserClient,
  options?: HistoryPageOptions,
): Promise<HistoryPageResult>;

// User client bootstrap
export type KeetaSdkNetwork = 'test' | 'main' | 'staging' | 'dev';
export interface UserClientBootstrapResult {
  client: UserClient;
  account: KeetaNet.lib.Account.AccountInstance;
  accountAddress: string;
  network: KeetaSdkNetwork;
}
export interface CreateUserClientOptions {
  accountIndex?: number;
  expectedAccountAddress?: string;
}
export async function createUserClientForSeed(
  network: KeetaSdkNetwork,
  seed: string | Uint8Array | ArrayBuffer,
  options?: CreateUserClientOptions,
): Promise<UserClientBootstrapResult>;

export async function destroyUserClient(client: UserClient | null | undefined): Promise<void>;
export async function recoverFromVotingConflict(client: UserClient): Promise<void>;

export async function quoteBuilderFee(
  client: UserClient,
  builder: ReturnType<UserClient['initBuilder']>,
): Promise<bigint>;

import {
  createUserClientForSeed,
  fetchHistoryPage,
  ensurePermissions,
  permissionFlags,
} from '@keetanetwork/wallet-core';

const { client, account } = await createUserClientForSeed('test', seedHex);
const history = await fetchHistoryPage(client, { depth: 50 });
const perms = ensurePermissions(['ACCESS']);
console.log(permissionFlags(perms));

// src/lib/wallet-provider.ts
export const KEYTHINGS_INPAGE_BRIDGE_TARGET = 'keythings:inpage-provider' as const;
export const KEYTHINGS_CONTENT_BRIDGE_TARGET = 'keythings:content-script' as const;

export type InpageToContentMessage =
  | {
      target: typeof KEYTHINGS_CONTENT_BRIDGE_TARGET;
      type: 'init';
      id?: number;
    }
  | {
      target: typeof KEYTHINGS_CONTENT_BRIDGE_TARGET;
      type: 'request';
      id: number;
      method: string;
      params?: unknown[];
    };

export type ContentToInpageMessage =
  | {
      target: typeof KEYTHINGS_INPAGE_BRIDGE_TARGET;
      type: 'state';
      state: KeetaProviderState;
    }
  | {
      target: typeof KEYTHINGS_INPAGE_BRIDGE_TARGET;
      type: 'response';
      id: number;
      result?: unknown;
      error?: SerializedKeetaError;
    }
  | {
      target: typeof KEYTHINGS_INPAGE_BRIDGE_TARGET;
      type: 'event';
      event: 'accountsChanged' | 'chainChanged' | 'disconnect' | 'lockChanged';
      payload?: unknown;
    };

import { z } from 'zod';

const InpageToContentMessageSchema = z.discriminatedUnion('type', [
  z.object({
    target: z.literal('keythings:content-script'),
    type: z.literal('init'),
    id: z.number().int().optional(),
  }),
  z.object({
    target: z.literal('keythings:content-script'),
    type: z.literal('request'),
    id: z.number().int(),
    method: z.string().min(1),
    params: z.array(z.unknown()).optional(),
  }),
]);

const ContentToInpageMessageSchema = z.discriminatedUnion('type', [
  z.object({
    target: z.literal('keythings:inpage-provider'),
    type: z.literal('state'),
    state: z.object({
      isConnected: z.boolean(),
      isUnlocked: z.boolean(),
      isLocked: z.boolean(),
      chainId: z.string(),
      selectedAddress: z.string().nullable(),
      network: z.enum(['test', 'main']),
    }),
  }),
  z.object({
    target: z.literal('keythings:inpage-provider'),
    type: z.literal('response'),
    id: z.number().int(),
    result: z.unknown().optional(),
    error: z
      .object({ code: z.number().int(), message: z.string(), data: z.unknown().optional() })
      .optional(),
  }),
  z.object({
    target: z.literal('keythings:inpage-provider'),
    type: z.literal('event'),
    event: z.enum(['accountsChanged', 'chainChanged', 'disconnect', 'lockChanged']),
    payload: z.unknown().optional(),
  }),
]);

// src/content-scripts/inject-provider.ts (simplified)
type BackgroundResponse = { id: number; result?: unknown; error?: SerializedKeetaError };

// Site status
sendRuntimeMessage<BackgroundResponse | undefined>({
  source: KEYTHINGS_CONTENT_BRIDGE_TARGET,
  type: 'keeta:get-site-status',
  origin: window.location.origin,
  pageUrl: window.location.href,
});

// RPC request
sendRuntimeMessage<BackgroundResponse | undefined>({
  source: KEYTHINGS_CONTENT_BRIDGE_TARGET,
  type: 'keeta:rpc-request',
  id,
  method,
  params,
  origin: window.location.origin,
  pageUrl: window.location.href,
});

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // Session messages (keeta:session:*) are handled elsewhere
  if (isRpcRequestMessage(message)) {
    await this.requireTrustedContentSender(sender, message);
    const origin = this.extractSenderOrigin(sender, message.origin);
    const pageUrl = this.extractSenderPageUrl(sender, message.pageUrl);
    this.ensureOriginIsAllowlisted(origin);
    const response = await this.handleRpcRequest(message, origin, pageUrl);
    sendResponse(safeSerialize(response, 'RPC response serialization'));
    return true;
  }
});