> 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/api/user-activity-api.md). # User Activity API Returns a wallet's trade and position history — every open/increase/decrease/close/liquidation event with full size, price, fee, referral, and PnL breakdowns. Cursor-paginated. ### Endpoint ``` GET /api/v1/bsc/user/trades ``` Base URL: `https://data-statistics-query.beatnet.htzfl.link` ### Parameters | Name | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `user_address` | string | Yes | Wallet address, 42 chars (`0x` + 40 hex) | | `limit` | number | No | Items per page | | `cursor` | string | No | Pagination cursor. Empty for the first page; pass the cursor returned by the previous response to fetch the next page. | ### Example Request ```bash curl -X GET "https://data-statistics-query.beatnet.htzfl.link/api/v1/bsc/user/trades?cursor=&limit=10&user_address=0xd08889CDA6c09680F9B4C6BADCB102Cb4AB423E8" \ -H "Accept: application/json" ``` ### Example Response ```json { "code": 200, "msg": "", "data": { "items": [ { "tx_hash": "0xb802e8bc9f59e6d21e53dfcbc160ba00228f9ed1c2fe08d2110074bf1e825447", "block_number": 113834914, "log_index": 31, "action_time_ms": 1781668784000, "market": "0xd537CD7D937446442c62B98c10a9c303152F289a", "market_symbol": "BTC/USD", "direction": "short", "is_long": false, "position_mode": "normal", "is_zfp": false, "trade_type": "market", "action_type": "market_decrease", "display_action": "Market Decrease", "is_increase": false, "leverage": "4351830663020.0x", "size_in_usd": "128484034384631847152474185564680", "size_in_tokens": "1675358515388475", "size_delta_usd": "14270000000000000000000000000000", "size_delta_tokens": "186072659759609", "trade_size_usd": "14270000000000000000000000000000", "collateral_token": "0x6335881872FEcab922d1d83c6Bae6E27C5a9209c", "collateral_delta_amount": "0", "execution_price": "65875420455568619", "index_token_price_min": "65809624675859061", "index_token_price_max": "65875467221807894", "position_fee_factor": "500000000000000000000000000", "position_fee_amount": "7145452212940958", "borrowing_fee_amount": "10517480750886936", "funding_fee_amount": "0", "total_cost_amount": "17305660353180847", "referral_code": "0x5445535430320000000000000000000000000000000000000000000000000000", "l1_affiliate": "0x930430832c1f2Ba82C9c4AbF45290Ae89Cfd1bF2", "l2_affiliate": "0x159b89b7c008d45d1EE38d4a481ce328a9abB60C", "referral_trader_discount_amount": "357272610647047", "referral_l1_reward_amount": "714545221294095", "referral_l2_reward_amount": "714545221294095", "pnl_detail": { "initial_collateral_amount": "29524134630614881210", "gross_pnl": "2012376601131246953332627057290", "loss_rebate": "0", "fees": "17637096007537647140463863311", "price_impact": "16844083709843938113825015", "liquidation_fee": "0" }, "loss_rebate_info": { "pending_lr_usd": "879102725551600000000000000000", "actual_rebate_usd": "0" }, "order_key": "0xc6a7b741371e71dd512ce71fb5e7551c95b157f229290c064412f499606e34a5", "position_key": "0x4b9a052197b2fec1643055771a5a0d20b064e086a031f9a9b83c825d9c711ee4", "is_credit_market": false } ] } } ``` ### Key Response Fields **Event identity** | Field | Type | Description | | ---------------------------------------- | ---------------- | ------------------------------------------------------------------- | | `tx_hash` / `block_number` / `log_index` | string / number | On-chain location of the event | | `action_time_ms` | number | Event time (ms epoch) | | `market` / `market_symbol` | string | Market address and symbol | | `action_type` / `display_action` | string | Event type, e.g. `market_increase`, `market_decrease`, `liquidated` | | `trade_type` | string | `market` or `limit` | | `direction` / `is_long` | string / boolean | Position side | | `position_mode` / `is_zfp` | string / boolean | `normal` or Hyper Lev (ZFP) | | `is_increase` | boolean | `true` for opens/increases, `false` for reduces/closes | | `is_credit_market` | boolean | Whether the position uses Credit collateral | **Size & price** | Field | Type | Description | | ------------------------------------------------- | ------ | --------------------------------------------------------------- | | `size_in_usd` / `size_in_tokens` | string | Total position size after the event (USD 1e30 / token decimals) | | `size_delta_usd` / `size_delta_tokens` | string | Size changed by this event | | `collateral_token` / `collateral_delta_amount` | string | Collateral token and amount changed | | `execution_price` | string | Fill price (token-decimal fixed-point) | | `index_token_price_min` / `index_token_price_max` | string | Oracle price band used | | `leverage` | string | Position leverage at the event | **Fees** | Field | Type | Description | | --------------------------------------------- | ------ | --------------------------------------------- | | `position_fee_factor` / `position_fee_amount` | string | Open/close fee rate (1e30) and amount (token) | | `borrowing_fee_amount` / `funding_fee_amount` | string | Accrued borrow and funding fees | | `total_cost_amount` | string | Total cost of the event (token decimals) | **Referral** | Field | Type | Description | | --------------------------------------------------------- | ------ | ---------------------------------- | | `referral_code` | string | Bound referral code (bytes32 hex) | | `l1_affiliate` / `l2_affiliate` | string | L1/L2 referrer addresses | | `referral_trader_discount_amount` | string | Discount credited to the trader | | `referral_l1_reward_amount` / `referral_l2_reward_amount` | string | Rebates accrued to L1/L2 referrers | **PnL & rebate** | Field | Type | Description | | ------------------------------------------------------- | ------ | ----------------------------------------------- | | `pnl_detail.gross_pnl` | string | Directional PnL before fees (USD 1e30) | | `pnl_detail.fees` / `pnl_detail.price_impact` | string | Fees and settled price impact (USD 1e30) | | `pnl_detail.loss_rebate` / `pnl_detail.liquidation_fee` | string | Loss rebate applied and liquidation fee charged | | `loss_rebate_info.pending_lr_usd` | string | Loss rebate accrued but not yet realized | | `loss_rebate_info.actual_rebate_usd` | string | Loss rebate actually paid out at close | {% hint style="info" %} Numeric encoding: `*_usd` and `*_factor` fields are 1e30 fixed-point strings; token amounts (`*_amount`, `size_in_tokens`) use the token's own decimals; prices are token-decimal fixed-point. See the [API overview](/hertzflow-docs/tech-docs/api.md#numeric-encoding). {% endhint %} --- # 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/api/user-activity-api.md?ask=&goal= ``` `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.