get_hip4_order_flow

Instructions

Implementation Reference

• src/index.ts:1803-1826 (registration)

  Registration of the 'get_hip4_order_flow' tool via server.registerTool. Sets name, description, input schema (coin, history params, interval), output schema, and handler.

  // HIP-4 Order Flow
  registerTool(
    "get_hip4_order_flow",
    "Get HIP-4 order flow aggregation (Pro+ tier) for a coin (e.g. '0'). Bare numeric coins are canonical; legacy '#0' / '%230' forms are also accepted.Returns time-bucketed order placement, cancellation, and fill metrics.",
    {
      coin: Hip4CoinParam,
      ...HistoryParams,
      interval: z
        .enum(["1m", "5m", "15m", "30m", "1h", "4h", "1d"])
        .optional()
        .describe("Aggregation interval (default '1h')"),
    },
    ListOutputSchema,
    async (params) => {
      const q = buildHistoryQuery(params.start, params.end, params.limit, params.cursor, {
        interval: params.interval,
      });
      const result = await hip4Request(
        `/orders/${normalizeHip4Coin(params.coin)}/flow`,
        q
      );
      return formatCursorResponse(result);
    }
  );

• src/index.ts:1816-1825 (handler)

  Handler function for get_hip4_order_flow. Builds query parameters from start/end/limit/cursor/interval, calls hip4Request to GET /orders/{coin}/flow, and formats the cursor-paginated response.

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

• src/index.ts:1539-1559 (helper)

  buildHistoryQuery helper used by the handler to construct time range, limit, cursor, and extra query parameters for HIP-4 API calls.

  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:1487-1537 (helper)

  hip4Request helper function used by the handler to make authenticated GET requests to the HIP-4 REST API endpoint.

  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:1807-1815 (schema)

  Input schema for get_hip4_order_flow: coin (Hip4CoinParam), start, end, limit, cursor (HistoryParams), and interval (1m-1d enum). Output is ListOutputSchema.

  {
    coin: Hip4CoinParam,
    ...HistoryParams,
    interval: z
      .enum(["1m", "5m", "15m", "30m", "1h", "4h", "1d"])
      .optional()
      .describe("Aggregation interval (default '1h')"),
  },
  ListOutputSchema,