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
Next Steps
Popular Examples
