Fix: Tealstreet Hyperliquid Vault Shows 0 Balance After Linking

If your Tealstreet terminal displays a zero balance after linking a Hyperliquid vault, the conflict stems from an address mismatch between your Externally Owned Account (EOA) master wallet and the dedicated Vault contract address. On Hyperliquid, vaults are independent smart contracts; providing your master wallet’s API key without specifying the vault’s unique contract identifier will result in an empty data return. To resolve this, ensure you are using the specific Vault address (0x…) in the Tealstreet “Vault Address” field rather than your primary trading address.

Architectural Context: L1 State Machine and the webData2 Stream

Hyperliquid operates as a purpose-built Layer 1 blockchain using the Tendermint BFT consensus engine. Unlike general-purpose chains, Hyperliquid’s state machine is optimized specifically for high-throughput perpetual trading. This optimization introduces a specialized data structure for Vaults.

Vaults as Sub-Account Contract Shards

On Hyperliquid, a Vault is not simply a folder in your wallet; it is a discrete entity with its own state on the L1 ledger. When you “join” a vault or create one, the protocol deploys a logic shard that manages positions, collateral, and margin independently of the participant’s EOA.

The API layer utilizes the webData2 WebSocket subscription to provide real-time updates to terminals like Tealstreet. This stream is “user-scoped.” If you initialize the stream with your EOA address, the Hyperliquid indexer filters the L1 state for entries where user == EOA. Since vault positions are recorded under user == VaultAddress, the stream correctly returns zero for the EOA’s specific vault-shard. To bridge this, Tealstreet must explicitly include the vaultAddress parameter in its info requests to the Hyperliquid JSON-RPC or WebSocket gateway.

The Role of L1 Action Signing

Every action taken within a vault—whether it’s an order placement or a leverage adjustment—must be signed by an authorized Signer. For vaults, the protocol checks the userToMultiSigSigners mapping. If your Tealstreet API key is derived from an EOA that is not explicitly authorized as a signer for that specific Vault contract, the L1 will reject the signature, and the frontend will fail to sync the balance matrix, defaulting to 0. This is a common failure point when traders rotate API keys without re-authorizing the new key’s public point on the vault’s access control list (ACL).

Production-Grade Prevention: Vault API Monitoring and Signer Audits

For institutional quant desks, relying on a visual terminal to verify vault health is insufficient. A production-grade setup requires programmatic monitoring of the vault’s state and authorization layer.

1. Automated Signer Verification Manual

Before deploying a new API key to Tealstreet, you should execute a verification script to ensure the key’s EOA has the necessary permissions. This prevents the “Zero Balance” error before it manifests in the trading UI.

Verification Workflow:

1. Query the info endpoint with type vaultDetails.
2. Extract the authorizedSigners array.
3. Cross-reference the signer address with the public key used to generate the Tealstreet API credential.

2. Python-Based Vault Health Monitor

The following script provides a template for a background service that monitors vault balance synchronization and alerts on “Zero Balance” anomalies:

import requests
import json
import time

class HyperliquidVaultMonitor:
    def __init__(self, vault_addr, rpc_url="https://api.hyperliquid.xyz/info"):
        self.vault_addr = vault_addr
        self.rpc_url = rpc_url

    def get_vault_state(self):
        payload = {
            "type": "vaultDetails",
            "vaultAddress": self.vault_addr
        }
        try:
            response = requests.post(self.rpc_url, json=payload)
            data = response.json()
            
            # Extract Margin Summary
            summary = data.get('summary', {})
            account_value = float(summary.get('accountValue', 0))
            
            if account_value <= 0:
                self.trigger_alert("ZERO_BALANCE_DETECTED", f"Vault {self.vault_addr} reporting 0 equity.")
            
            return data
        except Exception as e:
            self.trigger_alert("SYNC_FAILURE", str(e))

    def trigger_alert(self, code, message):
        print(f"CRITICAL: [{code}] {message}")
        # Integration point for PagerDuty or Slack Webhooks

# Usage
monitor = HyperliquidVaultMonitor("0xYOUR_VAULT_ADDRESS")
while True:
    monitor.get_vault_state()
    time.sleep(60) # Poll every minute

3. API Credential Schema for Tealstreet

To ensure successful linking, your environment configuration should follow this strict schema:

Advanced FAQ Layer

Q1: Why can I trade on the Hyperliquid DEX but not on Tealstreet?

This is usually due to CORS or IP restrictions on your API key. When you use the DEX, you are signing transactions via your browser extension (MetaMask/Rabbit). When you use Tealstreet, you are using an API key that may have specific “IP Whitelisting” enabled. If Tealstreet’s servers are not on your whitelist, the API will return a 403 Forbidden error, which the terminal often displays as a “0 Balance” sync error.

Q2: How does the “Sub-Account” feature in Hyperliquid affect Vault linking?

Hyperliquid recently introduced sub-accounts. A Vault is distinct from a Sub-Account. A sub-account is owned by your EOA and shares your API key context. A Vault is an external contract. If you mistakenly try to link a Vault using the “Sub-Account” field in Tealstreet, the mapping will fail. Always use the “Vault Address” field specifically for contract-based pools.

Q3: Does the webData2 stream support multiple vaults simultaneously?

The standard webData2 stream is optimized for a single user context. If you are managing multiple vaults, Tealstreet initializes separate WebSocket connections for each vaultAddress. If you hit a connection limit, some vaults may fail to load, resulting in intermittent zero balances. Ensure your “Max Connections” setting in Tealstreet is sufficient for your vault portfolio.