HertzFlow SDK

SDK

About

The HertzFlow SDK is a TypeScript-based SDK developed for interacting with HertzFlow protocol. It provides a comprehensive set of tools and utilities for building decentralized trading applications, managing positions, executing orders, and monitoring real-time market data.

Installation

Using npm

npm install @hertzflow/sdk-v2

Using yarn

yarn add @hertzflow/sdk-v2

Using pnpm

pnpm add @hertzflow/sdk-v2

Getting Started

Basic Configuration

import { HertzFlowSDK } from "@hertzflow/sdk-v2";

const sdk = new HertzFlowSDK({
  chainId: 97,                                       // BSC Testnet
  rpcUrl: "https://data-seed-prebsc-1-s1.binance.org:8545",
  oracleUrl: "https://oracle.hertzflow.com",
  statsUrl: "https://stats.hertzflow.com",
  account: "0xYourWalletAddress",
});

With Custom Viem Clients

import { HertzFlowSDK } from "@hertzflow/sdk-v2";
import { createPublicClient, createWalletClient, http } from "viem";
import { bscTestnet } from "viem/chains";

const publicClient = createPublicClient({
  chain: bscTestnet,
  transport: http("https://data-seed-prebsc-1-s1.binance.org:8545"),
});

const walletClient = createWalletClient({
  chain: bscTestnet,
  transport: http("https://data-seed-prebsc-1-s1.binance.org:8545"),
  account: "0xYourWalletAddress",
});

const sdk = new HertzFlowSDK({
  chainId: 97,
  rpcUrl: "https://data-seed-prebsc-1-s1.binance.org:8545",
  oracleUrl: "https://oracle.hertzflow.com",
  statsUrl: "https://stats.hertzflow.com",
  publicClient,
  walletClient,
});

With WebSocket Support

const sdk = new HertzFlowSDK({
  chainId: 97,
  rpcUrl: "https://data-seed-prebsc-1-s1.binance.org:8545",
  wsRpcUrl: "wss://bsc-testnet.publicnode.com",      // Enable real-time events
  oracleUrl: "https://oracle.hertzflow.com",
  statsUrl: "https://stats.hertzflow.com",
  account: "0xYourWalletAddress",
});

API Reference

Read Methods

Markets

Method

Description

sdk.markets.getMarkets()

Fetch all available trading markets

sdk.markets.getMarketsInfo()

Get comprehensive market data with prices and configs

sdk.markets.getMarketsConfigs(markets)

Fetch market configuration parameters

sdk.markets.getMarketsValues(params)

Get market runtime values (funding rates, pool amounts)

sdk.markets.getDailyVolumes()

Get trading volumes per market

sdk.markets.getTradingInstruments()

Get trading instruments with metadata

Positions

Method

Description

sdk.positions.getPositions(params)

Fetch raw position data for account

sdk.positions.getPositionsInfo(params)

Get enhanced positions with calculated metrics

sdk.positions.getPositionsConstants()

Get system constants (min collateral, max orders)

sdk.positions.getUserReferralInfo()

Get user's referral code and tier info

Tokens

Method

Description

sdk.tokens.getTokensData()

Fetch all available tokens with metadata

sdk.tokens.getTokenRecentPrices()

Get latest token prices from oracle

sdk.tokens.getTokensBalances(account?, tokensList?)

Get user token balances

sdk.tokens.getTokenTotalSupplies(tokenAddresses)

Get total supply of tokens

Orders

Method

Description

sdk.orders.getOrders(params)

Fetch all user orders with filtering

sdk.orders.getOrdersInfo(params)

Get enhanced order data with market info

Trades

Method

Description

sdk.trades.getTradeHistory(params)

Get market trade history

sdk.trades.getUserTradeHistory(params)

Get user's trade history with pagination

Claims

Method

Description

sdk.claim.getClaimableFundingData(markets)

Get claimable funding fees by market

sdk.claim.getClaimableCollaterals(params)

Get claimable price impact rebates

sdk.claim.getClaimHistory(params)

Get claim history with pagination

Utils

Method

Description

sdk.utils.getGasLimits()

Fetch gas limits for all operations

sdk.utils.getGasPrice()

Get current network gas price

sdk.utils.getEstimatedGasFee(type, params)

Estimate gas for operation

sdk.utils.getExecutionFee(type, tokensData, prices, params)

Calculate execution fee

Write Methods

Quick Methods

Method

Description

sdk.orders.long(params)

Quick method to open a long position

sdk.orders.short(params)

Quick method to open a short position

sdk.orders.swap(params)

Quick method to execute a token swap

Full Order Methods

Method

Description

sdk.orders.createIncreaseOrderTxn(params)

Create position increase order

sdk.orders.createDecreaseOrderTxn(params)

Close or reduce position

sdk.orders.createSwapOrderTxn(params)

Execute token swap order

sdk.orders.updateOrderTxn(params)

Modify existing order

sdk.orders.cancelOrdersTxn(orderKeys)

Cancel one or multiple orders

Pool Operations

Method

Description

sdk.orders.createHmDepositTxn(params)

Deposit to HM pool

sdk.orders.createHmWithdrawalTxn(params)

Withdraw from HM pool

sdk.orders.createHlvDepositTxn(params)

Deposit to HLV vault

sdk.orders.createHlvWithdrawalTxn(params)

Withdraw from HLV vault

Token Operations

Method

Description

sdk.orders.createWrapOrUnwrapTxn(params)

Wrap or unwrap native tokens

sdk.allowance.approveToken(tokenAddress, spenderAddress, amount?)

Approve token for spending

sdk.allowance.approveTokenForSyntheticsRouter(tokenAddress, amount?)

Approve for SyntheticsRouter

Claim Operations

Method

Description

sdk.claim.claimFundingFees(params)

Claim funding fees for markets

sdk.claim.claimPriceImpactRebates(params)

Claim price impact rebates

sdk.claim.claimAllRebates(params)

Batch claim funding and rebates

Event Subscriptions

Position Events

sdk.events.subscribePositionIncrease((logs) => {
  console.log("Position increased:", logs);
});

sdk.events.subscribePositionDecrease((logs) => {
  console.log("Position decreased:", logs);
});

Order Events

sdk.events.subscribeOrderCreated((logs) => {
  console.log("Order created:", logs);
});

sdk.events.subscribeOrderExecuted((logs) => {
  console.log("Order executed:", logs);
});

sdk.events.subscribeOrderCancelled((logs) => {
  console.log("Order cancelled:", logs);
});

Deposit/Withdrawal Events

sdk.events.subscribeDepositCreated((logs) => { /* ... */ });
sdk.events.subscribeDepositExecuted((logs) => { /* ... */ });
sdk.events.subscribeWithdrawalCreated((logs) => { /* ... */ });
sdk.events.subscribeWithdrawalExecuted((logs) => { /* ... */ });

Configuration Options

SDK Configuration Interface

interface HertzFlowSdkConfig {
  chainId: ContractsChainId;              // Network ID (97 for BSC Testnet)
  account?: Address;                       // User's wallet address
  oracleUrl: string;                       // Oracle service URL
  rpcUrl: string;                          // RPC endpoint
  wsRpcUrl?: string;                       // WebSocket RPC (optional)
  statsUrl: string;                        // Statistics backend URL
  publicClient?: PublicClient;             // Custom viem public client
  walletClient?: WalletClient;             // Custom viem wallet client
  tokens?: Record<string, Partial<Token>>; // Token overrides
  markets?: Record<string, Partial<MarketSdkConfig>>; // Market overrides
  settings?: {
    uiFeeReceiverAccount?: string;         // UI fee receiver address
    ignoreTimeoutError?: boolean;          // Ignore timeout errors
  };
}

Supported Chains

Chain

Chain ID

Description

BSC Testnet

BNB Smart Chain Testnet

Token Customization

You can override token information:

const sdk = new HertzFlowSDK({
  // ... other config
  tokens: {
    "0xTokenAddress": {
      name: "Custom Token Name",
      symbol: "CTN",
      imageUrl: "https://example.com/token.png",
    },
  },
});

Market Availability

Control which markets are available:

const sdk = new HertzFlowSDK({
  // ... other config
  markets: {
    "0xMarketAddress": {
      isListed: false,  // Hide this market
    },
  },
});

UI Fee Configuration

Set up UI fee receiver:

const sdk = new HertzFlowSDK({
  // ... other config
  settings: {
    uiFeeReceiverAccount: "0xYourFeeReceiverAddress",
  },
});

Usage Examples

Opening a Long Position

import { HertzFlowSDK } from "@hertzflow/sdk-v2";

const sdk = new HertzFlowSDK({
  chainId: 97,
  rpcUrl: "https://data-seed-prebsc-1-s1.binance.org:8545",
  oracleUrl: "https://oracle.hertzflow.com",
  statsUrl: "https://stats.hertzflow.com",
  account: "0xYourWalletAddress",
});

// Get market data and prices
const { marketsInfoData, tokensData } = await sdk.markets.getMarketsInfo();
const pricesData = await sdk.tokens.getTokenRecentPrices();

// Open a long position
const txn = await sdk.orders.long({
  payAmount: 1000000000n,                              // Amount in token decimals
  marketAddress: "0xMarketAddress",
  payTokenAddress: "0xPayTokenAddress",
  collateralTokenAddress: "0xCollateralTokenAddress",
  allowedSlippageBps: 125,                             // 1.25% slippage
  leverage: 50000n,                                    // 5x leverage (4 decimals)
  prices: pricesData,
});

console.log("Transaction:", txn);

Fetching Positions with Metrics

// Get market info first
const { marketsInfoData, tokensData } = await sdk.markets.getMarketsInfo();
const pricesData = await sdk.tokens.getTokenRecentPrices();

// Get positions with full metrics
const positionsInfo = await sdk.positions.getPositionsInfo({
  marketsInfoData,
  tokensData,
  prices: pricesData,
  showPnlInLeverage: true,
});

// Access position data
for (const [key, position] of Object.entries(positionsInfo)) {
  console.log(`Position: ${position.marketInfo.name}`);
  console.log(`  Size: ${position.sizeInUsd}`);
  console.log(`  PnL: ${position.pnl}`);
  console.log(`  Leverage: ${position.leverage}`);
  console.log(`  Liquidation Price: ${position.liquidationPrice}`);
}

Subscribing to Real-Time Events

// Enable WebSocket for real-time events
const sdk = new HertzFlowSDK({
  chainId: 97,
  rpcUrl: "https://data-seed-prebsc-1-s1.binance.org:8545",
  wsRpcUrl: "wss://bsc-testnet.publicnode.com",
  oracleUrl: "https://oracle.hertzflow.com",
  statsUrl: "https://stats.hertzflow.com",
  account: "0xYourWalletAddress",
});

// Subscribe to position events
const unsubscribeIncrease = sdk.events.subscribePositionIncrease((logs) => {
  logs.forEach((log) => {
    console.log("Position increased:", log);
  });
});

const unsubscribeDecrease = sdk.events.subscribePositionDecrease((logs) => {
  logs.forEach((log) => {
    console.log("Position decreased:", log);
  });
});

// Unsubscribe when done
// unsubscribeIncrease();
// unsubscribeDecrease();

Claiming Rewards

// Get claimable data
const markets = await sdk.markets.getMarkets();
const claimableFunding = await sdk.claim.getClaimableFundingData(markets);

// Claim funding fees
if (Object.keys(claimableFunding.claimableFundingFees).length > 0) {
  const txn = await sdk.claim.claimFundingFees({
    marketAddresses: Object.keys(claimableFunding.claimableFundingFees),
    tokenAddresses: Object.values(claimableFunding.claimableFundingFees).flatMap(
      (m) => Object.keys(m)
    ),
  });
  console.log("Claim transaction:", txn);
}

Account Management

Switching Accounts

// Switch to a different account
sdk.setAccount("0xNewWalletAddress");

// This automatically:
// - Updates internal account reference
// - Triggers account-specific event listeners
// - Clears allowance subscriptions

Updating Wallet Client

import { createWalletClient, http } from "viem";
import { bscTestnet } from "viem/chains";

const newWalletClient = createWalletClient({
  chain: bscTestnet,
  transport: http("https://data-seed-prebsc-1-s1.binance.org:8545"),
  account: "0xNewWalletAddress",
});

sdk.setWalletClient(newWalletClient);

Resource Cleanup

Always destroy the SDK when done to clean up resources:

// Clean up all resources
sdk.destroy();

// This:
// - Closes all WebSocket event listeners
// - Cleans up allowance event subscriptions
// - Releases internal references

PreviousLatest Price API NextOverview

Last updated 1 month ago

Good night

hashtagAbout

hashtagInstallation

hashtagUsing npm

hashtagUsing yarn

hashtagUsing pnpm

hashtagGetting Started

hashtagBasic Configuration

hashtagWith Custom Viem Clients

hashtagWith WebSocket Support

hashtagAPI Reference

hashtagRead Methods

hashtagWrite Methods

hashtagEvent Subscriptions

hashtagConfiguration Options

hashtagSDK Configuration Interface

hashtagSupported Chains

hashtagToken Customization

hashtagMarket Availability

hashtagUI Fee Configuration

hashtagUsage Examples

hashtagOpening a Long Position

hashtagFetching Positions with Metrics

hashtagSubscribing to Real-Time Events

hashtagClaiming Rewards

hashtagAccount Management

hashtagSwitching Accounts

hashtagUpdating Wallet Client

hashtagResource Cleanup

About

Installation

Using npm

Using yarn

Using pnpm

Getting Started

Basic Configuration

With Custom Viem Clients

With WebSocket Support

API Reference

Read Methods

Write Methods

Event Subscriptions

Configuration Options

SDK Configuration Interface

Supported Chains

Token Customization

Market Availability

UI Fee Configuration

Usage Examples

Opening a Long Position

Fetching Positions with Metrics

Subscribing to Real-Time Events

Claiming Rewards

Account Management

Switching Accounts

Updating Wallet Client

Resource Cleanup