Find smart contract events
portal_evm_query_logsRetrieve EVM event logs filtered by contract address, topic signature, or common event name, with optional inline decoding and earliest/latest scanning for targeted lookups.
Instructions
Query raw EVM logs with address/topic filters, common event aliases, earliest/latest scanning, and optional inline decoding.
COMMON USER ASKS:
Recent USDC Transfer logs
First recent USDC Transfer log
Latest ERC721/pass mint ID and tx hash
FIRST CHOICE FOR:
NFT or ERC721 mint lookups such as latest pass minted, token ID, and mint transaction hash
contract event questions where the user needs exact event evidence rather than wallet or transaction summaries
WHEN TO USE:
You need event logs filtered by contract or topic signature.
You want decoded log hints while still keeping the raw log shape available.
You want the first or last matching event in a bounded block/time window.
You want common event names such as transfer, approval, swap, mint, or burn instead of remembering topic0 hashes.
You need the latest ERC721/pass mint in a bounded deployment/recent window: filter Transfer events with topic1 as the zero address, use scan_order=latest, limit=1, and decode=true to expose decoded_log.decoded.token_id plus transaction_hash.
DON'T USE:
You only want token transfers, which are easier with the token-transfer tool.
EXAMPLES:
Recent USDC Transfer logs: {"network":"base-mainnet","timeframe":"1h","token_symbols":["USDC"],"event":"transfer","limit":20}
First recent USDC Transfer log: {"network":"base-mainnet","timeframe":"1h","token_symbols":["USDC"],"event":"transfer","scan_order":"earliest","limit":1}
Latest ERC721/pass mint ID and tx hash: {"network":"base-mainnet","from_block":46020000,"to_block":46100000,"addresses":["0xE4E70FdF2Fc1147a7f35c4c5de88E6BeA63eeAfA"],"event":"transfer","topic1":["0x0000000000000000000000000000000000000000000000000000000000000000"],"scan_order":"latest","decode":true,"include_transaction":true,"limit":1}
Decode logs inline: {"network":"ethereum-mainnet","timeframe":"1h","topic0":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"],"decode":true,"limit":10}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| event | No | Common event alias or topic0 hash. Examples: "transfer", "approval", "swap", "sync", "deposit", "withdrawal". Merges with topic0. | |
| limit | No | Max logs to return (default: 20, max: 200). Note: Lower default for MCP to reduce context usage. | |
| cursor | No | Continuation cursor from a previous response | |
| decode | No | Decode known log signatures inline when topics/data are available | |
| topic0 | No | Event signatures (topic0). E.g., Transfer = 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef | |
| topic1 | No | Topic1 filter (often: from address in Transfer, indexed parameter 1) | |
| topic2 | No | Topic2 filter (often: to address in Transfer, indexed parameter 2) | |
| topic3 | No | Topic3 filter (indexed parameter 3, chain-specific) | |
| network | No | Network name or alias. Optional when continuing with cursor. | |
| to_block | No | Ending block number. RECOMMENDED: <10k blocks for fast (<1s) responses. Larger ranges may be slow or timeout. | |
| addresses | No | Contract addresses to filter (e.g., ['0xUSDC...', '0xDAI...']). IMPORTANT: Always include this or topics for fast queries. | |
| timeframe | No | Natural time range such as '5m', '1h', '24h', '7d', or 'past 30 minutes'. Alternative to from_block/to_block. | |
| from_block | No | Starting block number (use this OR timeframe) | |
| scan_order | No | Which side of the block window to scan first. Use earliest for first-event questions. | latest |
| field_preset | No | Field preset: 'minimal' (address+topic0+block, ~80% smaller), 'standard' (all topics+timestamp), 'full' (includes raw data hex, largest). Use 'minimal' to reduce context usage. | standard |
| to_timestamp | No | Ending timestamp. Accepts Unix seconds, Unix milliseconds, ISO datetime, or relative input like "now". | |
| token_symbols | No | Token symbols to resolve via open token-list data and merge into addresses, e.g. ["USDC"]. | |
| finalized_only | No | Only query finalized blocks | |
| from_timestamp | No | Starting timestamp. Accepts Unix seconds, Unix milliseconds, ISO datetime, or relative input like "1h ago". | |
| max_scan_blocks | No | Maximum blocks to inspect for bounded earliest/latest scans. Sparse latest searches default to 25,000 blocks to stay within MCP request timeouts; raise only when deeper coverage is worth the added latency. | |
| response_format | No | Response format: defaults to 'compact' for chat-friendly output, or stays 'full' when inline transaction context is requested. Use 'summary' for counting or categorizing. | |
| include_transaction | No | Include parent transaction data | |
| include_transaction_logs | No | Include all logs from parent transactions | |
| max_token_symbol_matches | No | Maximum token-list matches to include per token symbol. Use addresses for deterministic single-contract filters. | |
| include_transaction_traces | No | Include traces for parent transactions |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _ui | No | Optional chart, table, and follow-up presentation metadata. | |
| _llm | No | Hints that help an AI client locate the primary evidence. | |
| _meta | No | Network, block range, timing, and row-count metadata. | |
| error | No | Structured failure details when the tool cannot complete the request. | |
| items | No | Primary result rows when the tool returns a list. | |
| value | No | Primary result when the tool returns a scalar value. | |
| answer | No | Concise answer grounded in the returned blockchain data. | |
| _notice | No | Important limitation or truncation notice. | |
| display | No | Plain-language labels for presenting the result. | |
| _notices | No | Important limitations or truncation notices. | |
| _summary | No | Human-readable summary of the result. | |
| _coverage | No | Completeness of the requested window and result set. | |
| _evidence | No | Replayable arguments, exact-data digest, row count, and completeness receipt. | |
| _ordering | No | Ordering guarantees for the returned data. | |
| _execution | No | Bounded execution and scan details. | |
| _freshness | No | Freshness and finality information for the returned data. | |
| next_steps | No | Safe follow-up actions and continuation guidance. | |
| _pagination | No | Pagination state and an optional continuation cursor. | |
| investigation | No | Evidence paths, useful pivots, and result limitations. | |
| pipes_handoff | No | Optional SQD Pipes guidance for custom data needs. | |
| _tool_contract | No | Tool identity, intent, and supported blockchain families. |