get_hip4_orderbook

Instructions

Implementation Reference

• src/index.ts:1621-1635 (handler)

  The handler function for the 'get_hip4_orderbook' tool. It accepts 'coin' and optional 'depth' parameters, normalizes the coin using normalizeHip4Coin, makes a request to /v1/hyperliquid/hip4/orderbook/{coin} via the hip4Request helper, and returns the response.

  registerTool(
    "get_hip4_orderbook",
    "Get the current HIP-4 L2 orderbook snapshot for a coin (e.g. '0'). Bare numeric coins are canonical; legacy '#0' / '%230' forms are also accepted.Returns bids and asks. Note: mark_price for HIP-4 is an implied probability (0..1), not a USD price. Pro+ tier required.",
    {
      coin: Hip4CoinParam,
      depth: DepthParam,
    },
    ObjectOutputSchema,
    async (params) => {
      const q: Record<string, unknown> = {};
      if (params.depth) q.depth = params.depth;
      const result = await hip4Request(`/orderbook/${normalizeHip4Coin(params.coin)}`, q);
      return formatResponse(result.data);
    }
  );

• src/index.ts:1624-1628 (schema)

  Input schema for get_hip4_orderbook: coin (Hip4CoinParam, a Zod string with HIP-4 outcome-market description) and optional depth (DepthParam, number). Output schema is ObjectOutputSchema (single data record).

  {
    coin: Hip4CoinParam,
    depth: DepthParam,
  },
  ObjectOutputSchema,

• src/index.ts:1620-1635 (registration)

  Registration of the 'get_hip4_orderbook' tool via registerTool. Wired to the HIP-4 REST API endpoint /orderbook/{coin} rather than the SDK because the SDK's hip4 namespace was not yet available.

  // HIP-4 Orderbook (current)
  registerTool(
    "get_hip4_orderbook",
    "Get the current HIP-4 L2 orderbook snapshot for a coin (e.g. '0'). Bare numeric coins are canonical; legacy '#0' / '%230' forms are also accepted.Returns bids and asks. Note: mark_price for HIP-4 is an implied probability (0..1), not a USD price. Pro+ tier required.",
    {
      coin: Hip4CoinParam,
      depth: DepthParam,
    },
    ObjectOutputSchema,
    async (params) => {
      const q: Record<string, unknown> = {};
      if (params.depth) q.depth = params.depth;
      const result = await hip4Request(`/orderbook/${normalizeHip4Coin(params.coin)}`, q);
      return formatResponse(result.data);
    }
  );

• src/index.ts:1487-1537 (helper)

  The hip4Request helper function that performs the actual fetch to the HIP-4 REST API. Used by the orderbook handler to make the GET request.

  async function hip4Request(
    path: string,
    query?: Record<string, unknown>
  ): Promise<{ data: unknown; nextCursor?: string }> {
    const url = new URL(`${HIP4_BASE_PATH}${path}`, HIP4_BASE_URL);
    if (query) {
      for (const [k, v] of Object.entries(query)) {
        if (v === undefined || v === null) continue;
        url.searchParams.set(k, String(v));
      }
    }
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      "User-Agent": "0xarchive-mcp/1.9.0",
    };
    if (apiKey) headers["X-API-Key"] = apiKey;
  
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 60000);
    try {
      const response = await fetch(url.toString(), {
        method: "GET",
        headers,
        signal: controller.signal,
      });
      const text = await response.text();
      let body: any;
      try {
        body = text ? JSON.parse(text) : null;
      } catch {
        body = text;
      }
      if (!response.ok) {
        const requestId =
          response.headers.get("x-request-id") || body?.meta?.requestId;
        const message =
          (body && (body.error?.message || body.error || body.message)) ||
          `HTTP ${response.status}`;
        throw new OxArchiveError(message, response.status, requestId ?? undefined);
      }
      if (body && typeof body === "object" && "data" in body) {
        return {
          data: body.data,
          nextCursor: body.meta?.nextCursor,
        };
      }
      return { data: body };
    } finally {
      clearTimeout(timeout);
    }
  }

• src/index.ts:307-314 (helper)

  The normalizeHip4Coin helper function that normalizes HIP-4 coin symbols (e.g., strips '#' or '%23' prefixes, falls back to URL-encoding). Used by the orderbook handler to normalize the coin parameter.

  function normalizeHip4Coin(coin: string): string {
    const trimmed = String(coin).trim();
    if (/^\d+$/.test(trimmed)) return trimmed;
    const stripped = trimmed.replace(/^(#|%23)/i, "");
    if (/^\d+$/.test(stripped)) return stripped;
    // Unknown shape — fall back to URL-encoding the original.
    return encodeURIComponent(trimmed);
  }