@hermetica/sdk

A TypeScript SDK for interacting with the Hermetica protocol. Supports Stacks transaction generation (with optional sponsored-tx mode), claims data retrieval, and protocol info (rates, prices, APYs).

📖 Full integration guide: see docs/ — concepts, step-machine pattern, per-flow walkthroughs, contract registry, and machine-readable artefacts.

Features

• Generate Stacks transaction hex for staking, unstaking, and claiming rewards (USDh and hBTC)
• Sponsored transactions — let an affiliate pay the STX fee on the user's behalf (great for BTC-native users)
• Multisig support on Stacks (Asigna)
• Claims data retrieval
• sUSDh and hBTC rate, price, and APY information retrieval
• Configurable API host and affiliate code support

Bitcoin tx generation has been removed. The SDK's Bitcoin path served the USDh ↔ sUSDh on Runes flow, which was sunset on 2026-05-15. The SDK no longer builds Bitcoin transactions. (hBTC ↔ BTC has always relied on the external sBTC protocol for bridging — see the docs/hbtc/ walkthroughs.)

Installation

npm install @hermetica/sdk

Configuration

The library can be configured with the following options:

const config = {
  // Optional: Custom API host (defaults to https://app.hermetica.fi)
  HOST: string;
  // Optional: Your Hermetica affiliate code
  AFFILIATE_CODE: string;
};

Usage

Initialization

import { TransactionBuilder } from '@hermetica/sdk';

const transactionBuilder = new TransactionBuilder({
  HOST: 'CUSTOM_HERMETICA_API', // optional
  AFFILIATE_CODE: 'YOUR_AFFILIATE_CODE' // optional
});

Generating Transactions (Stacks)

generateTransactionHex builds a signable Stacks contract-call hex for stake, unstake, or withdraw on USDh or hBTC.

const stakeResult = await transactionBuilder.generateTransactionHex({
  amount: '94.2', // Amount to stake
  type: 'stake', // 'stake' | 'unstake' | 'withdraw'
  chain: 'stacks',
  protocol: 'USDh', // 'USDh' | 'hBTC'
  public_key: '923xcv2...', // Your Stacks public key
  sponsored: false // Optional, default false. See "Sponsored transactions" below.
});

// Response format
{
  status: 'success' | 'failed';
  message: string;
  data: {
    tx_hex: string; // The transaction hex to be signed
    type: 'stake' | 'unstake' | 'withdraw';
    chain: 'stacks';
  }
}

Multisig (Stacks)

For multisig wallets (e.g., Asigna), pass comma-separated public keys and the signing threshold:

const stakeResult = await transactionBuilder.generateTransactionHex({
  amount: '100',
  type: 'stake',
  chain: 'stacks',
  protocol: 'USDh',
  public_key: 'pubKey1,pubKey2,pubKey3', // Comma-separated signer public keys
  threshold: 2 // 2-of-3 multisig (required signatures)
});

| Parameter | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------ | | public_key | string | Yes | Single key for standard wallets, or comma-separated keys for multisig | | threshold | number | No | Number of required signatures. Defaults to 1. Only used when public_key contains multiple keys |

Sponsored transactions

Set sponsored: true to receive a tx_hex built with Stacks Sponsored auth. The user signs the origin via their wallet; your fee-payer principal then calls sponsorTransaction(...) from @stacks/transactions to add the sponsor spending condition and broadcasts. Useful for BTC-native users who don't hold STX.

import {
  deserializeTransaction,
  sponsorTransaction,
  broadcastTransaction
} from '@stacks/transactions';

const result = await transactionBuilder.generateTransactionHex({
  amount: '0.01',
  type: 'stake',
  chain: 'stacks',
  protocol: 'hBTC',
  public_key: USER_STACKS_PUBKEY,
  sponsored: true // affiliate covers the STX fee for the user
});

// 1. User signs the origin via their wallet (sponsored mode is transparent to most Stacks wallets).
const signedOriginHex = await stacksWallet.signTransaction(result.data.tx_hex);

// 2. Your fee-payer finalizes the sponsor side.
const sponsoredTx = await sponsorTransaction({
  transaction: deserializeTransaction(signedOriginHex),
  sponsorPrivateKey: AFFILIATE_FEE_PAYER_KEY,
  network: stacksNetwork
});

// 3. Broadcast.
const { txid } = await broadcastTransaction({ transaction: sponsoredTx, network: stacksNetwork });

| Parameter | Type | Required | Description | | ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | sponsored | boolean | No | Defaults to false. When true, the returned tx_hex is built with Stacks Sponsored auth and the fee-payer must finalize it. |

Notes

• Hermetica never holds your fee-payer key — sponsorship is finalized client-side.
• Each sponsor must manage its own STX nonce across concurrent sponsorships.
• If the sponsor broadcast fails (insufficient STX, network error), the origin signature is wasted — re-issue generateTransactionHex({ ..., sponsored: true }) and re-prompt the user.

Retrieving Claims Data (Stacks)

const withdrawalsData = await transactionBuilder.getWithdrawalsData({
  chain: 'stacks',
  protocol: 'USDh', // 'USDh' | 'hBTC'
  public_key: '923xcv2...' // Your Stacks public key
});

// Response formats
{
  total_to_claim: number; // Total amount of tokens currently available to claim
  next_amount_to_unlock: number; // Amount of tokens that will be unlocked in the next unlock period
  next_claim_timestamp: number; // The timestamp in ms at which the next amount will become claimable
  last_claim_timestamp: number; // The timestamp in ms at which the last unstake request will be fully unlocked
}

getWithdrawalsData is Stacks-only at both the type and runtime level — its signature accepts StacksTransactionParams only, and the server returns an error for chain: 'bitcoin'.

The claims data response provides information about:

• Currently claimable amounts
• Future unlock amounts
• Timestamps for tracking unlock periods
• This information is useful for displaying countdown timers, progress bars, or other UI elements related to the staking lifecycle

Retrieving hBTC Rate

Get the current hBTC share price rate:

const hbtcRate = await transactionBuilder.gethBTCRate();

// Returns: number — The hBTC share price rate

Retrieving hBTC Price

Get the current hBTC price in USD:

const hbtcPrice = await transactionBuilder.gethBTCPrice();

// Returns: number — The hBTC price in USD

Retrieving hBTC APY

Get the current hBTC APY (Annual Percentage Yield):

const hbtcApy = await transactionBuilder.gethBTCApy({
  range: '7d' // Optional: Time range for APY calculation ('7d', '30d', '90d', or '365d')
});

// Returns: number — The current hBTC APY percentage

Retrieving hBTC Remaining Capacity

Get the remaining BTC deposit capacity for the hBTC vault:

const remainingCapacity = await transactionBuilder.gethBTCRemainingCapacity();

// Returns: number — The remaining BTC room available for deposits into the hBTC vault

Retrieving sUSDh Rate

Get the current sUSDh rate:

const susdhRate = await transactionBuilder.getsUSDhRate();

// Returns: number — The rate of USDh per sUSDh

Retrieving sUSDh APY

Get the current sUSDh APY (Annual Percentage Yield):

const susdhApy = await transactionBuilder.getsUSDhApy({
  range: '7d' // Optional: Time range for APY calculation ('7d', '30d', '90d', or '365d')
});

// Returns: number — The current sUSDh APY percentage

The APY functions support different time ranges to get historical or current yield data.

Retrieving USDh TVL

Get the current USDh total value locked in USD:

const usdhTvl = await transactionBuilder.getUsdhTvl();

// Response format
{
  tvl_usd: string; // TVL in USD
}

Retrieving hBTC TVL

Get the current hBTC total value locked in USD and BTC:

const hbtcTvl = await transactionBuilder.getHbtcTvl();

// Response format
{
  tvl_usd: string; // TVL in USD
  tvl_btc: string; // TVL in BTC
}

Supported Blockchains

• Stacks — full support for USDh and hBTC staking, unstaking, and claiming rewards. Single-sig and multisig (Asigna). Optional sponsored transactions.

Bitcoin tx generation has been removed. The SDK's Bitcoin path served USDh ↔ sUSDh on Runes, which was sunset on 2026-05-15. hBTC ↔ BTC has always been external to the SDK — bridging is handled by the sBTC protocol (see docs/hbtc/stake-bitcoin.md and docs/hbtc/unstake-bitcoin.md).

Transaction Types

• stake: Lock your tokens in the protocol to start earning rewards
• unstake: Initiate the withdrawal process for your staked tokens (requires waiting period)
• withdraw: Collect your available rewards and/or unlocked tokens after the waiting period

Error Handling

The library throws errors in the following cases:

• Invalid configuration
• Insufficient funds
• Invalid address format
• Network errors
• Invalid transaction parameters

Example error handling:

try {
  const result = await transactionBuilder.generateTransactionHex({
    // ... transaction parameters
  });
} catch (error) {
  console.error('Transaction generation failed:', error.message);
}

License

GPL-3.0