get_hip4_prices

Instructions

Implementation Reference

• src/index.ts:1755-1775 (registration)

  Registration of the get_hip4_prices tool via registerTool(). Defines input schema (coin, history params, interval) and output schema (ListOutputSchema). The handler calls hip4Request to fetch price history from the REST API endpoint, then formats the cursor-paginated response.

  // HIP-4 Prices
  registerTool(
    "get_hip4_prices",
    "Get HIP-4 mid-price (implied probability, 0..1) history for a coin (e.g. '0'). Bare numeric coins are canonical; legacy '#0' / '%230' forms are also accepted.Returns timestamped price snapshots over a time range with cursor pagination.",
    {
      coin: Hip4CoinParam,
      ...HistoryParams,
      interval: z
        .enum(["5m", "15m", "30m", "1h", "4h", "1d"])
        .optional()
        .describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'"),
    },
    ListOutputSchema,
    async (params) => {
      const q = buildHistoryQuery(params.start, params.end, params.limit, params.cursor, {
        interval: params.interval,
      });
      const result = await hip4Request(`/prices/${normalizeHip4Coin(params.coin)}`, q);
      return formatCursorResponse(result);
    }
  );

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

  Input schema for the HIP-4 coin parameter, used by get_hip4_prices and other HIP-4 tools.

  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."
    );

• src/index.ts:129-136 (schema)

  Output schema used by get_hip4_prices for paginated list responses.

  const ListOutputSchema: ZodRawShape = {
    records: z.array(z.record(z.unknown())).describe("Array of result records"),
    count: z.number().describe("Total number of records in the full result set"),
    nextCursor: z
      .string()
      .optional()
      .describe("Cursor for next page, if more results available"),
  };

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

  Helper function that makes REST API requests to the 0xArchive HIP-4 endpoints. Used by get_hip4_prices handler to fetch data from /v1/hyperliquid/hip4/prices/{coin}.

  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)

  Normalizes HIP-4 coin symbols (bare numeric, legacy #0, %230) before making API requests. Used by get_hip4_prices handler.

  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);
  }