Lookup Whale Wallet

Instructions

Implementation Reference

• src/tools/whales.ts:114-136 (handler)

  The handler function for the lookup_whale tool. It accepts an address, calls apiGet to /api/v1/whales/:address, handles 404/errors, and returns wallet detail JSON.

  async ({ address }) => {
    const res = await apiGet<{ dataset: string; data: Record<string, unknown> }>(
      `/api/v1/whales/${encodeURIComponent(address)}`,
    );
  
    if (!res.ok) {
      const msg =
        res.status === 404
          ? `Whale wallet ${address} not found.`
          : `API error (${res.status}): ${JSON.stringify(res.data)}`;
      return {
        content: [{ type: "text" as const, text: msg }],
        isError: res.status !== 404,
      };
    }
  
    const warn = stalenessWarning(res);
    return {
      content: [
        { type: "text" as const, text: `${warn}${JSON.stringify(res.data.data, null, 2)}` },
      ],
    };
  },

• src/tools/whales.ts:100-113 (schema)

  Registration call for lookup_whale including title, description, and inputSchema (zod string for address).

  server.registerTool(
    "lookup_whale",
    {
      title: "Lookup Whale Wallet",
      description:
        "Get full detail for a single whale wallet by address. Returns balance history, " +
        "token holdings, recent transactions, and PnL metrics. " +
        "Cost: $0.02 per query. Source: On-chain analytics.",
      inputSchema: {
        address: z
          .string()
          .describe("Wallet address (e.g. 0x...)"),
      },
    },

• src/tools/whales.ts:100-137 (registration)

  The server.registerTool('lookup_whale', ...) call that registers the tool with the MCP server.

  server.registerTool(
    "lookup_whale",
    {
      title: "Lookup Whale Wallet",
      description:
        "Get full detail for a single whale wallet by address. Returns balance history, " +
        "token holdings, recent transactions, and PnL metrics. " +
        "Cost: $0.02 per query. Source: On-chain analytics.",
      inputSchema: {
        address: z
          .string()
          .describe("Wallet address (e.g. 0x...)"),
      },
    },
    async ({ address }) => {
      const res = await apiGet<{ dataset: string; data: Record<string, unknown> }>(
        `/api/v1/whales/${encodeURIComponent(address)}`,
      );
  
      if (!res.ok) {
        const msg =
          res.status === 404
            ? `Whale wallet ${address} not found.`
            : `API error (${res.status}): ${JSON.stringify(res.data)}`;
        return {
          content: [{ type: "text" as const, text: msg }],
          isError: res.status !== 404,
        };
      }
  
      const warn = stalenessWarning(res);
      return {
        content: [
          { type: "text" as const, text: `${warn}${JSON.stringify(res.data.data, null, 2)}` },
        ],
      };
    },
  );

• src/index.ts:49-59 (registration)

  The registerWhaleTools(server) call in the main server setup that wires up all whale tools including lookup_whale.

  registerWhaleTools(server);
  registerLabelTools(server);
  registerHolderTools(server);
  registerDexTools(server);
  registerContractTools(server);
  registerPmTools(server);
  registerPmArbTools(server);
  registerPmResolutionTools(server);
  registerEconTools(server);
  registerPmMicroTools(server);

• src/client.ts:34-41 (helper)

  The stalenessWarning helper used inside the handler to prepend a stale-data warning if applicable.

  /** Build a staleness warning string if the data is stale, or empty string. */
  export function stalenessWarning(res: ApiResponse): string {
    if (!res.stale) return "";
    const parts = ["[STALE DATA]"];
    if (res.lastUpdated) parts.push(`Last updated: ${res.lastUpdated}`);
    if (res.ageSeconds != null) parts.push(`Age: ${res.ageSeconds}s`);
    return parts.join(" ") + "\n\n";
  }