> 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

Architecture and capabilities of the HertzFlow TypeScript SDK for BNB Smart Chain.

`@hertzflow/sdk-v2` is the TypeScript integration layer for the HertzFlow protocol on BNB Smart Chain. It combines contract reads and writes, HertzFlow oracle prices, transaction simulation, and derived trading calculations behind a `viem`-based interface.

## Supported Environments

| Environment             | Chain ID | Use                             |
| ----------------------- | -------: | ------------------------------- |
| BNB Smart Chain Testnet |     `97` | HertzFlow protocol integrations |
| BNB Smart Chain         |     `56` | HertzFlow protocol integrations |

The package requires Node.js 18 or later and publishes ESM, CommonJS, and TypeScript declaration builds.

## Architecture

```
HertzFlowSDK
├── markets       Market discovery, configuration, and live values
├── tokens        Token metadata, balances, and normalized prices
├── positions     Positions and derived PnL, leverage, and liquidation data
├── orders        Order reads, writes, and position collateral management
├── externalSwap  Peach quotes for internal USD increase orders
├── liquidity     HzLP and HzV deposit and withdrawal transactions
├── allowance     ERC-20 approvals
├── oracle        HertzFlow price reads
└── utils         Gas, execution-fee, and UI-fee helpers
```

The SDK creates public and wallet clients when custom `viem` clients are not supplied. Read operations use the public client. Write operations simulate and submit through the wallet client.

## Core Capabilities

### Trading

* Read markets, tokens, prices, positions, and orders.
* Enrich raw contract data with market metadata and derived values.
* Create market and limit increase orders, decrease orders, and SL/TP updates.
* Combine a Peach payment-token swap, internal USD mint, and increase order in one multicall.
* Add or remove position collateral.
* Estimate gas and protocol execution fees before submission.

### Liquidity

* Deposit into and withdraw from HzLP markets.
* Deposit into and withdraw from HzV vaults.
* Split HzV transactions across market allocations.
* Support HertzFlow internal USD wrappers during order and liquidity composition.

## Data Flow

```
HertzFlow contracts ─┐
Oracle service ──────┼─> SDK modules ─> typed raw data ─> derived trading data
Token configuration ─┘                 └> simulated/signed transactions
```

On-chain reads remain the source for protocol state such as markets, positions, orders, configuration, balances, and allowances. The oracle service supplies current prices. Token metadata comes from the SDK's built-in configuration and can be merged with configured static overrides or async metadata for newly listed tokens. Consumers can keep those layers separate or merge them with helpers such as `markets.mergeMarketsInfo()`.

## 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.