get_hip4_outcome

Instructions

Implementation Reference

• src/index.ts:1609-1618 (registration)

  Registration of the get_hip4_outcome tool via registerTool helper.

  registerTool(
    "get_hip4_outcome",
    "Get a single HIP-4 outcome by outcome_id. Returns the full Hip4OutcomeAggregate including aggregated_oi (latest both-sides OI snapshot, paired set supply, parity, and currency).",
    { outcome_id: Hip4OutcomeIdParam },
    ObjectOutputSchema,
    async (params) => {
      const result = await hip4Request(`/outcomes/${encodeURIComponent(String(params.outcome_id))}`);
      return formatResponse(result.data);
    }
  );

• src/index.ts:1614-1616 (handler)

  Handler function for get_hip4_outcome: calls the HIP-4 REST API endpoint /outcomes/{outcome_id} via hip4Request, then formats the response.

  async (params) => {
    const result = await hip4Request(`/outcomes/${encodeURIComponent(String(params.outcome_id))}`);
    return formatResponse(result.data);

• src/index.ts:69-71 (schema)

  Input schema param for outcome_id, accepting number or string.

  const Hip4OutcomeIdParam = z
    .union([z.number(), z.string()])
    .describe("HIP-4 outcome_id (integer). Each outcome has two sides: '<10*id>' (Yes) and '<10*id+1>' (No).");

• src/index.ts:139-141 (schema)

  Output schema used by get_hip4_outcome; returns a single data object.

  const ObjectOutputSchema: ZodRawShape = {
    data: z.record(z.unknown()).describe("Result data object"),
  };

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

  Helper function hip4Request that makes authenticated GET requests to the HIP-4 REST API (since the SDK does not yet have a hip4 namespace). Used by get_hip4_outcome to call /outcomes/{outcome_id}.

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