API Reference Overview

Complete API reference for the Hoosat JavaScript/TypeScript SDK.

Core Modules

The Hoosat SDK provides 8 core modules for interacting with the Hoosat blockchain:

HoosatClient

Main client for connecting to Hoosat nodes and querying blockchain data.

Key Features:

Node connection management
Blockchain queries (blocks, DAG info, network stats)
Balance and UTXO queries
Transaction submission
Multi-node failover support

Quick Example:

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

const balance = await client.getBalance(address);

HoosatCrypto

Cryptographic operations for key management and transactions.

Key Features:

Key pair generation (ECDSA secp256k1)
Wallet import/export
Address generation
Transaction signing
BLAKE3 hashing

Quick Example:

const wallet = HoosatCrypto.generateKeyPair('mainnet');
console.log('Address:', wallet.address);

HoosatTxBuilder

Fluent transaction builder with automatic change calculation.

Key Features:

Chainable API
Automatic change calculation
Input/output management
Built-in validation
Spam protection compliance

Quick Example:

const builder = new HoosatTxBuilder();

builder
  .addInput(utxo, wallet.privateKey)
  .addOutput(recipientAddress, amount)
  .setFee(feeEstimate.totalFee)
  .addChangeOutput(wallet.address);

const signedTx = builder.sign();

Fee Calculation

Automatic minimum fee calculation using MASS-based formula.

Key Features:

Automatic fee calculation via client.calculateMinFee()
Manual calculation via HoosatCrypto.calculateMinFee()
MASS-based formula (HTND compatible)
Payload size support
No dynamic fee estimation

Quick Example:

// Automatic (recommended)
const minFee = await client.calculateMinFee(wallet.address);

// Or manual
const minFee = HoosatCrypto.calculateMinFee(
  2,  // inputs
  2   // outputs
);

HoosatUtils

Utility functions for validation, conversion, and formatting.

Key Features:

Amount conversion (HTN ↔ sompi)
Address validation
Network detection
Amount formatting
Private key validation

Quick Example:

// Convert HTN to sompi
const sompi = HoosatUtils.amountToSompi('1.5');

// Validate address
if (HoosatUtils.isValidAddress(address)) {
  // Process address
}

HoosatEventManager

Real-time event streaming and WebSocket management.

Key Features:

UTXO change monitoring
Block notifications
Virtual DAG updates
Automatic reconnection
Multi-subscription support

Quick Example:

await client.events.subscribeToUtxoChanges([address]);

client.events.on(EventType.UtxoChange, (notification) => {
  console.log('Balance changed!');
});

HoosatQR

QR code generation and payment URI handling.

Key Features:

Payment request QR codes
Address QR codes
URI encoding/decoding
Customizable styling
Mobile wallet integration

Quick Example:

const qr = await HoosatQR.generatePaymentQR({
  address: merchantAddress,
  amount: HoosatUtils.amountToSompi('1.5'),
  label: 'My Store',
  message: 'Order #12345'
});

HoosatSigner

Message signing and verification for authentication.

Key Features:

Cryptographic message signing
Signature verification
Address ownership proofs
Authentication challenges
Authorization tokens

Quick Example:

const signature = HoosatSigner.signMessage(message, wallet.privateKey);

const isValid = HoosatSigner.verifyMessage(
  message,
  signature,
  wallet.address
);

Type Definitions

Common Types

// Network type
type HoosatNetwork = 'mainnet' | 'testnet';

// Key pair
interface KeyPair {
  address: string;
  publicKey: Buffer;
  privateKey: Buffer;
}

// API result wrapper
interface BaseResult<T> {
  ok: boolean;
  result?: T;
  error?: string;
}

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

// Transaction
interface Transaction {
  version: number;
  inputs: TransactionInput[];
  outputs: TransactionOutput[];
  lockTime: string;
  subnetworkId: string;
  gas: string;
  payload: string;
}

Event Types

enum EventType {
  UtxoChange = 'utxo_change',
  BlockAdded = 'block_added',
  VirtualDagChanged = 'virtual_dag_changed'
}

interface UtxoChangeNotification {
  address: string;
  added: UtxoEntry[];
  removed: UtxoEntry[];
}

interface BlockAddedNotification {
  blockHash: string;
  blockHeader: BlockHeader;
}

Fee Calculation

The SDK uses MASS-based minimum fee calculation:

// Automatic fee calculation
const minFee: string = await client.calculateMinFee(
  address: string,
  payloadSize?: number
);

// Manual fee calculation
const minFee: string = HoosatCrypto.calculateMinFee(
  inputsCount: number,
  outputsCount: number,
  payloadSize?: number
);

Module Comparison

Module	Purpose	Common Use Cases
HoosatClient	Blockchain queries	Check balance, get UTXOs, submit transactions, calculate fees
HoosatCrypto	Key management	Generate wallets, sign transactions, calculate fees, hash data
HoosatTxBuilder	Build transactions	Send payments, consolidate UTXOs, batch transfers
HoosatUtils	Validation & conversion	Validate addresses, convert amounts, format data
HoosatEventManager	Real-time monitoring	Track balance changes, monitor blocks
HoosatQR	Payment requests	Generate QR codes, handle payment URIs
HoosatSigner	Authentication	Prove ownership, sign messages, verify signatures

Quick Start Examples

Check Balance

import { HoosatClient, HoosatUtils } from 'hoosat-sdk';

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

const result = await client.getBalance(address);

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

Send Transaction

import {
  HoosatClient,
  HoosatCrypto,
  HoosatTxBuilder,
  HoosatUtils
} from 'hoosat-sdk';

const client = new HoosatClient({ host: '54.38.176.95', port: 42420 });
const wallet = HoosatCrypto.importKeyPair(process.env.WALLET_PRIVATE_KEY!);

// Get UTXOs
const utxosResult = await client.getUtxosByAddresses([wallet.address]);
const utxos = utxosResult.result.utxos;

// Calculate minimum fee
const minFee = await client.calculateMinFee(wallet.address);

// Build and sign transaction
const builder = new HoosatTxBuilder();

for (const utxo of utxos) {
  builder.addInput(utxo, wallet.privateKey);
}

builder
  .addOutput(recipientAddress, HoosatUtils.amountToSompi('1.0'))
  .setFee(minFee)
  .addChangeOutput(wallet.address);

const signedTx = builder.sign();

// Submit
const result = await client.submitTransaction(signedTx);

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

Monitor Balance

import { HoosatClient, EventType, HoosatUtils } from 'hoosat-sdk';

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

await client.events.subscribeToUtxoChanges([address]);

client.events.on(EventType.UtxoChange, (notification) => {
  let change = 0n;

  for (const utxo of notification.added) {
    change += BigInt(utxo.utxoEntry.amount);
  }

  for (const utxo of notification.removed) {
    change -= BigInt(utxo.utxoEntry.amount);
  }

  console.log('Balance changed by:', HoosatUtils.sompiToAmount(change), 'HTN');
});

Error Handling

All SDK methods use a consistent error handling pattern:

interface BaseResult<T> {
  ok: boolean;
  result?: T;
  error?: string;
}

// Usage
const result = await client.getBalance(address);

if (result.ok) {
  // Success - use result.result
  console.log('Balance:', result.result.balance);
} else {
  // Error - check result.error
  console.error('Error:', result.error);
}

Benefits:

Type-safe error handling
No thrown exceptions for API calls
Explicit success/failure checking
Detailed error messages

Constants

Network Prefixes

const MAINNET_PREFIX = 'hoosat:';
const TESTNET_PREFIX = 'hoosattest:';

Unit Conversion

const SOMPI_PER_HTN = 100000000n;  // 1 HTN = 100,000,000 sompi

Dust Threshold

const DUST_THRESHOLD = 1000n;  // 1000 sompi

Address Versions

const ADDRESS_VERSION_SCHNORR = 0x00;
const ADDRESS_VERSION_ECDSA = 0x01;
const ADDRESS_VERSION_P2SH = 0x08;

Spam Protection Limits

const MAX_RECIPIENT_OUTPUTS = 2;   // Max recipients per transaction
const MAX_TOTAL_OUTPUTS = 3;       // Max total outputs (recipients + change)

Next Steps

Getting Started - Install and setup
Quick Start Guide - First transaction
Core Concepts - Understand architecture
Examples - Working code examples
Guides - Detailed usage guides

Core Modules​

Type Definitions​

Common Types​

Event Types​

Fee Calculation​

Module Comparison​

Quick Start Examples​

Check Balance​

Send Transaction​

Monitor Balance​

Error Handling​

Constants​

Network Prefixes​

Unit Conversion​

Dust Threshold​

Address Versions​

Spam Protection Limits​

Next Steps​

Core Modules

Type Definitions

Common Types

Event Types

Fee Calculation

Module Comparison

Quick Start Examples

Check Balance

Send Transaction

Monitor Balance

Error Handling

Constants

Network Prefixes

Unit Conversion

Dust Threshold

Address Versions

Spam Protection Limits

Next Steps