@hermetica/sdk

A TypeScript SDK for interacting with the Hermetica protocol. Supports transaction generation, claims data retrieval, and protocol info (rates, prices, APYs) across Stacks and Bitcoin blockchains.

Features

• Generate transaction hex for staking, unstaking, and claiming rewards
• Support for both Stacks and Bitcoin blockchains
• USDh/sUSDh supported on Stacks and Bitcoin; hBTC supported on Stacks only
• Claims data retrieval for both chains
• sUSDh and hBTC rate, price, and APY information retrieval
• Configurable API host and affiliate code support

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

For Stacks (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
});

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

Multisig Transactions (Stacks only)

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 |

Note: Multisig is only supported on Stacks. Bitcoin USDh/sUSDh transactions do not support multisig.

For Bitcoin (USDh only)

const stakeResult = await transactionBuilder.generateTransactionHex({
  amount: '94.2', // Amount to stake in BTC
  type: 'stake', // 'stake' | 'unstake' | 'withdraw'
  chain: 'bitcoin',
  protocol: 'USDh', // Only USDh is supported on Bitcoin
  addresses: {
    payment_btc_address: {
      address: '38byQL...', // Your Bitcoin payment address
      pubKey: '0000231...', // Public key for the payment address
      type: 'p2sh' // Address type: p2wpkh, p2sh, etc.
    },
    taproot_btc_address: {
      address: 'bc1pkd...', // Your Taproot address
      pubKey: '023xc0...', // Public key for the Taproot address
      type: 'p2tr'
    }
  },
  satvBFee: 5 // Optional: Fee rate in sat/vB (defaults to highest from mempool)
});

// Response format
{
  status: 'success' | 'failed';
  message: string;
  data: {
    tx_hex: string; // The transaction hex to be signed
    type: 'stake' | 'unstake' | 'withdraw';
    chain: 'bitcoin';
    inputs_to_sign?: {
      [address: string]: number[]; // Input indices that need to be signed
    }
  }
}

Retrieving Claims Data

For Stacks (USDh or hBTC)

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
}

For Bitcoin (USDh only)

const withdrawalsData = await transactionBuilder.getWithdrawalsData({
  chain: 'bitcoin',
  protocol: 'USDh', // Only USDh is supported on Bitcoin
  addresses: {
    payment_btc_address: {
      address: '38byQL...',
      pubKey: '0000231...',
      type: 'p2sh'
    },
    taproot_btc_address: {
      address: 'bc1pkd...',
      pubKey: '023xc0...',
      type: 'p2tr'
    }
  }
});

// Response format
{
  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
}

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
• Bitcoin: Support for USDh staking, unstaking, and claiming rewards with:
  • Payment address (p2sh, p2wpkh)
  • Taproot address (p2tr)

Note: hBTC transactions are only supported on Stacks. Bitcoin chain support is limited to USDh/sUSDh.

Note: Multisig transactions are only supported on Stacks. Bitcoin USDh/sUSDh transactions do not support multisig.

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