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();
}

Demo Test Pages

Use these demo pages inside the same Kasperia web project to test provider injection, external wallet request callbacks, and QR scan links. The demo pages are stored under /demo/; the separate demo home page is intentionally not included.

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: ['0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF']
}

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: '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF',
  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 = '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF';
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: '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF'
  }
});

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: '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF',
      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: '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF',
    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: '0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF'
  }
});

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 scans the plain-text content inside a QR code, classifies it by protocol, and opens the matching app page with parsed parameters. Scanning only prepares the target page; it does not automatically submit a transfer, mint, bridge action, or transaction. The user must still review and confirm inside the app.

General QR Link Format

Use a plain-text URL or address as the QR content. For routes with parameters, use standard query parameters: ? after the route and & between parameters. Always URL-encode user-generated text, especially payloads, token symbols, addresses inside query values, spaces, symbols, and non-English characters.

KAS Transfer QR

Kaspa transfer QR content opens the Send KAS page. The scanner supports a raw Kaspa address and a transfer-style URL. If amount or payload is included, the app pre-fills those values. The app checks that the scanned recipient address prefix matches the current Kaspa network before opening the send page.

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()}`;
}

Kasperia App Pages / Bridge QR

Use the kasperia:// scheme for supported internal app pages. These links are handled by the app page scanner flow.

Copykasperia://bridge?to=kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl&amount=5
kasperia://krc20_tokens
kasperia://eco_system_fund?address=kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl&amount=5&targetAmount=100

KRC20 Transfer / Mint QR

Use the krc20:// scheme for KRC20 actions. The app reads tick as the token identifier, checks the current account token data when needed, and opens the matching KRC20 page. For transfer and mint, if a recipient is provided, the Kaspa address prefix must match the current Kaspa network.

Copykrc20://transfer?tick=JEMES&to=kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl&amount=5
krc20://mint?tick=JEMES&to=kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl&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. The app looks up the network by chain id; if no configured network is found, the scanner shows an error. If token is omitted, the app opens the native-token transfer flow. If token is provided, the app 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));
  if (to) 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 http:// or https:// 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/
http://example.com/dapp
https://kasbridge-tn10evm-m.kaspafoundation.org/

Recommended dApp behavior after being opened from a QR:

Copyasync function initAfterQrOpen() {
  const wallet = await waitForKasperia();
  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 that the scanner should receive.

Copyimport QRCode from 'qrcode';

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

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

Plain JavaScript helper for building supported scan links safely:

Copyconst KAS_TEST_ADDRESS = 'kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl';

const examples = {
  kasAddressOnly: KAS_TEST_ADDRESS,
  kasTransfer: `kaspa://transfer?to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5&payload=${encodeURIComponent('hello world')}`,
  bridge: `kasperia://bridge?to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  krc20TokenList: 'kasperia://krc20_tokens',
  ecosystemFund: `kasperia://eco_system_fund?address=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5&targetAmount=100`,
  krc20Transfer: `krc20://transfer?tick=JEMES&to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  krc20Mint: `krc20://mint?tick=JEMES&to=${encodeURIComponent(KAS_TEST_ADDRESS)}&amount=5`,
  krc20Token: 'krc20://token?tick=JEMES',
  evmNativeTransfer: 'ethereum://transfer?chainId=56&to=0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF&amount=1.5',
  evmTokenTransfer: 'ethereum://transfer?chainId=56&token=0x1234567890abcdef1234567890abcdef12345678&to=0x46C7956fDbC3c81b5D5aca9E20d9ACcFF59037BF&amount=100',
  dappHttps: 'https://kas.fun/',
  dappHttp: 'http://example.com/dapp'
};

Validation Notes

1. Scanning a payment, mint, bridge, or EVM QR opens a pre-filled app page; the user must still confirm the action.
2. For Kaspa and KRC20 links, the recipient address prefix must match the current Kaspa network. Use kaspa: on mainnet and kaspatest: on testnet.
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, must be greater than zero, and must exist in the app EVM network config.
5. For EVM contract-token transfers, token must be a valid contract address on the selected chain.
6. For dApp QR links, http:// and https:// URLs are opened inside the app WebView.
7. Use encodeURIComponent or URLSearchParams when generating QR links from JavaScript.
8. Unsupported or unknown protocols should be treated as invalid QR content.

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