Bug: Hyperliquid SPOT API: @notation pairs have misleading/opaque naming

[PrathmeshRanjan]

Hyperliquid SPOT API: @Notation pairs have misleading/opaque naming

The Hyperliquid SPOT API returns pair names using @number notation (e.g., @145, @156, @161), but these names don't match the actual underlying token pairs. This makes it difficult to:

1. Identify which pairs these represent
2. Match SPOT pairs between database storage and API responses
3. Understand what assets are actually being traded

Code to Reproduce

import { Hyperliquid } from '@nktkas/hyperliquid';

const client = new Hyperliquid();

async function investigateSpotPairs() {
  const [spotMeta, spotAssetCtxs] = await client.infoClient.spotMetaAndAssetCtxs();
  
  console.log(`Total SPOT pairs: ${spotMeta.universe.length}`);
  console.log(`Total tokens: ${spotMeta.tokens.length}\n`);
  
  // Show top pairs by volume with actual token names
  const topPairs = spotMeta.universe
    .map((p, idx) => {
      const assetCtx = spotAssetCtxs[idx];
      const baseToken = spotMeta.tokens.find(t => t.index === p.tokens[0]);
      const quoteToken = spotMeta.tokens.find(t => t.index === p.tokens[1]);
      
      return {
        pairName: p.name,              // API returns this
        actualSymbol: `${baseToken?.name}/${quoteToken?.name}`, // What it actually is
        baseAsset: baseToken?.name,
        quoteAsset: quoteToken?.name,
        volume: parseFloat(assetCtx?.dayNtlVlm || '0'),
        price: parseFloat(assetCtx?.midPx || assetCtx?.markPx || '0'),
      };
    })
    .filter(p => p.volume > 0)
    .sort((a, b) => b.volume - a.volume)
    .slice(0, 10);
  
  console.log('Top 10 SPOT pairs by volume:\n');
  topPairs.forEach((p, idx) => {
    console.log(`${idx + 1}. API Name: "${p.pairName}" -> Actual: ${p.actualSymbol}`);
    console.log(`   Price: $${p.price.toLocaleString()}, Volume: $${p.volume.toLocaleString()}\n`);
  });
}

investigateSpotPairs();

Actual Output (as of 2025-12-31)

Top 10 SPOT pairs by volume:

1. API Name: "@145" -> Actual: VORTX/USDC (should be BTC/USDC)
   Price: $88,563.5, Volume: $70,700,244

2. API Name: "@109" -> Actual: WOW/USDC (should be HYPE/USDC)
   Price: $25.828, Volume: $38,796,441

3. API Name: "@156" -> Actual: USOL/USDC (should be ETH/USDC)
   Price: $2,975.05, Volume: $8,648,178

4. API Name: "@161" -> Actual: PRFI/USDC (should be SOL/USDC)
   Price: $125.92, Volume: $6,701,855

5. API Name: "@224" -> Actual: UWLD/USDC
   Price: $0.17588, Volume: $2,882,144

6. API Name: "@246" -> Actual: IZEC/USDC
   Price: $0.99996, Volume: $2,656,106

7. API Name: "@174" -> Actual: ANON/USDC
   Price: $0.999155, Volume: $2,071,988

8. API Name: "@192" -> Actual: ANZ/USDC
   Price: $4,324.6, Volume: $1,988,151

9. API Name: "@170" -> Actual: PEG/USDC
   Price: $0.28535, Volume: $1,977,673

10. API Name: "@155" -> Actual: QUANT/USDC
    Price: $0.998415, Volume: $1,651,996

The Problem

Notice that:

• @145 is actually VORTX/USDC
• @156 is actually USOL/USDC
• @161 is actually PRFI/USDC

The @number notation does not indicate what the underlying assets are.

Environment

• @nktkas/hyperliquid version: 0.25.4 (specified in package.json as ^0.25.4)
• Runtime environment and its version: Bun 1.3.0

[damjankuznar]

@PrathmeshRanjan I'm working on a similar thing myself and I think that the code you have is actually producing the correct results.
For instance, BTC/USDC is actually @142 and not @145. Well, it's actually UBTC/USDC and HL UI has some internal mapping for certain spot assets, such as UBTC (Unit Bitcoin) -> BTC, USOL -> SOL, etc.

[PrathmeshRanjan]

@damjankuznar, you're right, UBTC/USDC is @142, but its price and volume don't correspond to the BTC/USDC spot pair on the UI. On the contrary, the pair VORTX/USDC (@145) does.
@nktkas, please verify.

Output:

Total SPOT pairs: 249

VORTX/USDC
@notation: @145
Tokens: VORTX (204) / USDC (0)
Price: $88055.5
24h Volume: $63,471,922.765
Prev Day Price: $87625.0

UBTC/USDC
@notation: @142
Tokens: UBTC (197) / USDC (0)
Price: $0.00016
24h Volume: $0
Prev Day Price: $0.000059

Code to reproduce:

import * as hl from '@nktkas/hyperliquid';

async function main() {
  const transport = new hl.HttpTransport({ url: 'https://api.hyperliquid.xyz' });
  const infoClient = new hl.InfoClient({ transport });

  const [spotMeta, spotAssetCtxs] = await infoClient.spotMetaAndAssetCtxs();

  console.log(`Total SPOT pairs: ${spotMeta.universe.length}\n`);

  const pairs = ['VORTX/USDC', 'UBTC/USDC'];

  for (const pairName of pairs) {
    const [base, quote] = pairName.split('/');

    const index = spotMeta.universe.findIndex((p) => {
      const baseToken = spotMeta.tokens.find(t => t.index === p.tokens[0]);
      const quoteToken = spotMeta.tokens.find(t => t.index === p.tokens[1]);
      return baseToken?.name === base && quoteToken?.name === quote;
    });

    if (index === -1) {
      console.log(`${pairName} not found\n`);
      continue;
    }

    const pair = spotMeta.universe[index];
    const ctx = spotAssetCtxs[index];
    const baseToken = spotMeta.tokens.find(t => t.index === pair.tokens[0]);
    const quoteToken = spotMeta.tokens.find(t => t.index === pair.tokens[1]);

    console.log(`${pairName}`);
    console.log(`@notation: ${pair.name}`);
    console.log(`Tokens: ${baseToken?.name} (${pair.tokens[0]}) / ${quoteToken?.name} (${pair.tokens[1]})`);
    console.log(`Price: $${ctx?.midPx || 'N/A'}`);
    console.log(`24h Volume: $${parseFloat(ctx?.dayNtlVlm || '0').toLocaleString()}`);
    console.log(`Prev Day Price: $${ctx?.prevDayPx || 'N/A'}\n`);
  }
}

main().catch(console.error);