---
name: sqd-blockchain-data
description: >
  Query and index blockchain data using SQD's infrastructure. Use when building
  blockchain data pipelines, querying on-chain data (transactions, logs, traces,
  token transfers, Bitcoin UTXOs), building indexers, or deploying dApp backends.
  Triggers on mentions of blockchain data, on-chain analytics, EVM/Solana/Bitcoin
  indexing, Portal API, Pipes SDK, Squid SDK, SQD, or Subsquid.
metadata:
  author: subsquid
  version: "1.0.7"
  last_updated: "2026-03-25"
---

# SQD Blockchain Data Infrastructure

Build production-grade blockchain data pipelines across 200+ networks. SQD provides four core products: **Portal API** (raw HTTP data access), **Pipes SDK** (composable TypeScript pipelines), **Squid SDK** (complete indexing framework with GraphQL), and **SQD Cloud** (managed deployment).

## Quick Reference

- **Portal API Base URL**: `https://portal.sqd.dev/datasets/{dataset-slug}`
- **Authentication**: Free, no API keys required
- **Rate Limits**: 20 requests per 10 seconds (public), unlimited (self-hosted)
- **Response Format**: Newline-delimited JSON (NDJSON), gzip-compressed. Always use `--compressed` in curl
- **Documentation**: https://beta.docs.sqd.dev
- **Full LLM docs**: https://beta.docs.sqd.dev/llms-full.txt

## When to Use Each Tool

| Scenario | Tool | Why |
|---|---|---|
| Non-TypeScript language (Python, Go, Rust) | **Portal API** | Language-agnostic HTTP |
| One-off data export or analytics | **Portal API** | No setup, simple curl |
| Custom TypeScript pipeline, non-Postgres DB | **Pipes SDK** | Lightweight, any target |
| dApp backend with GraphQL API | **Squid SDK** | Auto-generated GraphQL + TypeORM |
| Managed deployment with monitoring | **Squid SDK + Cloud** | One-command deploy |

## Portal API. Core Usage

### EVM Query Structure

```bash
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},
      "log": {"address": true, "topics": true, "data": true, "transactionHash": true}
    },
    "logs": [{
      "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
      "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }]
  }'
```

**Key parameters:**
- `fromBlock` (required): Starting block number
- `toBlock` (optional): Ending block. Omit to stream to current head and stop
- `includeAllBlocks`: If true, returns all blocks in range even without matching data
- `fields`: Select which fields to return per data type. Reduces payload size
- `logs`, `transactions`, `traces`, `stateDiffs`: Filter arrays for each data type

### Solana Query Structure

```bash
curl --compressed -X POST 'https://portal.sqd.dev/datasets/solana-mainnet/stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "solana",
    "fromBlock": 259984950,
    "fields": {
      "block": {"number": true, "timestamp": true},
      "instruction": {"programId": true, "accounts": true, "data": true}
    },
    "instructions": [{
      "programId": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "d1": ["0x03"]
    }]
  }'
```

Solana discriminators `d1`/`d2`/`d4`/`d8` are 1/2/4/8-byte instruction type identifiers in 0x-prefixed hex format. Example: `"d1": ["0x03"]` filters for SPL Token Transfer instructions.

### Bitcoin Query Structure

```bash
curl --compressed -X POST 'https://portal.sqd.dev/datasets/bitcoin-mainnet/stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bitcoin",
    "fromBlock": 880000,
    "toBlock": 880000,
    "fields": {
      "block": {"number": true, "hash": true, "timestamp": true},
      "transaction": {"txid": true, "hash": true, "size": true, "vsize": true, "weight": true},
      "input": {"transactionIndex": true, "inputIndex": true, "txid": true, "vout": true, "prevoutValue": true, "prevoutScriptPubKeyAddress": true},
      "output": {"transactionIndex": true, "outputIndex": true, "value": true, "scriptPubKeyAddress": true, "scriptPubKeyType": true}
    },
    "transactions": [{}]
  }'
```

**Bitcoin-specific data types:**
- `transactions`: Transaction data (txid, hash, size, vsize, weight, version, locktime). Use `"transactions": [{}]` to match all. Set `inputs: true` / `outputs: true` to include related data
- `inputs`: Transaction inputs with prevout data. Filter by `prevoutScriptPubKeyAddress`, `prevoutScriptPubKeyType`, or `prevoutGenerated` (coinbase). Set `transaction: true` to include parent tx
- `outputs`: Transaction outputs. Filter by `scriptPubKeyAddress` or `scriptPubKeyType` (e.g. `witness_v1_taproot`, `witness_v0_keyhash`, `pubkeyhash`, `scripthash`, `nulldata`). Set `transaction: true` to include parent tx

**Bitcoin block fields:** `number`, `hash`, `parentHash`, `timestamp`, `medianTime`, `version`, `merkleRoot`, `nonce`, `target`, `bits`, `difficulty`, `chainWork`, `strippedSize`, `size`, `weight`

### Common Event Signatures (topic0)

- **Transfer** (ERC-20/721): `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`
- **Approval** (ERC-20): `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925`
- **Swap** (Uniswap V2): `0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822`
- **Swap** (Uniswap V3): `0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67`

### Endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/stream` | POST | Stream blocks matching query, including real-time data |
| `/finalized-stream` | POST | Stream only finalized blocks (production-safe, handles reorgs) |
| `/head` | GET | Current chain head block |
| `/finalized-head` | GET | Latest finalized block |
| `/metadata` | GET | Dataset info: name, aliases, start block, real-time support |

### Error Codes

- **400**: Invalid query format
- **404**: Dataset not found (check slug at https://portal.sqd.dev/datasets)
- **204**: Requested block range exceeds available data
- **409**: Chain reorg conflict. Retry with updated block range
- **429**: Rate limit exceeded (20 req/10s on public Portal)
- **500**: Internal server error

**Important**: `fromBlock` is required. Omitting it silently streams from block 0, which is expensive and almost never what you want.

### Top Dataset Slugs

| Network | Slug | Chain ID | Real-time |
|---|---|---|---|
| Ethereum | `ethereum-mainnet` | 1 | ✓ |
| Base | `base-mainnet` | 8453 | ✓ |
| Arbitrum One | `arbitrum-one` | 42161 | ✓ |
| Optimism | `optimism-mainnet` | 10 | ✓ |
| Polygon | `polygon-mainnet` | 137 | ✓ |
| BSC | `binance-mainnet` | 56 | ✓ |
| Avalanche | `avalanche-mainnet` | 43114 | ✓ |
| Solana | `solana-mainnet` |. | ✓ |
| Bitcoin | `bitcoin-mainnet` |. | ✓ |
| Ethereum Sepolia | `ethereum-sepolia` | 11155111 | ✓ |
| Base Sepolia | `base-sepolia` | 84532 |. |

Full list: https://portal.sqd.dev/datasets (returns JSON array of dataset objects)

## Pipes SDK. Composable Pipelines

TypeScript-only. Currently supports EVM and Solana.

```typescript
import { createPipeline } from "@subsquid/portal-pipes";

const pipeline = createPipeline({
  portal: "https://portal.sqd.dev/datasets/ethereum-mainnet",
  query: {
    type: "evm",
    fromBlock: 18000000,
    fields: { log: { address: true, topics: true, data: true } },
    logs: [{ address: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"] }]
  }
});
```

Use Pipes SDK when: integrating into existing Node.js apps, storing to non-Postgres databases (ClickHouse, MongoDB, Kafka), or needing fine-grained streaming control.

## Squid SDK. Full Indexing Framework

TypeScript-only. Supports EVM, Solana, Substrate, Fuel, Tron, Starknet.

```typescript
import { EvmBatchProcessor } from "@subsquid/evm-processor";
import { TypeormDatabase } from "@subsquid/typeorm-store";

const processor = new EvmBatchProcessor()
  .setPortal("https://portal.sqd.dev/datasets/ethereum-mainnet")
  .addLog({ address: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"] });

processor.run(new TypeormDatabase(), async (ctx) => {
  for (const block of ctx.blocks) {
    for (const log of block.logs) {
      // decode and persist
    }
  }
});
```

Use Squid SDK when: building dApp backends with auto-generated GraphQL APIs, needing PostgreSQL with TypeORM migrations, or deploying to SQD Cloud (`sqd deploy`).

## Common Recipes

**Track USDC transfers on Base:**
```bash
curl --compressed -X POST 'https://portal.sqd.dev/datasets/base-mainnet/stream' \
  -H 'Content-Type: application/json' \
  -d '{"type":"evm","fromBlock":10000000,"fields":{"block":{"number":true,"timestamp":true},"log":{"topics":true,"data":true,"transactionHash":true}},"logs":[{"address":["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],"topic0":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}'
```

**Index Uniswap V3 swaps on Ethereum:**
```bash
curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \
  -H 'Content-Type: application/json' \
  -d '{"type":"evm","fromBlock":18000000,"fields":{"block":{"number":true,"timestamp":true},"log":{"address":true,"topics":true,"data":true}},"logs":[{"topic0":["0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67"]}]}'
```

**Query Bitcoin Taproot outputs:**
```bash
curl --compressed -X POST 'https://portal.sqd.dev/datasets/bitcoin-mainnet/stream' \
  -H 'Content-Type: application/json' \
  -d '{"type":"bitcoin","fromBlock":880000,"toBlock":880000,"fields":{"block":{"number":true,"timestamp":true},"output":{"transactionIndex":true,"outputIndex":true,"value":true,"scriptPubKeyType":true,"scriptPubKeyAddress":true}},"outputs":[{"scriptPubKeyType":["witness_v1_taproot"]}]}'
```

**Track contract deployments via traces:**
```bash
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":{"trace":{"type":true,"from":true,"to":true,"value":true}},"traces":[{"type":["create"]}]}'
```

## Guidelines

- Always use `--compressed` with curl. Portal returns gzip-compressed responses
- Use `/finalized-stream` instead of `/stream` for production-critical applications that need reorg safety
- Filter by `address` and/or `topic0` in logs to minimize response size. Unfiltered queries on busy chains return massive payloads
- The `fields` object controls which properties are returned per data type. Request only what you need
- Portal is 10-50x faster than RPC for historical data extraction
- For continuous real-time streaming, reconnect to `/stream` periodically after reaching head
- OpenAPI specs available at: https://beta.docs.sqd.dev/files/evm-openapi.yaml, https://beta.docs.sqd.dev/files/solana-openapi.yaml, and https://beta.docs.sqd.dev/files/bitcoin-openapi.yaml

## Portal MCP Server. Convenience Tools

The Portal MCP Server (`https://portal.sqd.dev/mcp`) provides high-level tools that are often more useful than raw curl for AI workflows:

| Tool | What it does |
|---|---|
| `portal_get_erc20_transfers` | Auto-decodes Transfer events, adds token metadata, formats human-readable amounts |
| `portal_get_nft_transfers` | ERC721/ERC1155 transfers. Note: `token_standard: "erc721"` is not supported (ERC-721 shares Transfer signature with ERC-20). Use `"erc1155"` or `"both"`, or provide specific `contract_addresses` |
| `portal_get_wallet_summary` | Full wallet activity: transactions + tokens + NFTs |
| `portal_get_gas_analytics` | Gas price trends, cost estimates |
| `portal_get_contract_activity` | Contract usage stats, top callers |
| `portal_aggregate_transfers` | Aggregate ERC20 transfer stats without fetching all records |
| `portal_decode_logs` | Decode event logs using known signatures (Swap, Transfer, etc.) |
| `portal_block_at_timestamp` | Convert Unix timestamp to block number |
| `portal_count_events` | Count events without fetching data (note: `group_by: "topic0"` may return "unknown") |
| `portal_get_recent_transactions` | Recent txs without manual block math |
| `portal_get_top_contracts` | Most active contracts by tx count |
| `portal_get_time_series` | Aggregate metrics over time intervals |
| `portal_query_hyperliquid_fills` | Hyperliquid trade executions, PnL, fees |
| `portal_query_hyperliquid_replica_cmds` | Hyperliquid orders, cancels, transfers, leverage |
| `portal_list_datasets` | List/search available datasets |
| `portal_get_token_info` | Token metadata from CoinGecko (name, symbol, logo). Won't find obscure/new tokens not listed on CoinGecko |
| `portal_get_dataset_info` | Dataset details: latest block, chain type, tables |
| `portal_get_block_number` | Current/latest block number |
| `portal_stream` | Raw Portal API streaming queries |

**Prefer MCP convenience tools over raw curl** when available. They auto-decode values, add token metadata, and format amounts.

## AI Integration

- **Docs MCP Server**: `https://beta.docs.sqd.dev/mcp`. Search and access SQD documentation
- **Portal MCP Server**: `https://portal.sqd.dev/mcp`. Query blockchain data directly (see convenience tools above)
- **Agent Skills**: https://github.com/subsquid-labs/agent-skills