Kasperia Wallet API Documentation

Integrate Kasperia Wallet by choosing one access mode first: use the injected provider inside the Kasperia App WebView or desktop extension, or use a deep-link request with callback from an external mobile browser. This guide covers connecting accounts, checking networks, reading balances, signing messages, and sending transactions.

Integration Modes

Provider Objects

Kasperia exposes one canonical wallet object for dApps:

Copywindow.kasperia

For EVM dApps, use the EVM provider under the same namespace:

Copywindow.kasperia.ethereum

Quick Start

Most integrations should follow this order:

1. Detect the environment. If window.kasperia exists, use the injected provider. If it does not exist on mobile, open Kasperia through the external request flow.
2. Connect after a user click. Use requestAccounts() for Kaspa or eth_requestAccounts for EVM.
3. Check the current network. Read getNetwork() or eth_chainId. If the user is on the wrong network, call the switch method and wait for confirmation.
4. Read state. Read the selected account, balance, and network again after connect or switch.
5. Submit user actions. Sign messages or send transactions only after the user confirms the action in your UI.

Copy-paste EVM integration

Copyconst KASPLEX_L2_TESTNET = '0x28c64'; // 167012
const KASPLEX_L2_MAINNET = '0x3173b'; // 202555
const BSC_TESTNET = '0x61'; // 97
const BSC_MAINNET = '0x38'; // 56

function getKasperiaWallet() {
  return window.kasperia && window.kasperia.isKasperia ? window.kasperia : null;
}

function getKasperiaEvmProvider() {
  const wallet = getKasperiaWallet();
  return wallet && wallet.ethereum ? wallet.ethereum : null;
}

async function waitForKasperia(timeout = 3000) {
  const wallet = getKasperiaWallet();
  if (wallet) return wallet;

  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error('Kasperia provider not found')), timeout);

    window.addEventListener('kasperia#initialized', () => {
      clearTimeout(timer);
      const injected = getKasperiaWallet();
      injected ? resolve(injected) : reject(new Error('Kasperia provider not found'));
    }, { once: true });
  });
}

async function connectEvm() {
  await waitForKasperia();
  const provider = getKasperiaEvmProvider();
  if (!provider) throw new Error('Kasperia EVM provider is not available');

  const accounts = await provider.request({ method: 'eth_requestAccounts' });
  return { provider, address: accounts[0] };
}

async function ensureEvmChain(provider, targetChainId) {
  const currentChainId = await provider.request({ method: 'eth_chainId' });
  if (currentChainId.toLowerCase() === targetChainId.toLowerCase()) return;

  await provider.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: targetChainId }]
  });
}

async function connectAndPrepareEvm() {
  const { provider, address } = await connectEvm();
  await ensureEvmChain(provider, KASPLEX_L2_TESTNET);

  const balance = await provider.request({
    method: 'eth_getBalance',
    params: [address, 'latest']
  });

  return { provider, address, balance };
}

Copy-paste Kaspa native integration

Copyasync function connectKaspa() {
  const wallet = await waitForKasperia();

  const accounts = await wallet.requestAccounts();
  const address = accounts[0];

  const network = await wallet.getNetwork();
  const balance = await wallet.getBalance();

  return { wallet, address, network, balance };
}

async function switchKaspaToTestnet10() {
  const wallet = await waitForKasperia();
  await wallet.switchNetwork('testnet-10');
  return await wallet.getNetwork();
}

Mobile Overview

The Kasperia mobile app supports two mobile access paths:

1. In-App Browser: the dApp page runs inside Kasperia WebView. The wallet provider is injected automatically.
2. External Browser: the dApp runs outside Kasperia. Use a deep link or universal link request to open Kasperia and get a callback response.

In-App Browser

Use this mode when your dApp is opened inside the Kasperia mobile app. The app injects window.kasperia at document start. Your page should wait for the provider, then use the same APIs as the browser extension integration.

Copyasync function initInKasperiaApp() {
  const wallet = await waitForKasperia();

  // Kaspa native provider
  const kaspaAccounts = await wallet.requestAccounts();

  // EVM provider
  const evmProvider = wallet.ethereum;
  const evmAccounts = evmProvider
    ? await evmProvider.request({ method: 'eth_requestAccounts' })
    : [];

  return { wallet, kaspaAccounts, evmProvider, evmAccounts };
}

After connection, always re-read the network before showing balances or enabling transaction buttons.

External Browser

Use this mode when the user opens your dApp in Safari, Chrome, Telegram, X, or another external mobile app. In this environment, the page cannot assume that window.kasperia is injected. Instead, create a wallet request, open Kasperia, and receive the result through your callback URL.

Supported request URLs:

Copykasperia://wallet/request?payload=<base64url-json>
https://link.kasperia.app/wallet/request?payload=<base64url-json>

External Request Payload

The payload is a JSON object encoded as base64url without padding. Each request should have a unique id. Your callback handler must decode walletResponse and verify that the response id matches the request id.

Copyconst payload = {
  id: crypto.randomUUID(),
  origin: window.location.origin,
  method: 'eth_requestAccounts',
  params: {},
  callback: `${window.location.origin}/wallet-callback`
};

Encode and open the request:

Copyfunction base64UrlEncodeJson(json) {
  const raw = JSON.stringify(json);
  const bytes = new TextEncoder().encode(raw);
  let binary = '';
  bytes.forEach((b) => binary += String.fromCharCode(b));

  return btoa(binary)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/g, '');
}

function openKasperiaWalletRequest(payload) {
  const encoded = base64UrlEncodeJson(payload);
  window.location.href = `kasperia://wallet/request?payload=${encoded}`;
}

Kasperia returns the result by appending walletResponse to your callback URL:

Copyhttps://your-dapp.com/wallet-callback?walletResponse=<base64url-json>

Decoded success response:

Copy{
  id: 'request-id',
  success: true,
  data: ['0x1234...']
}

Decoded error response:

Copy{
  id: 'request-id',
  success: false,
  error: {
    code: 4001,
    message: 'User rejected the request'
  }
}

Mobile Support Matrix

Connect Wallet

Copyasync function connectKaspaWallet() {
  const accounts = await window.kasperia.requestAccounts();
  const address = accounts[0];
  console.log('Kaspa address:', address);
  return address;
}

Returns

Copy['kaspa:...']
// or
['kaspatest:...']

Accounts

After the site is connected, use getAccounts to read the current Kaspa address without opening the connect prompt again.

Copyconst accounts = await window.kasperia.getAccounts();
const current = await window.kasperia.request({ method: 'kasperia_currentAccount' });
const publicKey = await window.kasperia.getPublicKey();

Current account response

Copy{
  id: 'account-id',
  name: 'Account 1',
  kaspaAddress: 'kaspa:...',
  evmAddress: '0x...',
  publicKey: '...',
  isCurrent: true
}

Network

Use getNetwork for the current Kaspa network and getNetworks for all available Kaspa and EVM networks.

Copyconst currentKaspaNetwork = await window.kasperia.getNetwork();
const allNetworks = await window.kasperia.getNetworks();

Switch Kaspa network:

Copyawait window.kasperia.switchNetwork('mainnet');
await window.kasperia.switchNetwork('testnet-10');

You can also use the generic request form:

Copyawait window.kasperia.request({
  method: 'kasperia_switchNetwork',
  params: { type: 'kaspa', network: 'testnet-10' }
});

Balance

Read the current Kaspa account balance. The raw unit is sompi and decimals is 8.

Copyconst balance = await window.kasperia.getBalance();
console.log(balance.raw, balance.symbol, balance.decimals);

Response

Copy{
  type: 'kaspa',
  network: 'mainnet',
  address: 'kaspa:...',
  symbol: 'KAS',
  decimals: 8,
  total: '100000000',
  available: '100000000',
  pending: '0',
  raw: '100000000'
}

Send KAS

Use sendKaspa to send KAS. The amount must be passed in sompi.

Copyasync function sendKas() {
  const to = 'kaspa:qp...';
  const sompi = '100000000'; // 1 KAS
const txid = await window.kasperia.sendKaspa(to, sompi, {
    payload: ''
  });

  console.log('Kaspa txid:', txid);
}

Generic request form:

Copyconst result = await window.kasperia.request({
  method: 'kasperia_sendKaspa',
  params: {
    to: 'kaspa:qp...',
    sompi: '100000000',
    payload: ''
  }
});

Generic Request

window.kasperia.request is the shared low-level request method. It is useful for methods without a convenience wrapper.

Copyconst version = await window.kasperia.getVersion();

const result = await window.kasperia.request({
  method: 'kasperia_getNetworks',
  params: {}
});

Kaspa Events

Copywindow.kasperia.on('networkChanged', (network) => {
  console.log('Kaspa network changed:', network);
});

window.kasperia.on('accountsChanged', (accounts) => {
  console.log('Kaspa accounts changed:', accounts);
});

Get EVM Provider

Use window.kasperia.ethereum as the recommended EVM provider.

Copyfunction getEvmProvider() {
  if (window.kasperia && window.kasperia.ethereum) {
    return window.kasperia.ethereum;
  }
  return null;
}

The provider supports request, send, sendAsync, enable, events, selectedAddress, chainId, and networkVersion.

Connect EVM Account

Copyasync function connectEvmWallet() {
  const provider = window.kasperia.ethereum;
  const accounts = await provider.request({ method: 'eth_requestAccounts' });
  return accounts[0];
}

Read connected EVM accounts without prompting:

Copyconst accounts = await window.kasperia.ethereum.request({
  method: 'eth_accounts'
});

Get / Switch Chain

Read the current EVM chain id. The result is a hex string.

Copyconst chainId = await window.kasperia.ethereum.request({
  method: 'eth_chainId'
});

console.log(chainId); // example: '0x28c64' = 167012

Switch EVM chain. Kasperia will show a Switch Network confirmation sheet in the app.

Copyawait window.kasperia.ethereum.request({
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: '0x28c64' }]
});

wallet_addEthereumChain is treated as a switch request to an already configured chain. The current app implementation does not add arbitrary new RPC networks from dApp params.

Get EVM Balance

Use eth_getBalance to read the native EVM balance. The result is a hex quantity.

Copyconst address = '0x...';
const balanceHex = await window.kasperia.ethereum.request({
  method: 'eth_getBalance',
  params: [address, 'latest']
});

You can also use the Kasperia generic request form:

Copyconst balance = await window.kasperia.request({
  method: 'kasperia_getBalance',
  params: {
    type: 'evm',
    address: '0x...'
  }
});

Send EVM Transaction

Use eth_sendTransaction for EVM transfers or contract calls. The app will show a transaction confirmation sheet before submitting the transaction.

Copyasync function sendEvmTransaction() {
  const provider = window.kasperia.ethereum;
  const [from] = await provider.request({ method: 'eth_requestAccounts' });

  const txHash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      from,
      to: '0x0000000000000000000000000000000000000000',
      value: '0x0',
      data: '0x'
    }]
  });

  console.log('EVM tx hash:', txHash);
}

For native transfers without custom gas or data, you may use the generic request form:

Copyconst result = await window.kasperia.request({
  method: 'kasperia_sendTransaction',
  params: {
    type: 'evm',
    to: '0x...',
    amount: '0.01'
  }
});

Sign Message

The current mobile implementation supports personal_sign.

Copyconst provider = window.kasperia.ethereum;
const [address] = await provider.request({ method: 'eth_requestAccounts' });

const signature = await provider.request({
  method: 'personal_sign',
  params: ['Hello Kasperia', address]
});

Generic request form:

Copyconst signed = await window.kasperia.request({
  method: 'kasperia_signMessage',
  params: {
    message: 'Hello Kasperia',
    address: '0x...'
  }
});

Read-only RPC

The mobile app proxies common read-only EVM RPC calls through the current selected EVM network RPC URL.

Copyconst blockNumber = await window.kasperia.ethereum.request({
  method: 'eth_blockNumber'
});

EVM Events

Copyconst provider = window.kasperia.ethereum;

provider.on('accountsChanged', (accounts) => {
  console.log('EVM accounts changed:', accounts);
});

provider.on('chainChanged', (chainId) => {
  console.log('EVM chain changed:', chainId);
});

provider.on('connect', ({ chainId }) => {
  console.log('Connected:', chainId);
});

provider.on('disconnect', (error) => {
  console.log('Disconnected:', error);
});

QR Scan Link Overview

Kasperia can scan a QR code, parse its text content, and open the matching app page with pre-filled parameters. QR scan links are intended to guide the user to the correct screen; they do not silently send funds. The user still reviews and confirms the action inside the app.

General QR Link Format

Use URL query parameters for optional values. Always URL-encode user-generated text, especially payloads, spaces, symbols, and non-English characters.

KAS Transfer QR

A Kaspa QR can contain only a recipient address, or it can include amount and payload. Scanning the QR opens the Send KAS page with the parsed values pre-filled.

Alternative query-style format:

Copykaspa://transfer?to=kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey&amount=5&payload=haha

Generate a KAS transfer QR string:

Copyfunction buildKasTransferQr({ to, amount, payload }) {
  const params = new URLSearchParams();
  params.set('to', to);
  if (amount !== undefined && amount !== '') params.set('amount', String(amount));
  if (payload) params.set('payload', payload);
  return `kaspa://transfer?${params.toString()}`;
}

const qrText = buildKasTransferQr({
  to: 'kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey',
  amount: 5,
  payload: 'haha'
});

Kasperia App Pages

Use the kasperia:// scheme to open supported Kasperia app pages. This is useful for QR codes printed on websites, campaigns, bridge pages, or offline materials.

Copykasperia://bridge?to=kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey&amount=5

KRC20 Transfer / Mint QR

Use the krc20:// scheme for KRC20 token actions. The app checks the current Kaspa network, looks up the current account token data, and opens the matching KRC20 page.

Examples:

Copykrc20://transfer?tick=JEMES&to=kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey&amount=5
krc20://mint?tick=JEMES&to=kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey&amount=5
krc20://token?tick=JEMES

Copyfunction buildKrc20TransferQr({ tick, to, amount }) {
  const params = new URLSearchParams();
  params.set('tick', tick);
  if (to) params.set('to', to);
  if (amount !== undefined && amount !== '') params.set('amount', String(amount));
  return `krc20://transfer?${params.toString()}`;
}

EVM Transfer QR

Use the ethereum://transfer scheme to open the EVM Send page. chainId is required. If token is omitted, Kasperia opens the native-token transfer flow for that chain. If token is provided, Kasperia treats it as a contract token address and opens the token transfer flow.

Copyfunction buildEvmTransferQr({ chainId, to, amount, token }) {
  const params = new URLSearchParams();
  params.set('chainId', String(chainId));
  params.set('to', to);
  if (amount !== undefined && amount !== '') params.set('amount', String(amount));
  if (token) params.set('token', token);
  return `ethereum://transfer?${params.toString()}`;
}

Open dApp URL QR

If the scanned QR content is a normal web URL, Kasperia opens it inside the app WebView. The dApp can then use window.kasperia and window.kasperia.ethereum after provider injection.

Copyhttps://kas.fun/
https://kasbridge-tn10evm-m.kaspafoundation.org/

Recommended dApp behavior after being opened from a QR:

Copyasync function initAfterQrOpen() {
  const wallet = await ensureKasperiaReady();
  const accounts = await wallet.requestAccounts();
  const network = await wallet.getNetwork();
  return { accounts, network };
}

QR Builder Examples

Developers can generate QR codes with any QR library as long as the encoded content is the exact plain-text link.

Copyimport QRCode from 'qrcode';

const qrText = 'krc20://transfer?tick=JEMES&to=kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey&amount=5';
const dataUrl = await QRCode.toDataURL(qrText);

document.querySelector('#qr').src = dataUrl;

Plain JavaScript helper for building links safely:

Copyconst KAS_TEST_ADDRESS = 'kaspatest:qr24daqennp22ang7flqyzn47wrhn90vgvgnem92tk78ga3teewcgyngg85ey';

const examples = {
  kasWithoutAmount: KAS_TEST_ADDRESS,
  kasWithAmount: `${KAS_TEST_ADDRESS}&amount=5`,
  kasWithPayload: `${KAS_TEST_ADDRESS}&amount=5&payload=${encodeURIComponent('haha afasdfsdafasdf')}`,
  bridge: `kasperia://bridge?to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  krc20Transfer: `krc20://transfer?tick=JEMES&to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  krc20Mint: `krc20://mint?tick=JEMES&to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  evmTransfer: 'ethereum://transfer?chainId=56&to=0xEe461548B7CA5b4A1C9E4c078054BD047b8786c1&amount=1.5',
  dapp: 'https://kas.fun/'
};

Validation Notes

1. Scanning a payment QR opens a pre-filled app page; the user must still confirm the transfer or mint operation.
2. For Kaspa and KRC20 links, the recipient address prefix must match the current Kaspa network. A kaspatest: address should be used on testnet, and a kaspa: address should be used on mainnet.
3. For KRC20 actions, tick is required. If the token cannot be found for the current account, the app shows an error.
4. For EVM transfer links, chainId is required and must exist in the app network config.
5. Use encodeURIComponent or URLSearchParams for payloads and addresses when generating QR links from JavaScript.
6. Avoid putting private keys, seed phrases, passwords, or long sensitive data inside QR codes.
7. Unsupported or unknown protocols should be treated as invalid QR content by the dApp or campaign page.

Network Reference

Use window.kasperia.getNetworks() to get the exact networks configured in the current app build. A network item may include the following fields:

Copy{
  type: 'evm',
  id: '167012',
  name: 'Kasplex L2 Testnet',
  isCurrent: true,
  chainId: 167012,
  rpcUrl: 'https://...',
  explorerUrl: 'https://...',
  symbol: 'KAS',
  decimals: 18
}

Error Codes

Copytry {
  await window.kasperia.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x28c64' }]
  });
} catch (error) {
  if (error.code === 4001) {
    console.log('User rejected the request');
  } else {
    console.error(error.code, error.message, error.data);
  }
}

Best Practices

1. Use window.kasperia as the single canonical namespace in your dApp.
2. Use window.kasperia.ethereum for EVM requests instead of mixing multiple provider names.
3. Always call connect, switch network, signing, and transaction APIs from a user click or similar direct action.
4. Disable your button while a wallet request is pending to avoid duplicate confirmation sheets.
5. After switching EVM chains, re-read eth_chainId and update your UI from the chainChanged event.
6. Pass EVM transaction value, gas, gasPrice, and nonce as hex quantities.
7. Pass Kaspa transfer amounts in sompi, not decimal KAS.
8. For external callback flows, generate a unique id for every request and verify the response id.

Unsupported Methods