Find Ethereum and Base transactions
portal_evm_query_transactionsRetrieve raw EVM transactions by sender, recipient, method, token, or time range. Include logs, traces, and state diffs, or rank by value, gas used, and gas price for transaction investigations.
Instructions
Query raw EVM transactions with optional logs, traces, state-diff context, and evidence pivots for transaction-level investigations.
COMMON USER ASKS:
Recent Base transactions
Filter by sender
First EIP-2930 transaction from Berlin fork
WHEN TO USE:
You need raw transaction records on an EVM network.
You want chain-specific transaction fields or include flags that convenience tools do not expose.
You need exact transaction evidence for an investigation, including sender, receiver, transaction hash, logs, traces, or failed calls.
You need to find the first transaction matching a raw field condition such as transaction type 0x1 from a known block.
You need top-N raw transactions ranked by value, gas used, or effective gas price.
You need top senders or receivers from a bounded transaction window.
You want common method names such as transfer, approve, deposit, or withdraw instead of remembering sighashes.
You want calls to a token contract by symbol, such as transfer calls to USDC, without hardcoding token addresses.
DON'T USE:
You only need a quick recent feed or wallet-level summary.
EXAMPLES:
Recent Base transactions: {"network":"base-mainnet","timeframe":"1h","limit":20}
Filter by sender: {"network":"ethereum-mainnet","timeframe":"6h","from_addresses":["0xabc..."],"limit":20}
First EIP-2930 transaction from Berlin fork: {"network":"ethereum-mainnet","from_block":12244000,"transaction_type":"0x1","scan_order":"earliest","limit":1,"field_preset":"minimal"}
Largest recent calls to a resolved token contract: {"network":"base-mainnet","timeframe":"1h","to_token_symbols":["USDC"],"method":"transfer","order_by":"gas_used_desc","limit":5}
Top senders by transaction count: {"network":"base-mainnet","timeframe":"1h","aggregate_by":"sender","aggregate_metric":"count","limit":10}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max transactions (default: 20, max: 200). Note: Lower default for MCP to reduce context usage. | |
| cursor | No | Continuation cursor from a previous response | |
| method | No | FILTER: Common EVM method alias or 4-byte sighash. Examples: "transfer", "approve", "transferFrom", "deposit", "withdraw". Merges with sighash. | |
| network | No | Network name or alias. Optional when continuing with cursor. | |
| sighash | No | FILTER: Function sighash (4-byte hex, e.g., '0xa9059cbb' for transfer). Optional if limit <=100. | |
| order_by | No | Optional ranking for top-N questions. Use value_desc, gas_used_desc, or effective_gas_price_desc. | chronological |
| to_block | No | Ending block number. RECOMMENDED: <5k blocks for fast (<500ms) responses. Larger ranges may be slow. | |
| timeframe | No | Natural time range such as '5m', '1h', '24h', '7d', or 'past 30 minutes'. Alternative to from_block/to_block. Large ranges are allowed with a low limit (<=100). | |
| from_block | No | Starting block number (use this OR timeframe). Large ranges OK with low limit (<=100). | |
| last_nonce | No | Maximum nonce | |
| scan_order | No | Which side of the block window to scan first. Normal previews default to latest; transaction_type searches default to earliest, so "first tx type 0x1 from block N" scans forward from from_block. | |
| first_nonce | No | Minimum nonce | |
| aggregate_by | No | Optional bounded aggregation for top sender/receiver questions. Returns ranked address rows instead of raw transactions. | |
| field_preset | No | Field preset: 'minimal' (from/to/value+block, ~70% smaller), 'standard' (hash+gas+timestamp), 'full' (includes input data hex, largest). Use 'minimal' to reduce context usage. | standard |
| include_logs | No | Include logs emitted by transactions | |
| min_gas_used | No | FILTER/RANKING: Minimum receipt gasUsed. Accepts decimal or hex string. | |
| to_addresses | No | FILTER: Recipient addresses (typically contracts being called, or wallets receiving ETH). Optional if limit <=100. | |
| to_timestamp | No | Ending timestamp. Accepts Unix seconds, Unix milliseconds, ISO datetime, or relative input like "now". | |
| min_value_wei | No | FILTER/RANKING: Minimum native token value in wei. Accepts decimal or hex string. | |
| finalized_only | No | Only query finalized blocks | |
| from_addresses | No | FILTER: Sender addresses (wallets or contracts that initiated the transaction). Optional if limit <=100. | |
| from_timestamp | No | Starting timestamp. Accepts Unix seconds, Unix milliseconds, ISO datetime, or relative input like "1h ago". | |
| include_traces | No | Include traces for transactions | |
| max_scan_blocks | No | Safety cap for first/last/ranked client-side scans. Default: min(window, 10000 blocks). | |
| response_format | No | Response format: defaults to 'compact' for chat-friendly output, or stays 'full' when inline logs, traces, or state diffs are requested. Use 'summary' for counting or profiling. | |
| aggregate_metric | No | Metric used with aggregate_by. count ranks by tx count; value by total native value; gas_used by total gas used; effective_gas_price by max effective gas price. | count |
| to_token_symbols | No | Resolve token symbols via open token-list data and merge them into to_addresses, e.g. transfer/approve calls to USDC. | |
| transaction_type | No | FILTER: EVM transaction type. Accepts decimal or hex strings such as 0, 1, 2, "0x0", "0x1", "0x2". Applied client-side while streaming Portal results; use with scan_order="earliest" and from_block to find the first typed transaction. | |
| contract_creation | No | FILTER: true returns contract-creation transactions; false excludes them. Useful for "first contract creation from this wallet". | |
| include_l2_fields | No | Include L2-specific fields | |
| from_token_symbols | No | Resolve token symbols via open token-list data and merge them into from_addresses. Rare, but useful for token-contract-originated transactions. | |
| transaction_status | No | FILTER: Transaction receipt status. Use "success"/1 or "failed"/0 for failed/reverted transaction searches. | |
| include_state_diffs | No | Include state diffs caused by transactions | |
| max_token_symbol_matches | No | Maximum token-list matches to include per token symbol. Use from_addresses/to_addresses for deterministic single-contract filters. | |
| min_effective_gas_price_wei | No | FILTER/RANKING: Minimum effectiveGasPrice in wei. Accepts decimal or hex string. |
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. |