get_events
Retrieve blockchain event logs by specifying network, contract addresses, and topic filters. Access detailed on-chain activity data for analysis and monitoring purposes.
Instructions
Fetches event logs for a given network and filter criteria
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | Yes | List of contract addresses to filter events | |
| fromBlock | No | Block number to start fetching logs from | |
| network | Yes | The blockchain network (e.g., "ethereum", "base") | |
| optionalTopics | No | Optional additional topics | |
| toBlock | No | Block number to stop fetching logs at | |
| topic | Yes | Primary topic to filter events |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"addresses": {
"description": "List of contract addresses to filter events",
"items": {
"type": "string"
},
"type": "array"
},
"fromBlock": {
"description": "Block number to start fetching logs from",
"type": "number"
},
"network": {
"description": "The blockchain network (e.g., \"ethereum\", \"base\")",
"type": "string"
},
"optionalTopics": {
"description": "Optional additional topics",
"items": {
"type": [
"string",
"null"
]
},
"type": "array"
},
"toBlock": {
"description": "Block number to stop fetching logs at",
"type": "number"
},
"topic": {
"description": "Primary topic to filter events",
"type": "string"
}
},
"required": [
"network",
"addresses",
"topic"
],
"type": "object"
}
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)}], }; }