> For the complete documentation index, see [llms.txt](https://hertzflow.gitbook.io/hertzflow-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hertzflow.gitbook.io/hertzflow-docs/tech-docs/hertzflow-sdk/overview.md).

# Overview

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hertzflow.gitbook.io/hertzflow-docs/tech-docs/hertzflow-sdk/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.