API Reference

Complete API reference for integrating eckoWALLET into your decentralized application. This document covers all available methods, events, and data structures.

Table of Contents

• Detecting eckoWALLET

• Connection Management

• Account Information

• Network Information

• Transaction Signing

• Token Transfers

• Events

• Error Handling

• TypeScript Types

Detecting eckoWALLET

Before interacting with eckoWALLET, verify it's installed.

Check Installation

const isEckoWalletInstalled = () => {
  const { kadena } = window;
  return Boolean(kadena && kadena.isKadena);
};

// Initialize your dApp
const initialize = async () => {
  if (isEckoWalletInstalled()) {
    console.log('eckoWALLET is installed!');
    // Proceed with wallet integration
  } else {
    console.log('eckoWALLET not found');
    // Show installation prompt
  }
};

// Wait for page to load
window.addEventListener('load', initialize);

Detection Best Practices

// Check with timeout to handle delayed injection
const waitForKadena = (timeout = 3000) => {
  return new Promise((resolve) => {
    if (window.kadena?.isKadena) {
      resolve(true);
      return;
    }

    let timeElapsed = 0;
    const interval = setInterval(() => {
      timeElapsed += 100;
      if (window.kadena?.isKadena) {
        clearInterval(interval);
        resolve(true);
      } else if (timeElapsed >= timeout) {
        clearInterval(interval);
        resolve(false);
      }
    }, 100);
  });
};

// Usage
const init = async () => {
  const isInstalled = await waitForKadena();
  if (isInstalled) {
    // Proceed
  } else {
    // Show install prompt
  }
};

Connection Management

kda_connect

Requests user permission to connect to your dApp.

Method: kda_connect

Parameters:

{
  method: 'kda_connect',
  networkId: string  // 'mainnet01', 'testnet04', or 'development'
}

Request Example:

const connect = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_connect',
      networkId: 'mainnet01'
    });

    console.log('Connected:', result);
    // Result contains account information
  } catch (error) {
    console.error('Connection failed:', error);
  }
};

Response (Success):

{
  status: 'success',
  message: 'Connected successfully',
  account: {
    account: 'k:5a2afbc...',       // Account name
    publicKey: '5a2afbc...',       // Public key
    chainId: '1'                    // Current chain
  }
}

Response (Rejected):

{
  status: 'fail',
  message: 'User rejected connection'
}

kda_disconnect

Disconnects your dApp from eckoWALLET.

Method: kda_disconnect

Parameters:

{
  method: 'kda_disconnect',
  networkId: string,
  domain: string  // Your dApp domain
}

Request Example:

const disconnect = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_disconnect',
      networkId: 'mainnet01',
      domain: window.location.hostname
    });

    console.log('Disconnected:', result);
  } catch (error) {
    console.error('Disconnect failed:', error);
  }
};

Response:

{
  status: 'success',
  message: 'Disconnected successfully'
}

kda_checkStatus

Checks if your dApp is currently connected.

Method: kda_checkStatus

Parameters:

{
  method: 'kda_checkStatus',
  networkId: string
}

Request Example:

const checkStatus = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_checkStatus',
      networkId: 'mainnet01'
    });

    if (result.status === 'success') {
      console.log('Connected account:', result.account);
    } else {
      console.log('Not connected');
    }
  } catch (error) {
    console.error('Status check failed:', error);
  }
};

Response (Connected):

{
  result: {
    status: 'success',
    message: 'Connected successfully',
    account: {
      account: 'k:5a2afbc...',
      publicKey: '5a2afbc...',
      chainId: '1',
      connectedSites: ['dapp.example.com']
    }
  },
  target: 'kda.dapps',
  action: 'res_checkStatus'
}

Response (Not Connected):

{
  result: {
    status: 'fail',
    message: 'Not connected'
  },
  target: 'kda.dapps',
  action: 'res_checkStatus'
}

kda_checkIsConnected

Quick check for connection status without full details.

Method: kda_checkIsConnected

Parameters:

{
  method: 'kda_checkIsConnected',
  networkId: string
}

Response:

{
  status: 'success',
  isLocked: false,  // Wallet lock status
  message: 'Connected'
}

Account Information

kda_requestAccount

Get comprehensive account information for the connected account.

Method: kda_requestAccount

Parameters:

{
  method: 'kda_requestAccount',
  networkId: string
}

Request Example:

const getAccount = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_requestAccount',
      networkId: 'mainnet01'
    });

    console.log('Account details:', result.wallet);
  } catch (error) {
    console.error('Failed to get account:', error);
  }
};

Response:

{
  status: 'success',
  message: 'Get account information successfully',
  wallet: {
    account: 'k:5a2afbc...',
    publicKey: '5a2afbc...',
    connectedSites: ['dapp.example.com'],
    balance: 10.431761673543  // Current balance on active chain
  }
}

kda_getSelectedAccount

Get only the currently selected account address and public key.

Method: kda_getSelectedAccount

Parameters:

{
  method: 'kda_getSelectedAccount'
}

Request Example:

const getSelected = async () => {
  const result = await window.kadena.request({
    method: 'kda_getSelectedAccount'
  });

  console.log('Current account:', result);
};

Response:

{
  account: 'k:5a2afbc...',
  publicKey: '5a2afbc...'
}

Network Information

kda_getNetwork

Get information about the currently selected network.

Method: kda_getNetwork

Parameters:

{
  method: 'kda_getNetwork'
}

Request Example:

const getNetwork = async () => {
  const network = await window.kadena.request({
    method: 'kda_getNetwork'
  });

  console.log('Current network:', network);
};

Response:

{
  name: 'Mainnet',
  url: 'https://api.chainweb.com',
  networkId: 'mainnet01',
  explorer: 'https://explorer.chainweb.com/mainnet',
  id: '0',
  isDefault: true
}

kda_getChain

Get the currently selected chain ID.

Method: kda_getChain

Parameters:

{
  method: 'kda_getChain'
}

Request Example:

const getChain = async () => {
  const chainId = await window.kadena.request({
    method: 'kda_getChain'
  });

  console.log('Current chain:', chainId);  // '1'
};

Response:

'1'  // Chain ID as string

Transaction Signing

kda_requestSign

Sign a single Pact transaction.

Method: kda_requestSign

Parameters:

{
  method: 'kda_requestSign',
  data: {
    networkId: string,
    signingCmd: {
      code: string,              // Pact code to execute
      data?: object,             // Environment data
      caps: Array<Capability>,   // Capabilities
      sender: string,            // Gas payer account
      chainId: string,           // Target chain
      gasPrice: number,          // Gas price (0.000001 typical)
      gasLimit: number,          // Gas limit (2500 typical)
      ttl: number,               // Time to live (seconds)
      nonce?: string,            // Optional nonce
      extraSigners?: string[]    // Additional signers
    }
  }
}

Capability Structure:

interface Capability {
  role: string;           // Capability role name
  description: string;    // User-friendly description
  cap: {
    name: string;        // Capability name (e.g., 'coin.TRANSFER')
    args: any[];         // Capability arguments
  };
}

Request Example:

const signTransaction = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_requestSign',
      data: {
        networkId: 'mainnet01',
        signingCmd: {
          sender: 'k:5a2afbc...',
          chainId: '1',
          gasPrice: 0.000001,
          gasLimit: 2500,
          ttl: 28800,
          code: '(coin.transfer "k:sender..." "k:receiver..." 1.0)',
          data: {},
          caps: [
            {
              role: 'Gas Payer',
              description: 'Pay gas for transaction',
              cap: {
                name: 'coin.GAS',
                args: []
              }
            },
            {
              role: 'Sender',
              description: 'Transfer 1 KDA',
              cap: {
                name: 'coin.TRANSFER',
                args: ['k:sender...', 'k:receiver...', 1.0]
              }
            }
          ]
        }
      }
    });

    console.log('Signed transaction:', result.signedCmd);

    // Now send to blockchain
    const sendResult = await fetch(`${networkUrl}/api/v1/send`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ cmds: [result.signedCmd] })
    });

  } catch (error) {
    console.error('Signing failed:', error);
  }
};

Response:

{
  status: 'success',
  signedCmd: {
    cmd: '{"payload":{...}}',  // JSON-encoded command
    sigs: [
      {
        sig: '8d5f3c...'  // Signature hash
      }
    ],
    hash: 'transaction-hash'  // Transaction hash (request key)
  }
}

Response (Rejected):

{
  status: 'fail',
  message: 'User rejected transaction'
}

kda_requestQuickSign

Sign multiple transactions at once (KIP-0015 QuickSign).

Method: kda_requestQuickSign

Parameters:

{
  method: 'kda_requestQuickSign',
  data: {
    networkId: string,
    commandSigDatas: Array<{
      cmd: string,           // JSON-stringified command
      sigs: Array<{
        pubKey: string,      // Public key
        sig?: string | null  // Optional signature (null to request)
      }>
    }>
  }
}

Request Example:

const quickSign = async () => {
  const cmd1 = JSON.stringify({
    payload: {
      exec: {
        code: '(coin.transfer "k:sender..." "k:receiver1..." 1.0)',
        data: {}
      }
    },
    signers: [{
      pubKey: 'sender-pubkey',
      clist: [
        { name: 'coin.GAS', args: [] },
        { name: 'coin.TRANSFER', args: ['k:sender...', 'k:receiver1...', 1.0] }
      ]
    }],
    meta: {
      chainId: '1',
      sender: 'k:sender...',
      gasLimit: 2500,
      gasPrice: 0.000001,
      ttl: 28800,
      creationTime: Math.floor(Date.now() / 1000)
    },
    networkId: 'mainnet01',
    nonce: `quicksign-${Date.now()}`
  });

  try {
    const result = await window.kadena.request({
      method: 'kda_requestQuickSign',
      data: {
        networkId: 'mainnet01',
        commandSigDatas: [
          {
            cmd: cmd1,
            sigs: [{
              pubKey: 'sender-pubkey',
              sig: null  // Requesting signature
            }]
          }
          // Can include multiple commands
        ]
      }
    });

    console.log('QuickSign result:', result);

    // result.quickSignData contains signed commands

  } catch (error) {
    console.error('QuickSign failed:', error);
  }
};

Response:

{
  status: 'success',
  quickSignData: [
    {
      commandSigData: {
        cmd: '{"payload":{...}}',
        sigs: [
          {
            pubKey: 'sender-pubkey',
            sig: '8d5f3c...'  // Signature added
          }
        ]
      },
      outcome: {
        hash: 'transaction-hash',
        result: 'success'
      }
    }
    // One entry per command
  ]
}

Response (Error):

{
  status: 'fail',
  error: 'QuickSign fail: wallet public key not found'
}

See QuickSign (KIP-0015) for detailed guide.

Token Transfers

kda_sendKadena

Simplified method for sending KDA tokens. Opens eckoWALLET UI for user confirmation.

Method: kda_sendKadena

Parameters:

{
  method: 'kda_sendKadena',
  data: {
    networkId: string,
    account: string,        // Destination account
    amount: number,         // Amount to send
    chainId: string,        // Destination chain
    sourceChainId: string,  // Source chain
    domain: string          // Your dApp domain
  }
}

Request Example:

const sendKDA = async () => {
  try {
    const result = await window.kadena.request({
      method: 'kda_sendKadena',
      data: {
        networkId: 'mainnet01',
        account: 'k:receiver-public-key',
        amount: 1.5,
        chainId: '1',
        sourceChainId: '1',
        domain: window.location.hostname
      }
    });

    console.log('Transfer result:', result);
  } catch (error) {
    console.error('Transfer failed:', error);
  }
};

Response:

{
  status: 'success',
  message: 'Transaction sent',
  data: {
    requestKey: 'transaction-hash'
  }
}

Events

eckoWALLET emits events that your dApp can listen to.

Event Listener Setup

// Generic event listener
window.kadena.on(eventName, (event) => {
  console.log('Event received:', event);
});

Available Events

res_accountChange

Triggered when user switches accounts in eckoWALLET.

Event Name: res_accountChange

Listener:

window.kadena.on('res_accountChange', (event) => {
  console.log('Account changed:', event);
  // Update your dApp UI with new account
  updateUIWithNewAccount();
});

Event Payload:

{
  result: {
    status: 'success',
    message: 'Account changed'
  },
  target: 'kda.dapps',
  action: 'res_accountChange'
}

Handling Account Changes:

window.kadena.on('res_accountChange', async (event) => {
  // Fetch new account details
  const accountInfo = await window.kadena.request({
    method: 'kda_getSelectedAccount'
  });

  // Update your UI
  updateAccountDisplay(accountInfo.account);

  // Refresh balances, etc.
  await refreshUserData();
});

res_checkStatus

Emitted when connection status changes.

Event Name: res_checkStatus

Listener:

window.kadena.on('res_checkStatus', (event) => {
  if (event.result.status === 'success') {
    console.log('Connected:', event.result.account);
  } else {
    console.log('Disconnected');
  }
});

res_requestSign

Emitted when a signing request completes.

Event Name: res_requestSign

Listener:

window.kadena.on('res_requestSign', (event) => {
  if (event.status === 'success') {
    console.log('Transaction signed:', event.signedCmd);
  } else {
    console.log('Signing rejected or failed');
  }
});

Other Events

Additional events you can listen for:

• res_requestQuickSign - QuickSign completion

• res_sendKadena - Token send completion

• res_getNetwork - Network change

• res_getChain - Chain change

• res_disconnect - Disconnection

• res_requestAccount - Account request completion

Event Handler Best Practices

class WalletEventHandler {
  constructor() {
    this.setupListeners();
  }

  setupListeners() {
    // Account changes
    window.kadena.on('res_accountChange', this.handleAccountChange.bind(this));

    // Network/chain changes
    window.kadena.on('res_getNetwork', this.handleNetworkChange.bind(this));
    window.kadena.on('res_getChain', this.handleChainChange.bind(this));
  }

  async handleAccountChange(event) {
    console.log('Account changed, refreshing...');
    await this.refreshAccountData();
  }

  async handleNetworkChange(event) {
    console.log('Network changed:', event);
    await this.reinitialize();
  }

  async handleChainChange(event) {
    console.log('Chain changed:', event);
    await this.updateChainDisplay();
  }

  async refreshAccountData() {
    // Implement your refresh logic
  }
}

// Usage
const eventHandler = new WalletEventHandler();

Error Handling

Common Errors

User Rejection:

{
  status: 'fail',
  message: 'User rejected the request'
}

Wallet Locked:

{
  status: 'fail',
  message: 'Wallet is locked'
}

Not Connected:

{
  status: 'fail',
  message: 'Not connected'
}

Invalid Network:

{
  status: 'fail',
  message: 'Invalid network ID'
}

Insufficient Balance:

{
  status: 'fail',
  message: 'Insufficient balance for transaction'
}

Error Handling Pattern

const safeRequest = async (requestConfig) => {
  try {
    const result = await window.kadena.request(requestConfig);

    if (result.status === 'fail') {
      // Handle failure response
      throw new Error(result.message || 'Request failed');
    }

    return result;

  } catch (error) {
    // Handle exceptions
    console.error('Request error:', error);

    if (error.message?.includes('User rejected')) {
      // User cancelled - don't show error
      console.log('User cancelled the request');
    } else if (error.message?.includes('locked')) {
      // Wallet locked - prompt to unlock
      alert('Please unlock your eckoWALLET');
    } else {
      // Other errors
      alert('An error occurred: ' + error.message);
    }

    throw error;
  }
};

// Usage
try {
  const result = await safeRequest({
    method: 'kda_connect',
    networkId: 'mainnet01'
  });
  // Handle success
} catch (error) {
  // Already handled in safeRequest
}

TypeScript Types

Type Definitions

// Window interface extension
declare global {
  interface Window {
    kadena?: KadenaWallet;
  }
}

interface KadenaWallet {
  isKadena: boolean;
  request: <T = any>(args: RequestArguments) => Promise<T>;
  on: (eventName: string, handler: (event: any) => void) => void;
}

interface RequestArguments {
  method: string;
  networkId?: string;
  data?: any;
}

// Network info
interface NetworkInfo {
  name: string;
  url: string;
  networkId: string;
  explorer: string;
  id: string;
  isDefault: boolean;
}

// Account info
interface AccountInfo {
  account: string;
  publicKey: string;
  chainId?: string;
  connectedSites?: string[];
  balance?: number;
}

// Connection response
interface ConnectResponse {
  status: 'success' | 'fail';
  message: string;
  account?: {
    account: string;
    publicKey: string;
    chainId: string;
  };
}

// Signing command
interface SigningCommand {
  code: string;
  data?: Record<string, any>;
  caps: Capability[];
  sender: string;
  chainId: string;
  gasPrice: number;
  gasLimit: number;
  ttl: number;
  nonce?: string;
  extraSigners?: string[];
}

interface Capability {
  role: string;
  description: string;
  cap: {
    name: string;
    args: any[];
  };
}

// Sign response
interface SignResponse {
  status: 'success' | 'fail';
  signedCmd?: {
    cmd: string;
    sigs: Array<{ sig: string }>;
    hash: string;
  };
  message?: string;
}

// QuickSign command
interface QuickSignCommandSigData {
  cmd: string;
  sigs: Array<{
    pubKey: string;
    sig: string | null;
  }>;
}

interface QuickSignResponse {
  status: 'success' | 'fail';
  quickSignData?: Array<{
    commandSigData: QuickSignCommandSigData;
    outcome: {
      hash: string;
      result: string;
    };
  }>;
  error?: string;
}

// Send Kadena
interface SendKadenaData {
  networkId: string;
  account: string;
  amount: number;
  chainId: string;
  sourceChainId: string;
  domain: string;
}

interface SendKadenaResponse {
  status: 'success' | 'fail';
  message: string;
  data?: {
    requestKey: string;
  };
}

Usage with TypeScript

import { KadenaWallet, ConnectResponse, SignResponse } from './types';

const connectWallet = async (): Promise<AccountInfo | null> => {
  if (!window.kadena?.isKadena) {
    console.error('eckoWALLET not installed');
    return null;
  }

  try {
    const response = await window.kadena.request<ConnectResponse>({
      method: 'kda_connect',
      networkId: 'mainnet01'
    });

    if (response.status === 'success' && response.account) {
      return {
        account: response.account.account,
        publicKey: response.account.publicKey,
        chainId: response.account.chainId
      };
    }

    return null;
  } catch (error) {
    console.error('Connection failed:', error);
    return null;
  }
};

Rate Limiting

eckoWALLET may rate-limit requests to prevent abuse:

• Maximum 10 requests per second per dApp

• Excessive requests may be throttled

• Implement debouncing for frequent calls

// Debounce helper
const debounce = (func, wait) => {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => func(...args), wait);
  };
};

// Debounced status check
const checkStatus = debounce(async () => {
  await window.kadena.request({
    method: 'kda_checkStatus',
    networkId: 'mainnet01'
  });
}, 1000);

Best Practices

1. Always Check Installation

if (!window.kadena?.isKadena) {
  // Prompt user to install
  window.open('https://eckowallet.com', '_blank');
  return;
}

2. Handle Connection State

// Check on page load
const initConnection = async () => {
  const status = await window.kadena.request({
    method: 'kda_checkStatus',
    networkId: 'mainnet01'
  });

  if (status.result.status === 'success') {
    // Already connected
    setConnected(true);
  } else {
    // Not connected, show connect button
    setConnected(false);
  }
};

3. Listen to Account Changes

// Update UI when account changes
window.kadena.on('res_accountChange', async () => {
  await refreshAccountData();
});

4. Provide User Feedback

const signTransaction = async () => {
  setLoading(true);
  setStatus('Waiting for approval...');

  try {
    const result = await window.kadena.request({
      method: 'kda_requestSign',
      data: signingCmd
    });

    setStatus('Transaction signed, sending to blockchain...');
    // Send to blockchain...

    setStatus('Transaction complete!');
  } catch (error) {
    setStatus('Transaction failed');
  } finally {
    setLoading(false);
  }
};

5. Handle Errors Gracefully

try {
  const result = await window.kadena.request(config);
} catch (error) {
  if (error.message?.includes('User rejected')) {
    // Don't show error, user intentionally cancelled
  } else {
    // Show error to user
    showErrorNotification(error.message);
  }
}

Next Steps

• dApp Integration Guide - Step-by-step integration tutorial

• Transaction Signing - Deep dive into signing

• QuickSign (KIP-0015) - Batch signing guide

• Code Examples - Ready-to-use code samples

• Testing Your Integration - Testing guide

Need Help?

• Join our Discord: https://discord.com/invite/runonflux

• Follow us: @eckoWALLET

• Report issues: GitHub