get_hip3_instruments

Instructions

Implementation Reference

• src/index.ts:636-641 (registration)

  Registration of the 'get_hip3_instruments' tool using the registerInstrumentsTool helper. It delegates to api().hyperliquid.hip3.instruments.list().

  // 16. HIP-3 Instruments
  registerInstrumentsTool(
    "get_hip3_instruments",
    "List all available HIP-3 builder perp instruments on Hyperliquid. HIP-3 symbols are CASE-SENSITIVE (e.g. 'km:US500', 'km:TSLA'). Use this to discover valid symbols before querying HIP-3 data.",
    () => api().hyperliquid.hip3.instruments.list()
  );

• src/index.ts:361-369 (handler)

  Handler helper: registerInstrumentsTool wraps the SDK call and formats the response. This is the actual handler invoked when the tool runs.

  function registerInstrumentsTool(
    name: string,
    description: string,
    sdkCall: () => Promise<unknown[]>
  ): void {
    registerTool(name, description, {}, ListOutputSchema, async () => {
      const data = await sdkCall();
      return formatResponse(data);
    });

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

  Output schema (ListOutputSchema) used by get_hip3_instruments. Defines the shape: records array, count, and optional nextCursor.

  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:328-370 (helper)

  Core registration helper: registerTool wraps server.registerTool with API key guard and error handling. Used by registerInstrumentsTool (which registers get_hip3_instruments).

  function registerTool(
    name: string,
    description: string,
    inputSchema: ZodRawShape,
    outputSchema: ZodRawShape,
    handler: (params: any) => Promise<McpContent>
  ): void {
    server.registerTool(
      name,
      {
        description,
        inputSchema,
        outputSchema,
        annotations: TOOL_ANNOTATIONS,
      },
      async (params: any) => {
        if (!client) {
          return {
            content: [{ type: "text" as const, text: MISSING_KEY_MESSAGE }],
            isError: true,
          };
        }
        try {
          return await handler(params);
        } catch (err) {
          const error = err instanceof OxArchiveError ? err : new OxArchiveError(String(err), 500);
          return formatError(error);
        }
      }
    );
  }
  
  // Pattern 1: Instrument list (no params)
  function registerInstrumentsTool(
    name: string,
    description: string,
    sdkCall: () => Promise<unknown[]>
  ): void {
    registerTool(name, description, {}, ListOutputSchema, async () => {
      const data = await sdkCall();
      return formatResponse(data);
    });
  }