@healchain/sdk v1.2.0

JavaScript SDK for HealChain — self-healing decentralized storage using Reed-Solomon erasure coding across multiple EVM chains.

Install

npm install @healchain/sdk

Quick Start

import HealChain from '@healchain/sdk';

const hc = new HealChain({
  apiUrl: 'https://api.healchain.org',
  apiKey: 'your-api-key',
});

// Store data — oracle fulfills automatically
const { recordId, chainId } = await hc.store('Hello World', {
  label: 'my first record',
});
console.log(`Stored as record #${recordId} on chain ${chainId}`);

// Retrieve — auto-discovers chain from GlobalRegistry
const { text, chainId: retrievedFrom } = await hc.retrieve(recordId);
console.log(`Retrieved from chain ${retrievedFrom}: ${text}`);

API

new HealChain(options)

| Option | Type | Default | Description | |---|---|---|---| | apiUrl | string | https://api.healchain.org | API base URL | | apiKey | string | — | API key (required for store/retrieve) | | chain | string | 'auto' | Chain: 'auto', 'sepolia', 'arbitrum', 'base', etc. | | preference | string | '' | 'cheapest' | 'fastest' | 'redundant' | '' (auto weighted) | | pollInterval | number | 4000 | Oracle poll interval in ms | | pollTimeout | number | 120000 | Max wait for oracle fulfillment in ms | | dataShards | number | 10 | Default RS data shards | | parityShards | number | 4 | Default RS parity shards |

hc.store(data, options?)

Store data on-chain. Polls until the oracle fulfills the request.

Parameters:

• data — string or Uint8Array
• options.label — record label (default: 'sdk upload')
• options.chain — override chain for this store
• options.preference — override preference for this store
• options.onFulfilled — callback when oracle fulfills: (result) => void

Returns: { recordId, tx, chainId, originalSize, encodedSize, ciDigestHash }

hc.retrieve(id)

Retrieve data by record ID. Auto-discovers which chain the record lives on.

Returns: { text, hex, chainId, originalSize, label }

hc.estimateFee(sizeBytes, chain?)

Estimate the fee for storing data of a given size.

Returns: { feeCents, feeUsd, sizeBytes, chain }

const fee = await hc.estimateFee(1024, 'auto');
console.log(`Fee: ${fee.feeUsd}`); // e.g. "$0.05"

hc.chainScores()

Get current chain scoring data (cost, reliability, latency).

Returns: array of chain score objects

hc.getMetadata(id)

Get record metadata without retrieving the data.

Returns: { id, label, originalSize, encodedSize, dataShards, parityShards, owner, timestamp, chainId }

hc.list(page?, limit?)

List stored records.

Returns: { records, total, pages }

hc.getBillingBalance(walletAddress)

Get testnet credit balance for a wallet.

hc.health()

Check API health.

Returns: { status, version, lastBlock }

hc.storeVault(document)

Store a document in the Permanent Document Vault with rich metadata.

Parameters:

• document.documentType — 'property_deed' | 'stock_certificate' | 'compliance_record' | 'invoice' | 'insurance_policy' | 'ip_registration' | 'forever_receipt' | 'generic'
• document.documentId — your internal document ID
• document.issuerName — issuing party name
• document.subjectName — subject/recipient name
• document.subjectWallet — subject wallet address (optional)
• document.effectiveDate — ISO date string
• document.data — document payload object
• document.metadata — additional metadata (optional)

Returns: { recordId, vaultUrl, verifyUrl, ciDigestHash }

const result = await hc.storeVault({
  documentType: 'property_deed',
  documentId: 'DEED-2026-001',
  issuerName: 'Acme Title Co',
  subjectName: 'John Smith',
  effectiveDate: '2026-06-24',
  data: { parcel: '123-456', address: '123 Main St' },
});
console.log(result.vaultUrl); // https://healchain.org/app/vault.html?id=...

hc.issueForeverReceipt(order)

Issue a permanent, tamper-proof payment receipt.

Parameters:

• order.orderId — your order/transaction ID
• order.total — order total (number)
• order.currency — currency code (default: 'USD')
• order.customerEmail — customer email (optional)
• order.customerWallet — customer wallet (optional)
• order.items — line items [{name, quantity, price}] (optional)
• order.vendorName — your business name (optional)

Returns: { recordId, viewUrl, qrCodeUrl }

const receipt = await hc.issueForeverReceipt({
  orderId: 'ORDER-12345',
  total: 99.00,
  currency: 'USD',
  customerEmail: '[email protected]',
  vendorName: 'Acme Corp',
  items: [{ name: 'Annual Plan', quantity: 1, price: 99.00 }],
});
console.log(receipt.viewUrl); // permanent receipt link

Error Handling

import HealChain, { HealChainError } from '@healchain/sdk';

try {
  const result = await hc.store('my data', { label: 'test' });
} catch (err) {
  if (err instanceof HealChainError) {
    console.error(err.message, err.status, err.code);
  }
}

Supported Chains

Mainnets

| Chain | Chain ID | Identifier | |---|---|---| | Ethereum | 1 | eth-mainnet | | Arbitrum One | 42161 | arbitrum-one | | Base | 8453 | base-mainnet | | Polygon | 137 | polygon | | BNB Chain | 56 | bnb | | Avalanche | 43114 | avalanche |

Testnets

| Chain | Chain ID | Identifier | |---|---|---| | Ethereum Sepolia | 11155111 | sepolia | | Arbitrum Sepolia | 421614 | arbitrum-sepolia | | Base Sepolia | 84532 | base-sepolia | | Optimism Sepolia | 11155420 | optimism-sepolia | | Unichain Sepolia | 1301 | unichain-sepolia | | Avalanche Fuji | 43113 | avalanche-fuji | | And 8 more testnets... | | |

Use chain: 'auto' (default) to let the scoring engine pick the optimal chain.

Chain Constants (v1.2+)

import HealChain, { CHAINS } from '@healchain/sdk';

const hc = new HealChain({ apiKey: 'your-key', chain: CHAINS.ETHEREUM });
// CHAINS.ETHEREUM, CHAINS.ARBITRUM_ONE, CHAINS.BASE, CHAINS.POLYGON,
// CHAINS.BNB, CHAINS.AVALANCHE, CHAINS.AUTO, CHAINS.SEPOLIA ...

License

MIT © HealChain