Overview

The HertzFlow SDK is a comprehensive TypeScript SDK designed for interacting with the HertzFlow protocol on BNB Smart Chain.

The HertzFlow SDK is a comprehensive TypeScript SDK designed for interacting with the HertzFlow protocol on BNB Smart Chain. It provides a complete trading infrastructure with support for positions, orders, markets, tokens, and various trading operations.

Features

Core Trading Features

• Position Management: Open, close, and manage leveraged long/short positions with full PnL tracking

• Order Management: Create, update, and cancel market/limit orders with support for stop-loss and take-profit

• Token Swaps: Execute token swaps with automatic route finding and slippage protection

• Pool Operations: Deposit and withdraw from HM pools and HLV vaults

Data & Analytics

• Market Data: Fetch comprehensive market information including configs, values, and daily volumes

• Position Analytics: Calculate PnL, leverage, liquidation prices, and fees in real-time

• Price Feeds: Access real-time token prices from integrated oracle services

• Trade History: Query historical trades with pagination and filtering

Real-Time Events

• WebSocket Integration: Subscribe to real-time position, order, and deposit/withdrawal events

• Event Filtering: Filter events by type and account

• Automatic Reconnection: Handles connection drops gracefully

Developer Experience

• TypeScript First: Full TypeScript support with comprehensive type definitions

• Modular Architecture: Clean separation of concerns with dedicated modules

• Custom Clients: Support for custom viem public and wallet clients

• Flexible Configuration: Override tokens, markets, and other settings

Architecture

HertzFlowSDK
├── markets        # Market data and configurations
├── positions      # Position management and analytics
├── orders         # Order creation and management
├── tokens         # Token data and balances
├── trades         # Trade history
├── events         # Real-time event subscriptions
├── claim          # Reward claiming operations
├── allowance      # Token approval management
├── accounts       # Account-specific data
├── oracle         # Price oracle integration
└── utils          # Gas and fee utilities

Technology Stack

• Language: TypeScript 5.4+

• Runtime: Node.js 18.0+

• Build System: TypeScript Compiler (tsc)

• Module Formats: ESM and CommonJS

• Web3 Library: viem

Supported Networks

Network	Chain ID	Status
BSC Testnet	97	Testnet

Smart Contracts

The SDK interacts with 50+ smart contracts including:

Core Contracts

• ExchangeRouter: Main entry point for trading operations

• SyntheticsRouter: Handles synthetic asset operations

• DataStore: On-chain data storage

• EventEmitter: Event emission for tracking

Vault Contracts

• OrderVault: Order collateral management

• DepositVault: Deposit handling

• WithdrawalVault: Withdrawal processing

Reader Contracts

• SyntheticsReader: Read operations for synthetics

• ReaderV2: General-purpose read operations

• HlvReader: HLV vault reading

Pool Contracts

• HlvRouter: HLV vault operations

Key Capabilities

1. Real-Time Event Streaming

WebSocket-based monitoring for positions, orders, deposits, and withdrawals.

2. Complex Fee Calculations

Automatic calculation of execution fees, position fees, UI fees, and referral discounts.

3. Advanced Swap Routing

Graph-based path finding for optimal token swap routes.

4. Leverage Trading

Full support for leveraged long/short positions with liquidation price calculations.

5. Pool Operations

HM and HLV vault deposits and withdrawals with execution fee handling.

6. Batch Operations

Multicall support for efficient RPC usage and reduced latency.

7. Referral System

Built-in referral code tracking and discount calculations.

8. Token Approvals

Permit support with subscription monitoring for approval events.

Use Cases

Trading Platforms

Build full-featured perpetual trading interfaces with the SDK's comprehensive trading APIs.

Portfolio Trackers

Fetch and display user positions, PnL, and trade history across markets.

Trading Bots

Automate trading strategies with order management and event subscriptions.

Analytics Dashboards

Access market data, volumes, and funding rates for analytics applications.

License

MIT License