portal_evm_query_logs
Query EVM event logs filtered by contract address, topic signatures, or event aliases. Supports earliest or latest scan order and optional inline decoding.
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 | Time range (e.g., '24h', '7d'). Alternative to from_block/to_block. Supported: 1h, 6h, 12h, 24h, 3d, 7d, 14d, 30d | |
| 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". | |
| 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 |