Wallet API

Wallet API 提供 7 个方法，用于查询余额、管理钱包、列出交易记录、发送链上交易以及检查交易状态。

方法

方法	参数	返回值	说明
getWalletBalance(walletAddress, chains?)	walletAddress: string, chains?: string[]	ApiResponse<EngineWalletBalance[]>	返回一条或多条链上的原生代币和代币余额。
getPortfolioSummary(walletAddress)	walletAddress: string	ApiResponse<PortfolioSummary>	返回聚合的投资组合价值及按链分类的明细。
getUserWallets(chainId?)	chainId?: string	ApiResponse<UserWallet[]>	列出已验证用户的所有钱包，可选按链筛选。
createWallet(chainId, type)	chainId: string, type: 'eoa' | 'smart'	ApiResponse<UserWallet>	在指定链上创建新钱包。
getWalletTransactions(walletAddress, options?)	walletAddress: string, options?: TransactionQueryOptions	ApiResponse<Transaction[]>	返回钱包的交易历史记录。
sendTransaction(request)	request: EngineTransactionRequest	ApiResponse<EngineTransactionResponse>	通过 engine 中继提交链上交易。
getTransactionStatus(txId)	txId: string	ApiResponse<Transaction>	轮询先前提交的交易状态。

类型

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

示例

获取钱包余额

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

获取投资组合摘要

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

创建智能钱包

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

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

发送交易

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

列出钱包交易

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

下一步

• Swap API -- 跨 DEX 兑换代币。
• On-ramp & Off-ramp API -- 使用法币买卖加密货币。