get_events

Instructions

Implementation Reference

• src/operations/events.ts:57-118 (handler)

  The core handler function that fetches event logs from the Bankless API using the provided parameters.

  /**
   * Fetches event logs for a given network and filter criteria.
   */
  export async function getEvents(
      network: string,
      addresses: string[],
      topic: string,
      optionalTopics: (string | null)[] = [],
      fromBlock?: number,
      toBlock?: number
  ): Promise<EthLog> {
      const token = process.env.BANKLESS_API_TOKEN;
  
      if (!token) {
          throw new BanklessAuthenticationError('BANKLESS_API_TOKEN environment variable is not set');
      }
  
      const endpoint = `${BASE_URL}/chains/${network}/events/logs`;
  
      try {
          const response = await axios.post(
              endpoint,
              {
                  addresses,
                  topic,
                  optionalTopics: optionalTopics || [],
                  fromBlock,
                  toBlock,
                  fetchAll: false,
              },
              {
                  headers: {
                      'Content-Type': 'application/json',
                      'X-BANKLESS-TOKEN': `${token}`
                  }
              }
          );
  
          return response.data;
      } catch (error) {
          if (axios.isAxiosError(error)) {
              const statusCode = error.response?.status || 'unknown';
              const errorMessage = error.response?.data?.message || error.message;
  
              if (statusCode === 401 || statusCode === 403) {
                  throw new BanklessAuthenticationError(`Authentication Failed: ${errorMessage}`);
              } else if (statusCode === 404) {
                  throw new BanklessResourceNotFoundError(`Not Found: ${errorMessage}`);
              } else if (statusCode === 422) {
                  throw new BanklessValidationError(`Validation Error: ${errorMessage}`, error.response?.data);
              } else if (statusCode === 429) {
                  // Extract reset timestamp or default to 60 seconds from now
                  const resetAt = new Date();
                  resetAt.setSeconds(resetAt.getSeconds() + 60);
                  throw new BanklessRateLimitError(`Rate Limit Exceeded: ${errorMessage}`, resetAt);
              }
  
              throw new Error(`Bankless API Error (${statusCode}): ${errorMessage}`);
          }
          throw new Error(`Failed to fetch event logs: ${error instanceof Error ? error.message : String(error)}`);
      }
  }

• src/operations/events.ts:14-21 (schema)

  Zod schema defining the input validation for the get_events tool.

  export const GetEventLogsSchema = z.object({
      network: z.string().describe('The blockchain network (e.g., "ethereum", "base")'),
      addresses: z.array(z.string()).describe('List of contract addresses to filter events'),
      topic: z.string().describe('Primary topic to filter events'),
      optionalTopics: z.array(z.string().nullable()).optional().describe('Optional additional topics'),
      fromBlock: z.number().optional().describe("Block number to start fetching logs from"),
      toBlock: z.number().optional().describe("Block number to stop fetching logs at")
  });

• src/index.ts:100-103 (registration)

  Registration of the get_events tool in the MCP server's list of tools, referencing the input schema.

      name: "get_events",
      description: "Fetches event logs for a given network and filter criteria",
      inputSchema: zodToJsonSchema(events.GetEventLogsSchema),
  },

• src/index.ts:192-205 (handler)

  Dispatch handler in the MCP server that parses arguments and calls the getEvents implementation.

  case "get_events": {
      const args = events.GetEventLogsSchema.parse(request.params.arguments);
      const result = await events.getEvents(
          args.network,
          args.addresses,
          args.topic,
          args.optionalTopics,
          args.fromBlock,
          args.toBlock
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }