get_hip4_orderbook_history

Instructions

Implementation Reference

• src/index.ts:1637-1657 (registration)

  Registration of the 'get_hip4_orderbook_history' tool via registerTool(). It uses Hip4CoinParam for coin input, HistoryParams for time range, and DepthParam for optional depth. The handler builds query params via buildHistoryQuery() and calls hip4Request() against the REST API endpoint '/orderbook/{coin}/history'.

  // HIP-4 Orderbook History
  registerTool(
    "get_hip4_orderbook_history",
    "Get historical HIP-4 L2 orderbook snapshots for a coin (e.g. '0'). Bare numeric coins are canonical; legacy '#0' / '%230' forms are also accepted.Returns L2 snapshots over a time range. Pro+ tier required.",
    {
      coin: Hip4CoinParam,
      ...HistoryParams,
      depth: DepthParam,
    },
    ListOutputSchema,
    async (params) => {
      const q = buildHistoryQuery(params.start, params.end, params.limit, params.cursor, {
        depth: params.depth,
      });
      const result = await hip4Request(
        `/orderbook/${normalizeHip4Coin(params.coin)}/history`,
        q
      );
      return formatCursorResponse(result);
    }
  );

• src/index.ts:1647-1656 (handler)

  The handler function for get_hip4_orderbook_history. It calls buildHistoryQuery() to construct time-range/limit/cursor/depth params, then makes a GET request to `/orderbook/{coin}/history` via hip4Request(), and formats the response via formatCursorResponse().

  async (params) => {
    const q = buildHistoryQuery(params.start, params.end, params.limit, params.cursor, {
      depth: params.depth,
    });
    const result = await hip4Request(
      `/orderbook/${normalizeHip4Coin(params.coin)}/history`,
      q
    );
    return formatCursorResponse(result);
  }

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

  hip4Request() is the helper that makes authenticated GET requests to the HIP-4 REST API (api.0xarchive.io) with the X-API-Key header. It handles 60s timeout, JSON parsing, error handling including OxArchiveError generation, and returns { data, nextCursor } objects.

  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:1539-1559 (helper)

  buildHistoryQuery() helper constructs the query parameters for paginated history endpoints. It resolves start/end timestamps via resolveTimeRange(), applies default limit=100, adds cursor if present, and merges extra parameters (like depth).

  function buildHistoryQuery(
    start?: number | string,
    end?: number | string,
    limit?: number,
    cursor?: string,
    extra?: Record<string, unknown>
  ): Record<string, unknown> {
    const range = resolveTimeRange(start, end);
    const q: Record<string, unknown> = {
      start: range.start,
      end: range.end,
      limit: resolveLimit(limit),
    };
    if (cursor) q.cursor = cursor;
    if (extra) {
      for (const [k, v] of Object.entries(extra)) {
        if (v !== undefined) q[k] = v;
      }
    }
    return q;
  }

• src/index.ts:63-67 (schema)

  Hip4CoinParam: Zod schema for HIP-4 coin symbols. Accepts bare numeric form (e.g., '0'), or legacy '#0' / '%230' forms.

  const Hip4CoinParam = z
    .string()
    .describe(
      "HIP-4 outcome-market coin symbol. Canonical form is the bare numeric '<10*outcome_id + side>' (e.g. '0' for outcome 0 Yes, '1' for outcome 0 No, '10' for outcome 1 Yes). The legacy '#0' and '%230' forms are also accepted. Use get_hip4_instruments to list all."
    );