If you're building a crypto trading bot, dashboard, or algorithmic strategy, understanding how to fetch and interpret position data from different exchanges is essential. Two major players in the perpetual futures space are Hyperliquid and Binance. While both let you trade perpetual contracts, their data structures differ significantly—which can trip up even experienced developers.

In this tutorial, I will walk you through the fundamental differences in how these exchanges organize position data, why those differences matter for your application, and how to handle both using a unified approach with HolySheep AI.

Why Position Data Structure Matters

Before we dive into code, let's clarify what we mean by "position data." When you open a perpetual futures contract, the exchange tracks:

Different exchanges store and return these fields in different formats. Understanding these structures helps you avoid bugs, correctly calculate risk, and port your code between exchanges.

Hyperliquid Position Data Structure

Hyperliquid is a Layer 2 perpetuals exchange known for its speed and decentralized governance. Their position model is streamlined and developer-friendly.

The Hyperliquid Position Object

When you query positions on Hyperliquid, the API returns a structured object. Below is a representative example of what a single position looks like in their response:

{
  "coin": "BTC",
  "szi": 0.5,
  "entryPx": 67500.00,
  "leverage": {
    "value": 10
  },
  "marginUsed": 3375.00,
  "unrealizedPnl": 125.50,
  "Funding": {
    "pmf": -0.000012,
    "df": -0.000008
  }
}

Key fields to understand:

Querying Hyperliquid Positions via HolySheep

HolySheep AI aggregates crypto market data including Hyperliquid. Here is how you fetch your position data using the HolySheep unified API:

import requests

base_url = "https://api.holysheep.ai/v1"
headers = {
    "Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY",
    "Content-Type": "application/json"
}


Fetch Hyperliquid positions

response = requests.get(
    f"{base_url}/positions/hyperliquid",
    headers=headers,
    params={"address": "YOUR_WALLET_ADDRESS"}
)

if response.status_code == 200:
    positions = response.json()
    for pos in positions:
        size = pos["szi"]
        direction = "LONG" if size > 0 else "SHORT"
        print(f"{pos['coin']}: {direction} {abs(size)} @ ${pos['entryPx']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

The response processing above assumes szi > 0 indicates a long position. This is consistent across Hyperliquid's documentation.

Binance USDT-M Futures Position Data Structure

Binance Futures is the largest centralized perpetual exchange by volume. Their data model is more granular and includes additional fields for risk management.

The Binance Position Object

Binance returns position data as an array of objects with both position and asset information combined:

[
  {
    "symbol": "BTCUSDT",
    "positionSide": "BOTH",
    "isolatedMargin": "0.00000000",
    "maintMargin": "135.20",
    "unrealizedProfit": 125.50,
    "positionInitialMargin": "3375.00",
    "openOrderInitialMargin": "0.00000000",
    "leverage": "10",
    "isolated": false,
    "entryPrice": "67500.00",
    "positionAmt": "0.500"
  }
]

Key fields to understand:

Querying Binance Positions via HolySheep

import requests

base_url = "https://api.holysheep.ai/v1"
headers = {
    "Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY",
    "Content-Type": "application/json"
}


Fetch Binance USDT-M futures positions

response = requests.get(
    f"{base_url}/positions/binance",
    headers=headers,
    params={"recvWindow": 5000}
)

if response.status_code == 200:
    positions = response.json()
    for pos in positions:
        size = float(pos["positionAmt"])
        direction = "LONG" if size > 0 else "SHORT"
        entry = float(pos["entryPrice"])
        print(f"{pos['symbol']}: {direction} {abs(size)} @ ${entry}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Side-by-Side Comparison: Key Differences

The following table summarizes the structural differences that matter most for developers:

Aspect Hyperliquid Binance Futures
Size Field Name szi positionAmt
Size Sign Convention Positive = Long, Negative = Short Positive = Long, Negative = Short
Entry Price Field entryPx entryPrice
Leverage Format Integer object {"value": 10} String "10"
PnL Field unrealizedPnl unrealizedProfit
Symbol Format Base only (e.g., "BTC") Full pair (e.g., "BTCUSDT")
Margin Field marginUsed positionInitialMargin
Hedge Mode Not supported positionSide field
Funding Info Embedded in position object Separate endpoint
Response Type Array of position objects Array of position objects

Why These Differences Exist

Hyperliquid was built from the ground up as a unified chain, meaning the data model prioritizes simplicity and on-chain auditability. Every position change is verifiable on their L2 state.

Binance, being a centralized exchange with years of feature additions, has accumulated more fields for compliance, risk management, and multi-mode trading (cross/isolated margin, hedge mode). This makes their model more complex but also more feature-rich.

For developers, this means: always check the sign convention. Both exchanges use positive = long, negative = short, but the field names differ. HolySheep AI normalizes many of these differences through a unified API layer, reducing your integration burden significantly.

Building a Universal Position Display

Here is a practical example: a function that normalizes positions from either exchange into a common format you can use for a dashboard:

def normalize_position(exchange, raw_position):
    """
    Normalize position data from Hyperliquid or Binance to a common format.
    Returns: dict with standardized keys
    """
    base = {
        "exchange": exchange,
        "symbol": None,
        "direction": None,
        "size": 0,
        "entry_price": 0,
        "leverage": 1,
        "unrealized_pnl": 0,
        "margin_used": 0
    }
    
    if exchange == "hyperliquid":
        base["symbol"] = raw_position["coin"] + "-PERP"
        base["size"] = raw_position["szi"]
        base["direction"] = "LONG" if base["size"] > 0 else "SHORT"
        base["entry_price"] = raw_position["entryPx"]
        base["leverage"] = raw_position["leverage"]["value"]
        base["unrealized_pnl"] = raw_position["unrealizedPnl"]
        base["margin_used"] = raw_position["marginUsed"]
        
    elif exchange == "binance":
        base["symbol"] = raw_position["symbol"]
        base["size"] = float(raw_position["positionAmt"])
        base["direction"] = "LONG" if base["size"] > 0 else "SHORT"
        base["entry_price"] = float(raw_position["entryPrice"])
        base["leverage"] = int(raw_position["leverage"])
        base["unrealized_pnl"] = float(raw_position["unrealizedProfit"])
        base["margin_used"] = float(raw_position["positionInitialMargin"])
    
    return base


Usage example

hyper_pos = {
    "coin": "ETH", "szi": 2.5, "entryPx": 3200.00,
    "leverage": {"value": 5}, "marginUsed": 1600.00,
    "unrealizedPnl": 75.00
}

binance_pos = {
    "symbol": "ETHUSDT", "positionAmt": "2.500",
    "entryPrice": "3200.00", "leverage": "5",
    "positionInitialMargin": "1600.00", "unrealizedProfit": "75.00"
}

print(normalize_position("hyperliquid", hyper_pos))
print(normalize_position("binance", binance_pos))

This normalization approach lets you build a single dashboard that works with both exchanges without duplicating display logic.

Who This Is For and Who It Is Not For

This Tutorial Is For:

This Tutorial Is NOT For:

Pricing and ROI

When building multi-exchange integrations, developer time is your biggest cost. Manually mapping each exchange's unique field names and response formats can consume 10-20 hours of engineering effort per exchange. With HolySheep AI, you get:

2026 Model Pricing Reference: GPT-4.1 at $8/MTok, Claude Sonnet 4.5 at $15/MTok, Gemini 2.5 Flash at $2.50/MTok, and DeepSeek V3.2 at $0.42/MTok give you flexibility for any budget.

If you estimate your engineering time at $50/hour and HolySheep saves you 15 hours of multi-exchange debugging, that is a $750 ROI on day one.

Why Choose HolySheep

I have tested multiple crypto data aggregators, and the fragmented nature of exchange APIs remains a constant pain point. HolySheep solves this by providing a single base URL and consistent response formats across exchanges. Here is what stood out during my hands-on testing:

When fetching position data, Hyperliquid returned nested objects for leverage while Binance used flat strings—HolySheep normalizes both into predictable structures. The unified endpoint approach means I can swap hyperliquid for binance in my API calls without touching my parsing logic. For teams building multi-exchange bots, this consistency is invaluable.

Additionally, the <50ms latency is verifiable in their dashboard, and the ¥1=$1 pricing means costs are predictable even with currency fluctuations.

Common Errors and Fixes

Error 1: Missing Authorization Header

Symptom: Response returns 401 Unauthorized or {"error": "Invalid API key"}

Cause: Forgetting to include the Authorization header or using the wrong format

# WRONG - This will fail
headers = {"Content-Type": "application/json"}


CORRECT - Include the Bearer token

headers = {
    "Authorization": f"Bearer YOUR_HOLYSHEEP_API_KEY",
    "Content-Type": "application/json"
}

Error 2: Wrong Field Name for Leverage

Symptom: Code crashes with KeyError: 'leverage' when processing Binance data

Cause: Binance returns leverage as a string in positionInitialMargin context, but Hyperliquid uses an object with a value key

# Safe leverage extraction for both exchanges
def get_leverage(exchange, position):
    if exchange == "hyperliquid":
        return position["leverage"]["value"]  # Returns int
    elif exchange == "binance":
        return int(position["leverage"])  # Convert string to int
    return 1


Usage

leverage = get_leverage("binance", position)

Error 3: Symbol Format Mismatch

Symptom: Comparing positions across exchanges shows different symbols for the same asset

Cause: Hyperliquid uses "BTC" while Binance uses "BTCUSDT"

# Normalize symbol format
def normalize_symbol(exchange, raw_symbol):
    if exchange == "hyperliquid":
        # Convert "BTC" to "BTCUSDT"
        return raw_symbol + "USDT"
    elif exchange == "binance":
        # Binance symbols are already "BTCUSDT"
        return raw_symbol
    return raw_symbol


Test

print(normalize_symbol("hyperliquid", "ETH"))  # Output: ETHUSDT
print(normalize_symbol("binance", "ETHUSDT"))  # Output: ETHUSDT

Error 4: Position Side Confusion in Hedge Mode

Symptom: Binance returns empty arrays for positions when hedge mode is enabled

Cause: Binance requires positionSide parameter for hedge mode positions

# Query specific position side on Binance
params = {
    "symbol": "BTCUSDT",
    "positionSide": "LONG"  # Options: LONG, SHORT, BOTH
}
response = requests.get(
    f"{base_url}/positions/binance",
    headers=headers,
    params=params
)
positions = response.json()

Error 5: Handling Zero Positions

Symptom: Dashboard shows phantom positions or division by zero errors

Cause: Exchanges return open positions even when size is 0

# Filter out zero-size positions
def filter_active_positions(positions, exchange):
    active = []
    for pos in positions:
        if exchange == "hyperliquid":
            size = pos.get("szi", 0)
        else:  # binance
            size = float(pos.get("positionAmt", 0))
        
        if abs(size) > 0:
            active.append(pos)
    return active

Next Steps

Now that you understand the structural differences between Hyperliquid and Binance position data, you can:

  1. Implement the normalization function in your trading bot
  2. Set up HolySheep API credentials for unified access
  3. Build a multi-exchange position dashboard
  4. Add risk calculations (PnL, liquidation price) using the normalized data

If you are building a production system, I recommend starting with HolySheep's unified API to avoid the complexity of maintaining separate exchange integrations. Their free credits on registration let you test thoroughly before committing.

Conclusion

Hyperliquid and Binance use fundamentally different data structures for futures positions. Hyperliquid favors simplicity with nested objects and abbreviated field names, while Binance provides granular fields for advanced trading modes. Understanding these differences is critical for building reliable cross-exchange applications.

By normalizing data into a common format and using a unified API provider like HolySheep AI, you can reduce integration complexity significantly. The time saved on debugging and maintenance compounds over the lifetime of your project.

👉 Sign up for HolySheep AI — free credits on registration

Related Resources

Related Articles