sqd_py

Python client for querying blockchain data from SQD Network.

Installation

pip install sqd_py

Install the fast extra to also pull in uvloop (auto-enabled on import, not available on Windows):

pip install sqd_py[fast]

Quick Start

import asyncio
from sqd import SQD, Dataset, EvmFields

async def main():
    sqd = SQD(dataset=Dataset.ETHEREUM)

    query = sqd.get_transactions(
        from_block=17_000_000,
        to_block=17_000_010,
        address="0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    )

    async for block in query:
        for tx in block.get("transactions", []):
            print(tx["hash"])

asyncio.run(main())

Usage

Querying Logs

query = sqd.get_logs(
    from_block=17_000_000,
    to_block=17_000_100,
    address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    topic0="0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
)

async for block in query:
    for log in block.get("logs", []):
        print(log)

ERC-20 Transfers

query = sqd.get_transfers(
    from_block=17_000_000,
    to_block=17_100_000,
    contract_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
)

async for block in query.with_progress():
    for log in block.get("logs", []):
        print(log)

Selecting Fields

query = sqd.get_transactions(
    from_block=17_000_000,
    to_block=17_000_010,
    include_fields=[
        EvmFields.TransactionField.hash,
        EvmFields.TransactionField.from_,
        EvmFields.TransactionField.gasUsed,
    ],
)

Chaining Queries

query = sqd.get_transactions(
    from_block=17_000_000,
    to_block=17_000_010,
    address="0x...",
).get_logs(
    address="0x...",
    topic0="0x...",
)

async for block in query:
    # block contains both transactions and logs
    pass

Progress Bar

async for block in query.with_progress():
    pass

Prefetch is enabled by default (2 concurrent workers) whenever the end of the range is known, and falls back to a single serial worker otherwise. Use prefetch_workers to change the worker count, or pass prefetch_workers=1 to force the serial path:

async for block in query.with_progress(prefetch_workers=4):
    pass

shards is still accepted as a deprecated alias for prefetch_workers.

Hyperliquid (HyperCore fills)

The hyperliquid-fills dataset exposes individual perpetual-futures trade executions (fills). Every filter accepts a single value or a list (OR-match); different filters combine with AND.

from sqd import SQD, HyperliquidFields

sqd = SQD(dataset="hyperliquid-fills", stream_type="finalized")

query = sqd.get_fills(
    from_block=905_000_000,
    to_block=905_001_000,
    coin=["BTC", "ETH"],          # OR; or a single string for one coin
    include_fields=list(HyperliquidFields.FillField),
)

async for block in query:
    for fill in block.get("fills", []):
        print(fill["coin"], fill["px"], fill["sz"], fill["side"])

Available filters: coin, user, builder, dir, fee_token, cloid.

SQD does not serve OHLCV candles directly. Build them by bucketing fills by the time field per coin — see examples/hyperliquid_candles.py.

Supported Datasets

72 EVM chains (Ethereum, Arbitrum, Base, Optimism, Polygon, zkSync, and more — see Dataset for the full list), plus Solana and Hyperliquid:

Chain	Dataset
Ethereum	Dataset.ETHEREUM or "ethereum-mainnet"
Arbitrum One	Dataset.ARBITRUM_ONE or "arbitrum-one"
Base	Dataset.BASE or "base-mainnet"
Optimism	Dataset.OPTIMISM or "optimism-mainnet"
Polygon	Dataset.POLYGON or "polygon-mainnet"
Binance Smart Chain	Dataset.BINANCE or "binance-mainnet"
Solana	Dataset.SOLANA or "solana-mainnet"
Hyperliquid (HyperCore fills)	Dataset.HYPERLIQUID_FILLS or "hyperliquid-fills"

Any other EVM dataset slug served by the SQD portal also works — pass it as a plain string (e.g. SQD(dataset="scroll-mainnet")) even without a matching Dataset member.

API

SQD

SQD(
    dataset: Dataset | str,
    portal_url: str = "https://portal.sqd.dev",
    stream_type: Literal["finalized", "realtime"] = "realtime",
)

Query Methods

EVM: - get_blocks(from_block, to_block, ...) - get_transactions(from_block, address, to_block, ...) - get_logs(from_block, address, topic0, to_block, ...) - get_transfers(from_block, contract_address, ...) - get_traces(from_block, to_block, ...) - get_state_diffs(from_block, to_block, ...)

Hyperliquid: - get_fills(from_block, to_block, coin, user, builder, dir, fee_token, cloid, ...)

Iteration

• async for block in query — default iteration
• query.with_progress(prefetch_workers=N) — with progress bar; prefetching on by default

Requirements

• Python 3.10+
• aiohttp >= 3.9.0
• tqdm >= 4.67.1
• orjson >= 3.10.0

License

MIT