Skip to main content

HoosatClient API Reference

Complete API reference for the HoosatClient class - the main interface for interacting with Hoosat blockchain nodes.

Constructor​

new HoosatClient(config?: HoosatClientConfig)​

Creates a new Hoosat client instance.

Parameters:

interface HoosatClientConfig {
  // Single-node configuration (legacy mode)
  host?: string;              // Node hostname/IP (default: '127.0.0.1')
  port?: number;              // Node port (default: 42420)
  timeout?: number;           // Request timeout in ms (default: 10000)

  // Multi-node configuration (high availability)
  nodes?: NodeConfig[];       // Array of nodes for failover
  healthCheckInterval?: number;    // Health check interval in ms (default: 30000)
  retryAttempts?: number;         // Retry attempts per request (default: 3)
  retryDelay?: number;            // Delay between retries in ms (default: 1000)
  requireUtxoIndex?: boolean;     // Only use nodes with UTXO index (default: true)
  requireSynced?: boolean;        // Only use synced nodes (default: true)

  // Event manager configuration
  events?: EventManagerConfig;
  debug?: boolean;            // Enable debug logging (default: false)
}

interface NodeConfig {
  host: string;               // Node hostname or IP
  port: number;               // Node port
  timeout?: number;           // Per-node timeout override
  primary?: boolean;          // Designate as primary node
  name?: string;              // Optional name for logging
}

Examples:

// Single node
const client = new HoosatClient({
  host: '54.38.176.95',
  port: 42420
});

// Multi-node with failover
const client = new HoosatClient({
  nodes: [
    { host: '54.38.176.95', port: 42420, primary: true, name: 'Primary' },
    { host: 'backup.example.com', port: 42420, name: 'Backup' }
  ],
  healthCheckInterval: 30000,
  requireUtxoIndex: true,
  requireSynced: true
});

Node Information​

getInfo()​

Get node information and status.

Returns: Promise<BaseResult<GetInfo>>

interface GetInfo {
  p2pId: string;
  mempoolSize: string;
  serverVersion: string;
  isUtxoIndexed: boolean;
  isSynced: boolean;
}

Example:

const info = await client.getInfo();

if (info.ok) {
  console.log('Version:', info.result.serverVersion);
  console.log('Synced:', info.result.isSynced);
  console.log('UTXO Index:', info.result.isUtxoIndexed);
  console.log('Mempool size:', info.result.mempoolSize);
}

getCurrentNetwork()​

Get current network type (mainnet/testnet).

Returns: Promise<BaseResult<GetCurrentNetwork>>

interface GetCurrentNetwork {
  currentNetwork: string; // 'hoosat-mainnet' or 'hoosat-testnet-10'
}

getConnectedPeerInfo()​

Get information about connected peers.

Returns: Promise<BaseResult<GetConnectedPeerInfo>>

Blockchain Queries​

getSelectedTipHash()​

Get the hash of the current selected tip block.

Returns: Promise<BaseResult<GetSelectedTipHash>>

interface GetSelectedTipHash {
  selectedTipHash: string;
}

getBlock(blockHash: string, includeTransactions?: boolean)​

Get block data by hash.

Parameters:

  • blockHash - Block hash (64-character hex string)
  • includeTransactions - Include full transaction data (default: false)

Returns: Promise<BaseResult<GetBlock>>

Example:

const block = await client.getBlock(blockHash, true);

if (block.ok) {
  console.log('Block height:', block.result.header.blueScore);
  console.log('Transactions:', block.result.transactions.length);
}

getBlocks(lowHash: string, includeTransactions?: boolean)​

Get multiple blocks starting from a hash.

Returns: Promise<BaseResult<GetBlocks>>

getBlockCount()​

Get current blockchain height.

Returns: Promise<BaseResult<GetBlockCount>>

const count = await client.getBlockCount();
if (count.ok) {
  console.log('Height:', count.result.blockCount);
}

getBlockDagInfo()​

Get DAG structure information.

Returns: Promise<BaseResult<GetBlockDagInfo>>

Balance & UTXOs​

getBalance(address: string)​

Get balance for a single address.

Parameters:

  • address - Hoosat address (with hoosat: prefix)

Returns: Promise<BaseResult<GetBalanceByAddress>>

interface GetBalanceByAddress {
  address: string;
  balance: string;  // Balance in sompi
}

Example:

const result = await client.getBalance('hoosat:qz7ulu...');

if (result.ok) {
  const htn = HoosatUtils.sompiToAmount(result.result.balance);
  console.log(`Balance: ${htn} HTN`);
}

getBalancesByAddresses(addresses: string[])​

Get balances for multiple addresses.

Parameters:

  • addresses - Array of Hoosat addresses

Returns: Promise<BaseResult<GetBalancesByAddresses>>

interface GetBalancesByAddresses {
  entries: Array<{
    address: string;
    balance: string;
  }>;
}

Example:

const result = await client.getBalancesByAddresses([
  'hoosat:qz7ulu...',
  'hoosat:qq8xdv...'
]);

if (result.ok) {
  result.result.entries.forEach(entry => {
    console.log(`${entry.address}: ${entry.balance} sompi`);
  });
}

getUtxosByAddresses(addresses: string[])​

Get UTXOs for addresses.

Parameters:

  • addresses - Array of Hoosat addresses

Returns: Promise<BaseResult<GetUtxosByAddresses>>

interface GetUtxosByAddresses {
  utxos: UtxoForSigning[];
}

interface UtxoForSigning {
  outpoint: {
    transactionId: string;
    index: number;
  };
  utxoEntry: {
    amount: string;
    scriptPublicKey: {
      scriptPublicKey: string;
      version: number;
    };
    blockDaaScore: string;
    isCoinbase: boolean;
  };
}

Example:

const result = await client.getUtxosByAddresses([wallet.address]);

if (result.ok) {
  const utxos = result.result.utxos;
  console.log(`Found ${utxos.length} UTXOs`);

  utxos.forEach(utxo => {
    console.log(`Amount: ${utxo.utxoEntry.amount} sompi`);
    console.log(`TX: ${utxo.outpoint.transactionId}`);
  });
}

Transactions​

submitTransaction(transaction: Transaction, allowOrphan?: boolean)​

Submit a signed transaction to the network.

Parameters:

  • transaction - Signed transaction object
  • allowOrphan - Allow orphan transactions (default: false)

Returns: Promise<BaseResult<SubmitTransaction>>

interface SubmitTransaction {
  transactionId: string;
}

Example:

const result = await client.submitTransaction(signedTx);

if (result.ok) {
  console.log('TX ID:', result.result.transactionId);
} else {
  console.error('Submit failed:', result.error);
}

getTransactionStatus(txId: string, senderAddress: string, recipientAddress: string)​

Check transaction status (PENDING/CONFIRMED/NOT_FOUND).

Parameters:

  • txId - Transaction ID
  • senderAddress - Sender address
  • recipientAddress - Recipient address

Returns: Promise<BaseResult<GetTransactionStatus>>

interface GetTransactionStatus {
  status: 'PENDING' | 'CONFIRMED' | 'NOT_FOUND';
  details: {
    message?: string;
    fee?: string;
    blockDaaScore?: string;
  };
}

Example:

const status = await client.getTransactionStatus(
  txId,
  senderAddr,
  recipientAddr
);

if (status.ok) {
  switch (status.result.status) {
    case 'PENDING':
      console.log('In mempool, fee:', status.result.details.fee);
      break;
    case 'CONFIRMED':
      console.log('Confirmed in block:', status.result.details.blockDaaScore);
      break;
    case 'NOT_FOUND':
      console.log('Not found:', status.result.details.message);
      break;
  }
}

Note: Node must be started with --utxoindex flag for CONFIRMED status detection.

Mempool​

getMempoolEntry(txId: string, includeOrphanPool?: boolean, filterTransactionPool?: boolean)​

Get single mempool entry.

Parameters:

  • txId - Transaction ID
  • includeOrphanPool - Search orphan pool (default: true)
  • filterTransactionPool - Filter transaction pool (default: true)

Returns: Promise<BaseResult<GetMempoolEntry>>

getMempoolEntries(includeOrphanPool?: boolean, filterTransactionPool?: boolean)​

Get all mempool entries.

Returns: Promise<BaseResult<GetMempoolEntries>>

const mempool = await client.getMempoolEntries();

if (mempool.ok) {
  console.log('Mempool size:', mempool.result.entries.length);
}

getMempoolEntriesByAddresses(addresses: string[], includeOrphanPool?: boolean, filterTransactionPool?: boolean)​

Get mempool entries for specific addresses.

Returns: Promise<BaseResult<GetMempoolEntriesByAddresses>>

Events​

The client includes an integrated event manager accessible via client.events.

See HoosatEventManager for complete documentation.

Quick example:

// Subscribe to UTXO changes
await client.events.subscribeToUtxoChanges([address]);

// Listen for changes
client.events.on(EventType.UtxoChange, (notification) => {
  console.log('UTXOs changed!');
});

Node Management (Multi-Node)​

getNodesStatus()​

Get health status of all configured nodes.

Returns: NodeStatus[] | null

interface NodeStatus {
  config: NodeConfig;
  health: NodeHealth;
}

interface NodeHealth {
  isHealthy: boolean;
  isSynced: boolean;
  hasUtxoIndex: boolean;
  lastCheckTime: number;
  error?: string;
}

Example:

const status = client.getNodesStatus();

status?.forEach(node => {
  console.log(`${node.config.name}:`);
  console.log(`  Healthy: ${node.health.isHealthy}`);
  console.log(`  Synced: ${node.health.isSynced}`);
  console.log(`  UTXO Index: ${node.health.hasUtxoIndex}`);
});

Client Info​

getClientInfo()​

Get current client configuration.

Returns: Object with host, port, and timeout.

const info = client.getClientInfo();
console.log(`Connected to ${info.host}:${info.port}`);

Connection Management​

disconnect()​

Close all connections and clean up resources.

Returns: void

// Cleanup
await client.events.unsubscribeFromAll();
client.disconnect();

Response Format​

All methods return BaseResult<T>:

interface BaseResult<T> {
  ok: boolean;         // true if successful
  result: T | null;    // Result data if successful
  error: string | null; // Error message if failed
}

Always check .ok before accessing .result:

const result = await client.getBalance(address);

if (result.ok) {
  // Safe to use result.result
  console.log(result.result.balance);
} else {
  // Handle error
  console.error(result.error);
}

Error Handling​

Common errors:

  • Connection errors - Node unreachable
  • Timeout errors - Request took too long
  • Invalid parameters - Bad address format, etc.
  • Node errors - Node returned error

Example:

try {
  const result = await client.getBalance(address);

  if (!result.ok) {
    // Expected error (bad address, etc.)
    console.error('Request failed:', result.error);
    return;
  }

  // Success
  console.log('Balance:', result.result.balance);
} catch (error) {
  // Unexpected error (network, etc.)
  console.error('Fatal error:', error);
}

Next Steps​