live_long_short_ratio

Instructions

Implementation Reference

• src/index.ts:30-38 (registration)

  The tool name 'live_long_short_ratio' is listed in the FREE_TIER_TOOLS set, marking it as a free tier tool available without an API key.

  const FREE_TIER_TOOLS = new Set([
    'pulse_global_stats',
    'pulse_market_overview',
    'list_markets',
    'market_price',
    'market_orderbook',
    'pulse_most_traded_coins',
    'live_long_short_ratio',
  ]);

• src/index.ts:684-708 (handler)

  The main handler for the 'live_long_short_ratio' tool. It registers the tool with server.registerTool, defines the input schema (useToonFormat, optional coin, optional hours), and the async handler function. The handler has three modes: 1) if 'hours' is provided, calls /live/long-short/history for historical data; 2) if 'coin' is provided (without hours), calls /live/coins/{coin}/long-short for per-coin ratio; 3) otherwise calls /live/long-short for the global ratio.

  // TOOL 20: Long/Short Ratio                         [FREE]
  // ══════════════════════════════════════════════════════════
  if (shouldRegister("live_long_short_ratio")) server.registerTool(
    "live_long_short_ratio",
    {
      description: "Get long/short ratio data. Without a coin, returns the global ratio across all Hyperliquid. With a coin, returns that specific pair's ratio. Optionally include historical data over the last N hours.",
      inputSchema: {
        useToonFormat: useToonFormatSchema,
        coin: z.string().optional().describe("Coin symbol (e.g. BTC, ETH). For builder dex: prefix:COIN (e.g. xyz:SILVER). Omit for global ratio."),
        hours: z.number().min(1).max(168).optional().describe("Include historical data for the last N hours (max 168 = 7 days)"),
      },
    },
    async ({ useToonFormat, coin, hours }) => {
      if (hours) {
        // Historical mode
        const params: Record<string, string> = { hours: String(hours) };
        if (coin) params.coin = normalizeCoin(coin);
        return toolResult(await callAPI(useToonFormat, "/live/long-short/history", params));
      }
      if (coin) {
        return toolResult(await callAPI(useToonFormat, `/live/coins/${normalizeCoin(coin)}/long-short`));
      }
      return toolResult(await callAPI(useToonFormat, "/live/long-short"));
    }
  );

• src/index.ts:689-695 (schema)

  Input schema for the live_long_short_ratio tool. Accepts an optional 'coin' symbol (string) and an optional 'hours' parameter (1-168) to include historical data.

    description: "Get long/short ratio data. Without a coin, returns the global ratio across all Hyperliquid. With a coin, returns that specific pair's ratio. Optionally include historical data over the last N hours.",
    inputSchema: {
      useToonFormat: useToonFormatSchema,
      coin: z.string().optional().describe("Coin symbol (e.g. BTC, ETH). For builder dex: prefix:COIN (e.g. xyz:SILVER). Omit for global ratio."),
      hours: z.number().min(1).max(168).optional().describe("Include historical data for the last N hours (max 168 = 7 days)"),
    },
  },

• src/index.ts:19-28 (registration)

  Duplicate registration entry for 'live_long_short_ratio' in the built/compiled index.js FREE_TIER_TOOLS set.

  const API_URL = process.env.COINVERSAA_API_URL || "https://api.coinversa.ai";
  const BASE = `${API_URL}/api/public/v1`;
  const REQUEST_TIMEOUT_MS = 30_000;
  const MAX_RETRIES = 2;
  const RETRY_DELAY_MS = 1_000;
  
  // Free tier tools — available without an API key (IP-rate-limited on the backend).
  // Must match prod's FREE_TIER_ROUTES allowlist in apiKeyAuth.ts — any mismatch
  // means users hit 401s on tools the MCP advertises as keyless.
  // The cross-market asset tools (list_assets, list_asset, pulse_cross_market_asset)

• src/index.ts:485-507 (handler)

  Compiled handler for the 'live_long_short_ratio' tool in build/index.js, identical logic to the source.

  if (shouldRegister("pulse_recent_trades")) server.registerTool(
    "pulse_recent_trades",
    {
      description: "Get the biggest trades on Hyperliquid in the last N minutes/hours. Returns trades sorted by absolute PnL — the largest movers. Use this to see what's happening right now on the exchange.",
      inputSchema: {
        useToonFormat: useToonFormatSchema,
        since: sinceSchema.default("10m"),
        limit: z.number().min(1).max(100).default(20).describe("Number of trades to return"),
        coin: z.string().optional().describe("Filter by coin symbol (e.g. BTC, ETH, SOL). For builder dex: prefix:COIN (e.g. xyz:SILVER)"),
      },
    },
    async ({ useToonFormat, since, limit, coin }) => {
      const params: Record<string, string> = { since, limit: String(limit) };
      if (coin) params.coin = normalizeCoin(coin);
      return toolResult(await callAPI(useToonFormat, "/pulse/trades/recent", params));
    }
  );
  
  // ══════════════════════════════════════════════════════════
  // TOOL 12: Trader Recent Trades
  // ══════════════════════════════════════════════════════════
  if (shouldRegister("pulse_trader_trades")) server.registerTool(
    "pulse_trader_trades",