# Event Log Endpoints
Event log endpoints allow you to query smart contract events with powerful filtering capabilities.
## Table of Contents
- [Get Event Logs by Address](#get-event-logs-by-address)
- [Get Event Logs by Topics](#get-event-logs-by-topics)
- [Get Event Logs by Address and Topics](#get-event-logs-by-address-and-topics)
- [Topic Operators](#topic-operators)
- [Common Event Signatures](#common-event-signatures)
---
## Get Event Logs by Address
Get all event logs emitted by a specific contract address.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `logs` |
| action | Yes | string | Set to `getLogs` |
| address | Yes | string | Contract address |
| fromBlock | No | number | Starting block number (default: 0) |
| toBlock | No | number | Ending block number (default: latest) |
| page | No | number | Page number (default: 1) |
| offset | No | number | Records per page (max 1000, default: 1000) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&fromBlock=18000000&toBlock=18001000&page=1&offset=100&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e",
"0x000000000000000000000000de0b295669a9fd93d5f28d9ec85e40f4cb697bae"
],
"data": "0x00000000000000000000000000000000000000000000000000000000000f4240",
"blockNumber": "0x1130f20",
"timeStamp": "0x656a1234",
"gasPrice": "0x4a817c800",
"gasUsed": "0xfde8",
"logIndex": "0x5",
"transactionHash": "0xabc123...",
"transactionIndex": "0xa"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| address | Contract address that emitted the log |
| topics | Array of indexed event parameters (up to 4 topics) |
| data | Non-indexed event parameters (ABI-encoded) |
| blockNumber | Block number (hex) |
| timeStamp | Block timestamp (hex) |
| gasPrice | Gas price used (hex, Wei) |
| gasUsed | Gas used by transaction (hex) |
| logIndex | Log index within block (hex) |
| transactionHash | Transaction hash |
| transactionIndex | Transaction index within block (hex) |
### Notes
- Maximum **1000 results** per request
- Use pagination for larger result sets
- Block range limit: **5000 blocks** per request
- Topics[0] is always the event signature hash
- Data field contains non-indexed parameters
---
## Get Event Logs by Topics
Get logs filtered by specific topic values (indexed parameters).
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `logs` |
| action | Yes | string | Set to `getLogs` |
| fromBlock | No | number | Starting block number |
| toBlock | No | number | Ending block number |
| topic0 | No | string | Topic 0 (event signature) |
| topic1 | No | string | Topic 1 (first indexed parameter) |
| topic2 | No | string | Topic 2 (second indexed parameter) |
| topic3 | No | string | Topic 3 (third indexed parameter) |
| topic0_1_opr | No | string | Operator between topic0 and topic1 |
| topic1_2_opr | No | string | Operator between topic1 and topic2 |
| topic2_3_opr | No | string | Operator between topic2 and topic3 |
| page | No | number | Page number |
| offset | No | number | Records per page (max 1000) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get all Transfer events (ERC20)
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&fromBlock=18000000&toBlock=18001000&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&page=1&offset=100&apikey=YourApiKey"
```
### Example: Specific Transfer Event
```bash
# Transfer from specific address
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&fromBlock=18000000&toBlock=18001000&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&topic1=0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e&topic0_1_opr=and&apikey=YourApiKey"
```
### Notes
- Topic filtering is powerful for finding specific events
- Topic values must be 32-byte hex strings (0x-prefixed, 64 hex digits)
- Addresses must be padded to 32 bytes: `0x000000000000000000000000{address}`
- Use operators to combine topic filters
---
## Get Event Logs by Address and Topics
Combine address and topic filtering for precise queries.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
Combines all parameters from [address filtering](#get-event-logs-by-address) and [topic filtering](#get-event-logs-by-topics).
### Example Request
```bash
# Get USDC Transfer events from specific address
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&fromBlock=18000000&toBlock=18001000&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&topic1=0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e&topic0_1_opr=and&apikey=YourApiKey"
```
### Notes
- Most precise filtering method
- Combines contract-specific and event-specific filters
- Reduces result set size
- Faster queries
---
## Topic Operators
Topic operators allow you to create complex logical queries.
### Available Operators
| Operator | Description | Example Use Case |
|----------|-------------|------------------|
| `and` | Both conditions must be true | Transfer FROM and TO specific addresses |
| `or` | Either condition can be true | Transfer FROM or TO specific address |
### Operator Syntax
```
topic0_1_opr = and | or
topic1_2_opr = and | or
topic2_3_opr = and | or
```
### Example: AND Operator
```bash
# Transfer FROM 0x742... AND TO 0xde0...
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&fromBlock=18000000&toBlock=18001000&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&topic1=0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e&topic2=0x000000000000000000000000de0b295669a9fd93d5f28d9ec85e40f4cb697bae&topic0_1_opr=and&topic1_2_opr=and&apikey=YourApiKey"
```
### Example: OR Operator
```bash
# Transfer FROM 0x742... OR FROM 0xde0...
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&fromBlock=18000000&toBlock=18001000&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&topic1=0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e&topic2=0x000000000000000000000000de0b295669a9fd93d5f28d9ec85e40f4cb697bae&topic0_1_opr=and&topic1_2_opr=or&apikey=YourApiKey"
```
---
## Common Event Signatures
Event signatures are keccak256 hashes of the event declaration. Here are commonly used events:
### ERC20 Events
#### Transfer
```solidity
event Transfer(address indexed from, address indexed to, uint256 value)
```
**Signature**: `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`
- topic0: Event signature
- topic1: from address (padded)
- topic2: to address (padded)
- data: value (uint256)
#### Approval
```solidity
event Approval(address indexed owner, address indexed spender, uint256 value)
```
**Signature**: `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925`
- topic0: Event signature
- topic1: owner address (padded)
- topic2: spender address (padded)
- data: value (uint256)
### ERC721 Events
#### Transfer
```solidity
event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)
```
**Signature**: `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`
- topic0: Event signature (same as ERC20!)
- topic1: from address (padded)
- topic2: to address (padded)
- topic3: tokenId (padded)
#### Approval
```solidity
event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId)
```
**Signature**: `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925`
#### ApprovalForAll
```solidity
event ApprovalForAll(address indexed owner, address indexed operator, bool approved)
```
**Signature**: `0x17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c31`
### Uniswap V2 Events
#### Swap
```solidity
event Swap(
address indexed sender,
uint256 amount0In,
uint256 amount1In,
uint256 amount0Out,
uint256 amount1Out,
address indexed to
)
```
**Signature**: `0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822`
#### Sync
```solidity
event Sync(uint112 reserve0, uint112 reserve1)
```
**Signature**: `0x1c411e9a96e071241c2f21f7726b17ae89e3cab4c78be50e062b03a9fffbbad1`
### Uniswap V3 Events
#### Swap
```solidity
event Swap(
address indexed sender,
address indexed recipient,
int256 amount0,
int256 amount1,
uint160 sqrtPriceX96,
uint128 liquidity,
int24 tick
)
```
**Signature**: `0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67`
### OpenSea / Seaport Events
#### OrderFulfilled
```solidity
event OrderFulfilled(
bytes32 orderHash,
address indexed offerer,
address indexed zone,
address recipient,
SpentItem[] offer,
ReceivedItem[] consideration
)
```
**Signature**: `0x9d9af8e38d66c62e2c12f0225249fd9d721c54b83f48d9352c97c6cacdcb6f31`
---
## Decoding Log Data
### Understanding Topics
- **topic0**: Always the event signature (keccak256 of event declaration)
- **topic1-3**: Indexed parameters (addresses, token IDs, etc.)
- **data**: Non-indexed parameters (ABI-encoded)
### Example: Decoding ERC20 Transfer
```javascript
// Log result
const log = {
topics: [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e",
"0x000000000000000000000000de0b295669a9fd93d5f28d9ec85e40f4cb697bae"
],
data: "0x00000000000000000000000000000000000000000000000000000000000f4240"
};
// Decode
const from = "0x" + log.topics[1].slice(26); // Remove padding
const to = "0x" + log.topics[2].slice(26);
const value = parseInt(log.data, 16); // 1000000 (1 USDC with 6 decimals)
console.log(`Transfer: ${from} -> ${to}, Amount: ${value / 1e6} USDC`);
```
### Using ethers.js
```javascript
import { ethers } from 'ethers';
// Define event interface
const iface = new ethers.Interface([
"event Transfer(address indexed from, address indexed to, uint256 value)"
]);
// Decode log
const decodedLog = iface.parseLog({
topics: log.topics,
data: log.data
});
console.log(decodedLog.args.from); // from address
console.log(decodedLog.args.to); // to address
console.log(decodedLog.args.value); // value as BigInt
```
---
## Query Optimization Tips
### 1. Limit Block Range
```bash
# Good: 1000 blocks
&fromBlock=18000000&toBlock=18001000
# Avoid: Very large ranges
&fromBlock=0&toBlock=latest
```
### 2. Use Specific Contracts
```bash
# Better performance
&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
# vs. no address filter
```
### 3. Filter by Topics
```bash
# Specific event type
&topic0=0xddf252...
# Specific parameter values
&topic1=0x000000000000000000000000742d35cc...
```
### 4. Pagination
```bash
# Process in chunks
&page=1&offset=1000
&page=2&offset=1000
# etc.
```
---
## Common Use Cases
### Track Token Transfers
```bash
# All USDC transfers in block range
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&fromBlock=18000000&toBlock=18001000&apikey=YourApiKey"
```
### Monitor Specific Address
```bash
# All events involving address (as sender)
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&topic1=0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e&fromBlock=18000000&toBlock=latest&apikey=YourApiKey"
```
### Track DEX Swaps
```bash
# Uniswap V2 swaps
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&topic0=0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822&fromBlock=18000000&toBlock=18001000&apikey=YourApiKey"
```
### NFT Sales Tracking
```bash
# NFT transfers (mints, sales, transfers)
curl "https://api.etherscan.io/v2/api?chainid=1&module=logs&action=getLogs&address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef&fromBlock=18000000&toBlock=18001000&apikey=YourApiKey"
```
---
## Error Codes
| Status | Message | Description |
|--------|---------|-------------|
| 0 | Block range too large | Reduce to max 5000 blocks |
| 0 | Invalid topic format | Use 32-byte hex (0x + 64 hex chars) |
| 0 | Query timeout | Reduce block range or add more filters |
| 0 | Too many results | Use pagination or narrow filters |
## Rate Limits
- Free tier: **5 calls/second**
- Max results per call: **1000**
- Max block range: **5000 blocks**
- Timeout: **10 seconds** per query
## Tools for Event Signatures
### Calculate Event Signature
```javascript
import { ethers } from 'ethers';
const signature = ethers.id("Transfer(address,address,uint256)");
console.log(signature);
// 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
```
### Online Tools
- [Keccak-256 Calculator](https://emn178.github.io/online-tools/keccak_256.html)
- [4byte Directory](https://www.4byte.directory/) - Event signature database
## See Also
- [Account Endpoints](./account-endpoints.md)
- [Contract Endpoints](./contracts-endpoints.md)
- [Solidity Event Documentation](https://docs.soliditylang.org/en/latest/contracts.html#events)
