Skip to main content

Wallet API

The Wallet API exposes 7 methods for querying balances, managing wallets, listing transactions, sending on-chain transactions, and checking transaction status.

Methods​

MethodParametersReturnsDescription
getWalletBalance(walletAddress, chains?)walletAddress: string, chains?: string[]ApiResponse<EngineWalletBalance[]>Returns native and token balances across one or more chains.
getPortfolioSummary(walletAddress)walletAddress: stringApiResponse<PortfolioSummary>Returns an aggregated portfolio value with per-chain breakdown.
getUserWallets(chainId?)chainId?: stringApiResponse<UserWallet[]>Lists all wallets belonging to the authenticated user, optionally filtered by chain.
createWallet(chainId, type)chainId: string, type: 'eoa' | 'smart'ApiResponse<UserWallet>Creates a new wallet on the specified chain.
getWalletTransactions(walletAddress, options?)walletAddress: string, options?: TransactionQueryOptionsApiResponse<Transaction[]>Returns the transaction history for a wallet.
sendTransaction(request)request: EngineTransactionRequestApiResponse<EngineTransactionResponse>Submits an on-chain transaction via the engine relay.
getTransactionStatus(txId)txId: stringApiResponse<Transaction>Polls the status of a previously submitted transaction.

Types​

EngineWalletBalance​

interface EngineWalletBalance {
  chainId: string;
  chainName: string;
  nativeBalance: string;
  nativeSymbol: string;
  nativeUsdValue: string;
  tokens: TokenBalance[];
}

TokenBalance​

interface TokenBalance {
  contractAddress: string;
  symbol: string;
  name: string;
  decimals: number;
  balance: string;
  usdValue: string;
  logoUrl?: string;
}

PortfolioSummary​

interface PortfolioSummary {
  totalUsdValue: string;
  chains: {
    chainId: string;
    chainName: string;
    usdValue: string;
    percentage: number;
  }[];
}

UserWallet​

interface UserWallet {
  id: string;
  address: string;
  chainId: string;
  type: 'eoa' | 'smart';
  label?: string;
  createdAt: string;
}

TransactionQueryOptions​

interface TransactionQueryOptions {
  /** Filter by chain. */
  chainId?: string;
  /** Number of records to return. Default 20. */
  limit?: number;
  /** Pagination cursor. */
  cursor?: string;
  /** Filter by status. */
  status?: 'pending' | 'confirmed' | 'failed';
}

EngineTransactionRequest​

interface EngineTransactionRequest {
  /** Sender wallet address. */
  from: string;
  /** Recipient address. */
  to: string;
  /** Chain to execute on. */
  chainId: string;
  /** Amount in token units (human-readable, e.g. "1.5"). */
  amount: string;
  /** Token contract address. Omit for native currency. */
  tokenAddress?: string;
  /** Optional calldata for contract interactions. */
  data?: string;
  /** Optional gas limit override. */
  gasLimit?: string;
}

EngineTransactionResponse​

interface EngineTransactionResponse {
  /** Engine-assigned transaction ID for status polling. */
  txId: string;
  /** On-chain transaction hash (available once submitted). */
  txHash?: string;
  /** Current status. */
  status: 'queued' | 'submitted' | 'pending' | 'confirmed' | 'failed';
}

Transaction​

interface Transaction {
  txId: string;
  txHash: string;
  chainId: string;
  from: string;
  to: string;
  amount: string;
  tokenAddress?: string;
  tokenSymbol?: string;
  status: 'pending' | 'confirmed' | 'failed';
  blockNumber?: number;
  timestamp: string;
  gasUsed?: string;
  fee?: string;
}

Examples​

Get Wallet Balance​

// Single chain
const res = await engine.getWalletBalance('0xABC...', ['ethereum']);

if (res.success && res.data) {
  for (const chain of res.data) {
    console.log(`${chain.chainName}: ${chain.nativeBalance} ${chain.nativeSymbol}`);
    for (const token of chain.tokens) {
      console.log(`  ${token.symbol}: ${token.balance} ($${token.usdValue})`);
    }
  }
}

Get Portfolio Summary​

const res = await engine.getPortfolioSummary('0xABC...');

if (res.success && res.data) {
  console.log(`Total value: $${res.data.totalUsdValue}`);
  for (const chain of res.data.chains) {
    console.log(`  ${chain.chainName}: $${chain.usdValue} (${chain.percentage}%)`);
  }
}

Create a Smart Wallet​

const res = await engine.createWallet('ethereum', 'smart');

if (res.success && res.data) {
  console.log('New wallet:', res.data.address);
}

Send a Transaction​

const res = await engine.sendTransaction({
  from: '0xABC...',
  to: '0xDEF...',
  chainId: 'ethereum',
  amount: '0.1',
  // tokenAddress omitted = native ETH transfer
});

if (res.success && res.data) {
  console.log('Transaction queued:', res.data.txId);

  // Poll for confirmation
  let status = res.data.status;
  while (status !== 'confirmed' && status !== 'failed') {
    await new Promise(r => setTimeout(r, 3000));
    const poll = await engine.getTransactionStatus(res.data.txId);
    if (poll.success && poll.data) {
      status = poll.data.status;
      console.log('Status:', status);
    }
  }
}

List Wallet Transactions​

const res = await engine.getWalletTransactions('0xABC...', {
  chainId: 'ethereum',
  limit: 10,
  status: 'confirmed',
});

if (res.success && res.data) {
  for (const tx of res.data) {
    console.log(`${tx.txHash} | ${tx.amount} ${tx.tokenSymbol ?? 'ETH'} | ${tx.status}`);
  }
}

Next Steps​