KasperiaKASPERIA

Kaspa Wallet Integration (Kasperia)

This guide helps you integrate the Kasperia browser extension wallet with your web application. It follows popular wallet‑injection patterns and adopts the EIP‑6963 provider discovery standard for a smooth multi‑wallet experience. The examples are TypeScript‑friendly.

Kasperia Wallet

Kasperia Wallet is a non-custodial wallet. We never have access to your funds. Kasperia Wallet never stores your seed phrase, your password or any private information. Your accounts are derived from your Secret Recovery Phrase.

  1. Kasperia Wallet is a hierarchical deterministic wallet. Your accounts are derived from your Secret Recovery Phrase.
  2. Your private keys are encrypted on your device by your password and are never shared with anyone.
  3. Kasperia Wallet doesn't track any personal identifiable information, your account addresses, or asset balances.
  4. Use RPC/SDK to query balances and submit transactions.

Quick Start

Go to the chrome extension webstore and install Kasperia wallet extension.

Kaspa integration

Welcome to Kasperia's integration documentation. This documentation is for learning to integrate Kasperia wallet with your applications. Please note : The integration API may be modified if relevant standards are officially released by kaspa core team one day in the future.

Getting Started

First of all, install Kasperia Wallet on your development machine. Once Kasperia Wallet is installed and running, you should find that new browser tabs have a window.kasperia object available in the developer console. This is how your website will interact with Kasperia Wallet.

Browser Detection

To verify if the browser is running Kasperia Wallet, copy and paste the code snippet below in the developer console of your web browser:

if (typeof window.kasperia !== 'undefined') {
  console.log('kasperia Wallet is installed!');
}

You can review the full API for the window.kasperia object here.

Connecting to kasperia Wallet

"Connecting" or "logging in" to kasperia Wallet effectively means "to access the user's Kaspa account(s)".

You should only initiate a connection request in response to direct user action, such as clicking a button. You should always disable the "connect" button while the connection request is pending. You should never initiate a connection request on page load.

We recommend that you provide a button to allow the user to connect kasperia Wallet to your dapp. Clicking this button should call the following method:

kasperia.requestAccounts();

Methods

requestAccounts

kasperia.requestAccounts();

Connect the current account.

Parameters

none

Returns

Promise returns string[] : Address of current account.

try {
  let accounts = await kasperia.requestAccounts();
  console.log('connect success', accounts);
} catch (e) {
  console.log('connect failed');
}
> connect success ['kaspatest:qq9h47etjv6x8jgcla0ecnp8mgrkfxm70ch3k60es5a50ypsf4h6sak3g0lru']

getAccounts

kasperia.getAccounts();

Get address of current account. It's also used to certify if the user is connected, which should be called first.

Parameters

none

Returns

  • Promise - string: address of current account
try {
  let res = await window.kasperia.getAccounts();
  console.log(res)
} catch (e) {
  console.log(e);
}
> ["kaspatest:qq9h47etjv6x8jgcla0ecnp8mgrkfxm70ch3k60es5a50ypsf4h6sak3g0lru"]

getVersion

kasperia.getVersion();

get wallet version

Parameters

none

Returns

  • Promise - string: wallet version

Example

try {
  const res = await kasperia.getVersion();
  console.log(res)
} catch (e) {
  console.log(e);
}
> "1.10.52"

getNetwork

kasperia.getNetwork();

get network

Parameters

none

Returns

  • Promise - string: the network. livenet and testnet

Example

try {
  let res = await kasperia.getNetwork();
  console.log(res)
} catch (e) {
  console.log(e);
}
​
> 'mainnet'

switchNetwork

kasperia.switchNetwork(network);

switch network It's disable in the mobile app.

Parameters

  • network - string: the network. mainnet/testnet

Returns

none

Example

try {
  let res = await kasperia.switchNetwork("mainnet");
  console.log(res)
} catch (e) {
  console.log(e);
}
​

disconnect

kasperia.disconnect(origin);

disconnect kasperia wallet

Parameters

  • origin - string: website origin url

Returns

none

Example

try {
  let origin = window.location.origin;
  await kasperia.disconnect(origin);
} catch (e) {
  console.log(e);
}
​

getPublicKey

kasperia.getPublicKey();

Get publicKey of current account.

Parameters

none

Returns

  • Promise - string: publicKey

Example

try {
  let res = await kasperia.getPublicKey();
  console.log(res)
} catch (e) {
  console.log(e);
}
> 03cbaedc26f03fd3ba02fc936f338e980c9e2172c5e23128877ed46827e935296f

getBalance

kasperia.getBalance();

Get KAS balance

Parameters

none

Returns

  • Promise - Object:
  • total - number : the total sompi

Example

try {
  let res = await kasperia.getBalance();
  console.log(res)
} catch (e) {
  console.log(e);
}
​
> {
    "total":100000
  }

sendKaspa

kasperia.sendKaspa(toAddress, sompi, options);

Send KAS

Parameters

  • toAddress - string: the address to send
  • sompi - number: the sompi to send
  • options - object: (optional)
  • payload - string: payload for transactions

Returns

  • Promise - string: txid

Example

try {
  let txid = await kasperia.sendKaspa(
    "kaspatest:qq9h47etjv6x8jgcla0ecnp8mgrkfxm70ch3k60es5a50ypsf4h6sak3g0lru",
    1000
  );
  console.log(txid);
} catch (e) {
  console.log(e);
}

submitCommitReveal

kasperia.submitCommitReveal(commitParams, revealParams);

Submit commit & reveal transactions for inscription (e.g. KNS / KRC).

Parameters

commitParams – object

Commit transaction parameters.

  • priorityFee - string
  • outputs - array

Output list for commit transaction.

  • address - string: Receiver address (testnet / mainnet).
  • amount - string: Amount in sompi.

revealParams – object

Reveal (inscription) parameters.

  • Promise – object
  • protocol - string: Protocol name, e.g. "kns" | "krc20" | "kspr_krc721"
  • action - object: Inscription action payload, depends on protocol.

Returns

  • Promise – object
  • commitTxid - string: Commit transaction hash.
  • revealTxid - string: Reveal transaction hash.

Example

try {
  const result = await kasperia.submitCommitReveal(
    {
      priorityFee: "1000000000",
      outputs: [
        {
          address: "kaspatest:qq9h47etjv6x8jgcla0ecnp8mgrkfxm70ch3k60es5a50ypsf4h6sak3g0lru",
          amount: "3500000000",
        },
      ],
    },
    {
      protocol: "kns",
      action: {
        op: "create",
        p: "domain",
        v: "jemes22",
      },
    }
  );

  console.log("commit & reveal txid", result);
} catch (e) {
  console.log(e);
}

Response Example

{
  commitTxid: "d4aa375cbf00ef14b1a6eb3f15a2ade2dfcc22b259495ade8d92688c9a9c6f81",
  revealTxid: "71ba18fc3e14088c843760ab4a7876bf0997608c0682fb8e1632481b35c99724"
}

accountsChanged

kasperia.on('accountsChanged', handler: (accounts: Array) => void);
kasperia.removeListener('accountsChanged', handler: (accounts: Array) => void);

The accountsChanged will be emitted whenever the user's exposed account address changes.

networkChanged

kasperia.on('networkChanged', handler: (network: string) => void);
kasperia.removeListener('networkChanged', handler: (network: string) => void);

The networkChanged will be emitted whenever the user's network changes.

EVM integration

In order to provide support for Kaspa-based layer2 networks, the kasperia wallet has integrated support for EVM networks. When utilizing the kasperia wallet, users can directly submit layer2 transactions to Kaspa. Consequently, this offers protection against MEV attacks, which is a distinct advantage compared to other wallets.

EVM web apps can interact with Kasperia wallet via the provider that is injected at window.Kasperia.ethereum. This provider conforms to the EIP-1193 standard and is also injected at window.ethereum to support legacy integrations.

To detect if a user has already installed Kasperia wallet, a web application should check for the existence of a Kasperia object. If a Kasperia object exists, EVM dApps can interact with Kasperia wallet via the API found at window.kasperia.ethereum. This ethereum provider is also made available at window.ethereum but is prone to namespace collisions from other injected wallets.

Get Provider

function getProvider() {
  const providerList = []
  const handler = (event) => {
    if(!providerList.some(i => i.rdns === event.detail.info.rdns)) {
      providerList.push({ ...event.detail.info, provider: event.detail.provider })
    }
  }
  window.addEventListener("eip6963:announceProvider", handler);
  window.dispatchEvent(new Event("eip6963:requestProvider"));
  const kasperiaProvider = providerList.find(i => i.rdns === "io.kasperia.wallet")
  window.removeEventListener("eip6963:announceProvider", handler);
  return kasperiaProvider || null
}
const kasperia = await getProvider()

Eth_requestAccounts

const accounts = await kasperia.provider.request({ method: "eth_requestAccounts" })

Connect the current account.

Parameters

none

Returns

Promise returns string[] : Address of current account.

Example

try {
  let accounts = await await kasperia.provider.request({ method: "eth_requestAccounts" })
  console.log('connect success', accounts);
} catch (e) {
  console.log('connect failed');
}
> connect success ['0xAd0a0406fF27e4De7B7577e8e1877A8780f3E138']

eth_accounts

const accounts = await kasperia.provider.request({ method: "eth_accounts" })

Get address of current account. It's also used to certify if the user is connected, which should be called first.

Parameters

none

Returns

Promise - string: address of current account

Example

try {
  let accounts = await kasperia.provider.request({ method: "eth_accounts" })
  console.log('connect success', accounts);
} catch (e) {
  console.log('connect failed');
}
> connect success ['0xAd0a0406fF27e4De7B7577e8e1877A8780f3E138']

eth_getBalance

const balance = await kasperia.provider.request({ method: "eth_getBalance" })

Get balance of current account. It's also used to certify if the user is connected, which should be called first.

Parameters

params: [address, "latest"]

Returns

Promise - string: the hexadecimal amount passed into the account

Example

try {
  let balance = await kasperia.provider.request({ 
    method: "eth_getBalance", 
    params: [address, "latest"] })
  console.log('balance info', balance);
} catch (e) {
  console.log('balance failed');
}
> balance info 0x0

eth_chainId

const chainId = await kasperia.provider.request({ method: "eth_chainId" })

get network

Parameters

none

Returns

Promise - string: the chainId in hexadecimal

Example

try {
  let chainId = await kasperia.provider.request({   method: "eth_chainId" })
  console.log('chainId info', chainId);
} catch (e) {
  console.log('chainId failed');
}
> chainId info 0xcc

wallet_switchEthereumChain

const chainId = await kasperia.provider.request({ 
  method: "wallet_switchEthereumChain", 
  params: [{ chainId: "0x28c64" }] 
})

Parameters

params: [{ chainId: "0x28c64" }]

Returns

none

Example

try {
  await kasperia.provider.request({ 
    method: "wallet_switchEthereumChain", 
    params: [{ chainId: "0x28c64" }] 
  })
  console.log('chainId switch successful');
} catch (e) {
  console.log('chainId failed');
}

sendTransaction

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

The sendTransaction method constructs and sends an Ethereum transaction through the connected wallet provider. It internally encodes the contract call lockForBridge(payloadHex) and sends it to the specified smart contract address.

Parameters

  • from - string: The source address (currently connected wallet address).
  • to - string: Target contract address .
  • value - string: Transaction value in hexadecimal.
  • data - string: ABI-encoded contract function call (lockForBridge payload).

Returns

  • hash - string: Transaction hash returned from the provider.

Example

import Web3 from "web3";
const web3 = new Web3(kasperia.provider)
const toAddress = "kaspatest:qp48ut63r78w5umx6tpk4vu6s4ftv79x2uf56arar3acqs368mxd65sfdeqjl"
const contractAbi = [...]
const contractAddress = "0x1234567890123456789012345678901234567890"
const contract =new web3.eth.Contract(contractAbi,contractAddress)
const payloadHex =web3.utils.toHex(toAddress)
const data = contract.methods.lockForBridge(payloadHex).encodeABI();
try {
const hash = await kasperia.provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
    to: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
    value: '0x0',
    data
  }]
})
  console.log("Transaction Hash:", hash);
} catch (error) {
  console.log("Transaction failed:", error);
}

Events

accountsChanged

kasperia.provider.on('accountsChanged', onAccountsChangedHandler);
kasperia.provider.removeListener('accountsChanged', onAccountsChangedHandler);

The accountsChanged will be emitted whenever the user's exposed account address changes.

Example


kasperia.provider.on('accountsChanged', (accounts) => {
  const accounts = Array.isArray(accountsRaw) ? accountsRaw : [];
  const address = accounts[0] ?? '';
  console.log('address', address)
})