Make your first Portal request to access raw EVM blockchain data in under 5 minutes. No setup required—just HTTP requests.
What You’ll Build
In this quickstart, you’ll:
- Make a simple Portal request using curl (no installation required)
- Query recent Ethereum blocks
- Filter event logs from a smart contract
This guide uses the Public Portal endpoint, which is free and
rate-limited. Perfect for getting started.
Step 1: Your First Request
Let’s query the last 1,000 blocks from Ethereum mainnet. Copy and paste this command:
curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \
-H 'Content-Type: application/json' \
-d '{
"type": "evm",
"fromBlock": 18000000,
"toBlock": 18001000,
"fields": {
"block": {
"number": true,
"timestamp": true,
"gasUsed": true
}
}
}'
You should see a stream of JSON objects, one per block, showing block numbers,
timestamps, and gas usage.
Try it yourself with the interactive query interface below:
First, install the client:npm install @subsquid/portal-client
import { DataSource } from "@subsquid/portal-client";
const dataSource = new DataSource({
network: "ethereum-mainnet",
});
const blocks = await dataSource.getBlocks({
from: 18000000,
to: 18001000,
fields: {
block: {
number: true,
timestamp: true,
gasUsed: true,
},
},
});
console.log(`Retrieved ${blocks.length} blocks`);
blocks.forEach((block) => {
console.log(`Block ${block.header.number}: ${block.header.gasUsed} gas used`);
});
First, install requests:Then run this code:import requests
import json
url = "https://portal.sqd.dev/datasets/ethereum-mainnet/stream"
headers = {"Content-Type": "application/json"}
payload = {
"type": "evm",
"fromBlock": 18000000,
"toBlock": 18001000,
"fields": {
"block": {
"number": True,
"timestamp": True,
"gasUsed": True
}
}
}
response = requests.post(url, headers=headers, json=payload)
# Response is newline-delimited JSON
for line in response.text.strip().split('\n'):
block = json.loads(line)
print(f"Block {block['header']['number']}: {block['header']['gasUsed']} gas used")
Step 2: Understanding the Request
Let’s break down what you just sent:
{
"type": "evm", // Chain type (EVM, Solana, etc.)
"fromBlock": 18000000, // Starting block (inclusive)
"toBlock": 18001000, // Ending block (inclusive)
"fields": { // What data to return
"block": {
"number": true, // Block number
"timestamp": true, // Block timestamp
"gasUsed": true // Total gas used in block
}
}
}
Portal only returns the fields you request. This keeps responses fast and
bandwidth-efficient.
Step 3: Understanding the Response
Portal returns newline-delimited JSON (NDJSON). Each line is a complete JSON object representing one block:
{
"header": {
"number": 18000000,
"timestamp": 1693066895,
"gasUsed": "0xf7e9ab"
}
}
{
"header": {
"number": 18000439,
"timestamp": 1693072175,
"gasUsed": "0xd314ec"
}
}
{
"header": {
"number": 18000440,
"timestamp": 1693072187,
"gasUsed": "0x10fad02"
}
}
{
"header": {
"number": 18001000,
"timestamp": 1693078967,
"gasUsed": "0xae0606"
}
}
This format enables constant-memory streaming of massive ranges. You can
process millions of blocks without loading everything into RAM.
Step 4: Filter Event Logs
Track USDC Transfer events:
curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \
-H 'Content-Type: application/json' \
-d '{
"type": "evm",
"fromBlock": 18000000,
"toBlock": 18010000,
"fields": {
"log": {
"address": true,
"topics": true,
"data": true,
"transactionHash": true
}
},
"logs": [{
"address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
"topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}]
}'
You should see Transfer events from the USDC contract. Portal filtered the
data before sending, saving bandwidth.
What You Learned
In 5 minutes, you:
- ✓ Made HTTP requests to Portal
- ✓ Queried arbitrary block ranges
- ✓ Filtered smart contract events
- ✓ Processed newline-delimited JSON responses
Rate Limits
The Public Portal is rate-limited:
- 20 requests per 10 seconds
- Perfect for development and testing
Cloud Portal
Production-ready managed access with higher limits
Self-Host Portal
Run your own Portal instance with no rate limits
Next Steps
API Reference
Complete reference with all fields and filters
View Examples
Practical examples for common use cases
Use with SDK
Build type-safe indexers with Portal as the data source
Popular Examples
Query Event Logs
Track smart contract events
Query Transactions
Monitor wallet activity
Track NFT Transfers
Index NFT collection activity
Index DEX Swaps
Build DEX analytics
