{ "openapi": "3.1.0", "info": { "title": "SQD Portal API", "version": "1.0.0", "summary": "Streaming HTTP access to decoded blockchain data across 140+ networks.", "description": "The SQD Portal serves raw and decoded onchain data (blocks, transactions, logs, traces,\nstate diffs, Solana instructions, Bitcoin transactions, Hyperliquid fills) over plain\nHTTP, one dataset per network. Responses to the stream endpoints are JSON Lines, so a\nclient reads them incrementally instead of buffering a whole range.\n\nThe public Portal at https://portal.sqd.dev shares capacity across users and is intended\nfor development and bounded evaluation. Authenticated and dedicated portals take an API\nkey in the `x-api-key` header; the paths and payloads are identical either way.\n\nEvery error, on every status code, is JSON: `{\"error\":{\"type\",\"code\",\"message\"}}`. Match on\n`error.code`, not on the message text.\n\nWhat the Portal does NOT serve: reconstructed contract state. There is no balance-at-block\nor `balanceOf` call. Balances are derived by the caller from transfer and state-diff data.", "contact": { "name": "SQD", "url": "https://sqd.dev/contact/" }, "termsOfService": "https://sqd.dev/imprint/" }, "externalDocs": { "description": "SQD Portal API reference", "url": "https://docs.sqd.dev/en/api/evm/introduction" }, "servers": [ { "url": "https://portal.sqd.dev", "description": "Public SQD Portal. Shared capacity, for development and bounded evaluation." }, { "url": "https://{portal}", "description": "Authenticated or dedicated portal. Same paths and payloads as the public one.", "variables": { "portal": { "default": "portal.sqd.dev", "description": "Hostname of the dedicated portal issued to your organisation." } } } ], "tags": [ { "name": "Datasets", "description": "Discover networks and inspect what a dataset currently holds." }, { "name": "Streaming", "description": "Read matching blocks as JSON Lines." } ], "security": [ {}, { "portalApiKey": [] } ], "paths": { "/datasets": { "get": { "operationId": "listDatasets", "summary": "List every available dataset", "description": "Returns one entry per supported network, with its canonical name, any aliases, and whether it carries real-time data. Start here: the `dataset` path parameter of every other operation comes from this list.", "tags": [ "Datasets" ], "responses": { "200": { "description": "The datasets this portal serves.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "examples": { "default": { "summary": "Truncated live response", "value": [ { "dataset": "arbitrum-one", "aliases": [], "real_time": true }, { "dataset": "base-mainnet", "aliases": [], "real_time": true } ] } } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/metadata": { "get": { "operationId": "getDatasetMetadata", "summary": "Describe one dataset", "description": "Returns the dataset name, aliases, whether it is real-time, and its `start_block`. A query with `fromBlock` below `start_block` is rejected with 400, so read this first when querying deep history.", "tags": [ "Datasets" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "responses": { "200": { "description": "Dataset metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetMetadata" }, "examples": { "default": { "summary": "Live response for ethereum-mainnet", "value": { "dataset": "ethereum-mainnet", "aliases": [], "real_time": true, "start_block": 0 } } } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/head": { "get": { "operationId": "getDatasetHead", "summary": "Get the highest available block", "description": "Returns the number and hash of the highest block the dataset holds, real-time data included, or `null` when the dataset is empty. Use it to bound a query or to check how far ingestion has progressed.", "tags": [ "Datasets" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "responses": { "200": { "description": "Highest available block, or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockHead" }, "examples": { "default": { "summary": "Live response for ethereum-mainnet", "value": { "number": 25826425, "hash": "0x252be3366c3493c60d065a0145f69936e3485a78e1ab02865ede976342dcdac0" } } } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/finalized-head": { "get": { "operationId": "getDatasetFinalizedHead", "summary": "Get the highest finalized block", "description": "Same as `getDatasetHead`, restricted to finalized blocks. Anything at or below this height will not be reorganised, so it is the safe watermark for irreversible bookkeeping.", "tags": [ "Datasets" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "responses": { "200": { "description": "Highest finalized block, or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockHead" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/timestamps/{timestamp}/block": { "get": { "operationId": "resolveTimestampToBlock", "summary": "Resolve a Unix timestamp to a block number", "description": "Returns the first block at or after the given instant. Block numbers are not comparable\nacross networks, so this is how a caller lines up the same wall-clock window on several\nchains before querying each one. On Solana the same field carries a slot.\n\nThe timestamp is in **seconds**. Passing milliseconds does not error in an obvious way:\nthe value lands far beyond the chain head and comes back as a 404, so a client that\nforgets to divide sees \"not found\" rather than \"wrong unit\".", "tags": [ "Datasets" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } }, { "name": "timestamp", "in": "path", "required": true, "description": "Unix timestamp in seconds, not milliseconds.", "schema": { "type": "integer", "format": "int64", "minimum": 0, "examples": [ 1748736000 ] } } ], "responses": { "200": { "description": "The first block at or after the timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimestampBlock" }, "examples": { "default": { "summary": "2025-06-01 00:00:00 UTC on Base, from a live response", "value": { "block_number": 30973327 } } } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "400": { "description": "The timestamp is not an integer. `error.code` is `malformed_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset (`unknown_dataset`), or the timestamp is beyond the highest block the dataset holds (`not_found`). A millisecond timestamp lands here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/state": { "get": { "operationId": "getDatasetState", "summary": "Get stored block ranges per worker", "description": "Returns which block ranges each SQD Network worker currently holds, plus the highest seen block and the first gap. Intended for diagnostics and network status views. The response is large (tens of MB for a mature dataset); prefer `getDatasetMetadata` or `getDatasetHead` for routine checks.", "tags": [ "Datasets" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "responses": { "200": { "description": "Stored ranges for the dataset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetState" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } } } } }, "/datasets/{dataset}/stream": { "post": { "operationId": "streamBlocks", "summary": "Stream blocks matching a query", "description": "Streams every block matching the query as JSON Lines (`application/jsonl`), one JSON object\nper line, including unfinalized blocks. Send `Content-Type: application/json`; optionally\n`Accept-Encoding: gzip` and `Content-Encoding: gzip`.\n\nThe response is open-ended when `toBlock` is omitted, so read it as a stream. Cross-check\n`X-Sqd-Finalized-Head-Number` to know which returned blocks are still reorg-able; on a 409,\nrestart from a block both sides agree on.", "tags": [ "Streaming" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "requestBody": { "required": true, "description": "Block range, field selector, and item filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataQuery" }, "examples": { "evmBlockHeaders": { "summary": "Two Ethereum block headers", "value": { "type": "evm", "fromBlock": 20494139, "toBlock": 20494140, "fields": { "block": { "number": true, "hash": true } } } }, "evmTransfers": { "summary": "ERC-20 Transfer logs for one contract", "value": { "type": "evm", "fromBlock": 20494139, "toBlock": 20494200, "fields": { "log": { "address": true, "topics": true, "data": true }, "block": { "number": true } }, "logs": [ { "address": [ "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" ], "topic0": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" ] } ] } }, "solanaBlocks": { "summary": "One Solana block header", "value": { "type": "solana", "fromBlock": 317617480, "toBlock": 317617480, "fields": { "block": { "number": true, "hash": true } } } } } } } }, "responses": { "200": { "description": "Matching blocks as JSON Lines. Empty when a bounded range contains no match.", "headers": { "X-Sqd-Finalized-Head-Number": { "description": "Block number of the latest finalized block. Returned blocks may sit above, at, or below it.", "schema": { "type": "integer", "format": "int64" } }, "X-Sqd-Finalized-Head-Hash": { "description": "Hash of the latest finalized block. Every returned block belongs to the same chain as this block.", "schema": { "type": "string" } }, "X-Sqd-Head-Number": { "description": "Block number of the highest block the dataset currently holds.", "schema": { "type": "integer", "format": "int64" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } }, "X-Sqd-Data-Source": { "description": "Which tier answered: `network` for data read from the decentralised lake, `real_time` for unfinalized blocks held near the head.", "schema": { "type": "string", "enum": [ "network", "real_time" ] } } }, "content": { "application/jsonl": { "schema": { "$ref": "#/components/schemas/Block" }, "examples": { "default": { "summary": "One line of a live response; the stream sends one such object per block", "value": { "header": { "number": 20494139, "hash": "0x3faa6ecbfc83a0c5d95a9728616295cfb17238edc897550fdc1330e3b8edf575" } } } } } } }, "204": { "description": "The requested range sits entirely above the dataset height. The portal may hold the request for up to 5s first.", "headers": { "X-Sqd-Finalized-Head-Number": { "description": "Block number of the latest finalized block. Returned blocks may sit above, at, or below it.", "schema": { "type": "integer", "format": "int64" } }, "X-Sqd-Finalized-Head-Hash": { "description": "Hash of the latest finalized block. Every returned block belongs to the same chain as this block.", "schema": { "type": "string" } }, "X-Sqd-Head-Number": { "description": "Block number of the highest block the dataset currently holds.", "schema": { "type": "integer", "format": "int64" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } }, "X-Sqd-Data-Source": { "description": "Which tier answered: `network` for data read from the decentralised lake, `real_time` for unfinalized blocks held near the head.", "schema": { "type": "string", "enum": [ "network", "real_time" ] } } } }, "400": { "description": "Malformed request: bad encoding, an invalid query, or a `fromBlock` below the dataset start block (see `getDatasetMetadata`). `error.message` names the offending field and lists the accepted values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "409": { "description": "The requested range starts on an orphaned block. The body lists recent blocks on the current chain; restart the stream from the newest one your records agree with.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` when present.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Do not retry the identical request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later, honouring `Retry-After` when present.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/datasets/{dataset}/finalized-stream": { "post": { "operationId": "streamFinalizedBlocks", "summary": "Stream finalized blocks matching a query", "description": "Identical to `streamBlocks` in query shape and response format, restricted to finalized blocks. It lags the chain head by the network finality delay.\n\nNothing it returns can later be reorganised, so a cursor taken from this stream stays valid. That is not the same as never seeing a 409: if you carry over a `parentBlockHash` from the unfinalized stream, or from a chain the dataset no longer agrees with, this endpoint answers `base_block_mismatch` exactly as `streamBlocks` does. Handle the 409 and resume from the newest block in `previousBlocks` that your records agree with.", "tags": [ "Streaming" ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "description": "Dataset name or alias, one per network (e.g. `ethereum-mainnet`, `solana-mainnet`, `base-mainnet`). Enumerate the current set with `listDatasets`.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "examples": [ "ethereum-mainnet" ] } } ], "requestBody": { "required": true, "description": "Block range, field selector, and item filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataQuery" } } } }, "responses": { "200": { "description": "Matching finalized blocks as JSON Lines.", "headers": { "X-Sqd-Finalized-Head-Number": { "description": "Block number of the latest finalized block. Returned blocks may sit above, at, or below it.", "schema": { "type": "integer", "format": "int64" } }, "X-Sqd-Finalized-Head-Hash": { "description": "Hash of the latest finalized block. Every returned block belongs to the same chain as this block.", "schema": { "type": "string" } }, "X-Sqd-Head-Number": { "description": "Block number of the highest block the dataset currently holds.", "schema": { "type": "integer", "format": "int64" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } }, "X-Sqd-Data-Source": { "description": "Which tier answered: `network` for data read from the decentralised lake, `real_time` for unfinalized blocks held near the head.", "schema": { "type": "string", "enum": [ "network", "real_time" ] } } }, "content": { "application/jsonl": { "schema": { "$ref": "#/components/schemas/Block" } } } }, "204": { "description": "The requested range sits entirely above the finalized height.", "headers": { "X-Sqd-Finalized-Head-Number": { "description": "Block number of the latest finalized block. Returned blocks may sit above, at, or below it.", "schema": { "type": "integer", "format": "int64" } }, "X-Sqd-Finalized-Head-Hash": { "description": "Hash of the latest finalized block. Every returned block belongs to the same chain as this block.", "schema": { "type": "string" } }, "X-Sqd-Head-Number": { "description": "Block number of the highest block the dataset currently holds.", "schema": { "type": "integer", "format": "int64" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } }, "X-Sqd-Data-Source": { "description": "Which tier answered: `network` for data read from the decentralised lake, `real_time` for unfinalized blocks held near the head.", "schema": { "type": "string", "enum": [ "network", "real_time" ] } } } }, "400": { "description": "Malformed request: bad encoding, an invalid query, or a `fromBlock` below the dataset start block (see `getDatasetMetadata`). `error.message` names the offending field and lists the accepted values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "404": { "description": "Unknown dataset. `error.code` is `unknown_dataset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "405": { "description": "Wrong HTTP method for this path. `error.code` is `method_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "409": { "description": "The requested range starts on an orphaned block. The body lists recent blocks on the current chain; restart the stream from the newest one your records agree with.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` when present.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Do not retry the identical request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later, honouring `Retry-After` when present.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Identifier for this request, returned on every response. Quote it when reporting a problem; on some errors it also appears in the body as `error.request_id`.", "schema": { "type": "string", "examples": [ "3119d9c92fe4aae6032e714631fe4442" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "portalApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for an authenticated or dedicated portal. The public Portal accepts requests without one. See https://docs.sqd.dev/en/portal/pricing for access options." } }, "schemas": { "Dataset": { "type": "object", "title": "Dataset", "description": "One network served by this portal.", "required": [ "dataset", "aliases", "real_time" ], "properties": { "dataset": { "type": "string", "description": "Canonical dataset name, used in every path.", "examples": [ "ethereum-mainnet" ] }, "aliases": { "type": "array", "description": "Alternative names accepted in the same position.", "items": { "type": "string" } }, "real_time": { "type": "boolean", "description": "Whether the dataset carries unfinalized, real-time blocks." } } }, "DatasetMetadata": { "type": "object", "title": "DatasetMetadata", "required": [ "dataset", "aliases", "real_time", "start_block" ], "properties": { "dataset": { "type": "string", "description": "Canonical dataset name." }, "aliases": { "type": "array", "description": "Alternative names.", "items": { "type": "string" } }, "real_time": { "type": "boolean", "description": "Whether real-time blocks are served." }, "start_block": { "type": "integer", "format": "int64", "description": "Lowest block available. A `fromBlock` below this is a 400." } } }, "DatasetState": { "type": "object", "title": "DatasetState", "description": "Which ranges each worker holds. Large; diagnostics only.", "required": [ "worker_ranges", "highest_seen_block" ], "properties": { "worker_ranges": { "type": "object", "description": "Keyed by worker peer ID.", "additionalProperties": { "type": "object", "required": [ "ranges" ], "properties": { "ranges": { "type": "array", "items": { "type": "object", "required": [ "begin", "end" ], "properties": { "begin": { "type": "integer", "format": "int64", "description": "First block, inclusive." }, "end": { "type": "integer", "format": "int64", "description": "Last block, inclusive." } } } } } } }, "highest_seen_block": { "type": "integer", "format": "int64", "description": "Highest block number seen for this dataset." }, "first_gap": { "type": "integer", "format": "int64", "description": "First block number with missing coverage, when one exists." } } }, "BlockHead": { "type": [ "object", "null" ], "title": "BlockHead", "description": "A block reference, or null when the dataset is empty.", "required": [ "number", "hash" ], "properties": { "number": { "type": "integer", "format": "int64", "description": "Block number." }, "hash": { "type": "string", "description": "Block hash." } } }, "TimestampBlock": { "type": "object", "title": "TimestampBlock", "description": "The block a timestamp resolves to. On Solana `block_number` carries a slot.", "required": [ "block_number" ], "properties": { "block_number": { "type": "integer", "format": "int64", "description": "Number of the first block at or after the requested instant." } } }, "DataQuery": { "type": "object", "title": "DataQuery", "description": "What to read and which fields to return. `type` selects the chain family and must match\nthe dataset; the item filters below (`logs`, `transactions`, `traces`, `stateDiffs`) are the\nEVM set. Other families take their own item filters: Solana `instructions`, Bitcoin\n`transactions`, Hyperliquid `fills`, documented per chain in the SQD docs.\n\nUnknown keys are rejected with 400, and the error message lists what was accepted, so a\nclient can discover the exact per-chain shape from the API itself.", "required": [ "type", "fromBlock" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Chain family of the dataset being queried.", "enum": [ "evm", "solana", "substrate", "bitcoin", "fuel", "tron", "hyperliquidFills", "hyperliquidReplicaCmds" ], "examples": [ "evm" ] }, "fromBlock": { "type": "integer", "format": "int64", "minimum": 0, "description": "First block to read, inclusive. Must be >= the dataset `start_block`." }, "toBlock": { "type": "integer", "format": "int64", "minimum": 0, "description": "Last block to read, inclusive. Omit to stream until the dataset height, then keep following the chain." }, "parentBlockHash": { "type": "string", "description": "Expected parent hash of the first requested block. When it disagrees with the chain, the request fails with 409 instead of returning orphaned data." }, "includeAllBlocks": { "type": "boolean", "default": false, "description": "Return blocks in range even when nothing in them matches the filters." }, "fields": { "type": "object", "description": "Field selector. Only requested fields are returned, which is what keeps responses small. The `block` selector below is the EVM set.", "additionalProperties": true, "properties": { "block": { "type": "object", "description": "Block header field selector. Which names are accepted depends on the query `type`; each is annotated below with the families that take it. Sending an unknown name returns a `malformed_request` error whose message lists the accepted set for that dataset.", "additionalProperties": true, "properties": { "number": { "type": "boolean", "default": false, "description": "Accepted by every dataset type." }, "hash": { "type": "boolean", "default": false, "description": "Accepted by every dataset type." }, "parentHash": { "type": "boolean", "default": false, "description": "Accepted by every dataset type." }, "timestamp": { "type": "boolean", "default": false, "description": "Accepted by every dataset type." }, "transactionsRoot": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "receiptsRoot": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "stateRoot": { "type": "boolean", "default": false, "description": "Accepted by: evm, substrate." }, "logsBloom": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "sha3Uncles": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "extraData": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "miner": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "nonce": { "type": "boolean", "default": false, "description": "Accepted by: evm, bitcoin." }, "mixHash": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "size": { "type": "boolean", "default": false, "description": "Accepted by: evm, bitcoin." }, "gasLimit": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "gasUsed": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "difficulty": { "type": "boolean", "default": false, "description": "Accepted by: evm, bitcoin." }, "totalDifficulty": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "baseFeePerGas": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "uncles": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "withdrawals": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "withdrawalsRoot": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "blobGasUsed": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "excessBlobGas": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "parentBeaconBlockRoot": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "requestsHash": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "l1BlockNumber": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "mainBlockGeneralGasLimit": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "sharedGasLimit": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "timestampMillisPart": { "type": "boolean", "default": false, "description": "Accepted by: evm." }, "bits": { "type": "boolean", "description": "Accepted by: bitcoin." }, "chainWork": { "type": "boolean", "description": "Accepted by: bitcoin." }, "digest": { "type": "boolean", "description": "Accepted by: substrate." }, "extrinsicsRoot": { "type": "boolean", "description": "Accepted by: substrate." }, "hardfork": { "type": "boolean", "description": "Accepted by: hyperliquidReplicaCmds." }, "height": { "type": "boolean", "description": "Accepted by: solana." }, "implName": { "type": "boolean", "description": "Accepted by: substrate." }, "implVersion": { "type": "boolean", "description": "Accepted by: substrate." }, "medianTime": { "type": "boolean", "description": "Accepted by: bitcoin." }, "merkleRoot": { "type": "boolean", "description": "Accepted by: bitcoin." }, "parentNumber": { "type": "boolean", "description": "Accepted by: solana." }, "parentRound": { "type": "boolean", "description": "Accepted by: hyperliquidReplicaCmds." }, "proposer": { "type": "boolean", "description": "Accepted by: hyperliquidReplicaCmds." }, "round": { "type": "boolean", "description": "Accepted by: hyperliquidReplicaCmds." }, "specName": { "type": "boolean", "description": "Accepted by: substrate." }, "specVersion": { "type": "boolean", "description": "Accepted by: substrate." }, "strippedSize": { "type": "boolean", "description": "Accepted by: bitcoin." }, "target": { "type": "boolean", "description": "Accepted by: bitcoin." }, "txTrieRoot": { "type": "boolean", "description": "Accepted by: tron." }, "validator": { "type": "boolean", "description": "Accepted by: substrate." }, "version": { "type": "boolean", "description": "Accepted by: bitcoin, tron." }, "weight": { "type": "boolean", "description": "Accepted by: bitcoin." }, "witnessAddress": { "type": "boolean", "description": "Accepted by: tron." }, "witnessSignature": { "type": "boolean", "description": "Accepted by: tron." } } } } }, "logs": { "type": "array", "description": "EVM log filters. Entries are OR-ed; keys within an entry are AND-ed.", "items": { "type": "object", "additionalProperties": true, "properties": { "address": { "type": "array", "description": "Contract addresses, lowercase hex.", "items": { "type": "string" } }, "topic0": { "type": "array", "description": "Event signature hashes.", "items": { "type": "string" } }, "topic1": { "type": "array", "description": "First indexed argument.", "items": { "type": "string" } }, "topic2": { "type": "array", "description": "Second indexed argument.", "items": { "type": "string" } }, "topic3": { "type": "array", "description": "Third indexed argument.", "items": { "type": "string" } }, "transaction": { "type": "boolean", "description": "Also return the transaction that produced each matching log." } } } }, "transactions": { "type": "array", "description": "EVM transaction filters. Entries are OR-ed.", "items": { "type": "object", "additionalProperties": true, "properties": { "from": { "type": "array", "description": "Sender addresses.", "items": { "type": "string" } }, "to": { "type": "array", "description": "Recipient addresses.", "items": { "type": "string" } }, "sighash": { "type": "array", "description": "Function selectors.", "items": { "type": "string" } }, "logs": { "type": "boolean", "description": "Also return the logs each match emitted." }, "traces": { "type": "boolean", "description": "Also return the traces each match produced." } } } }, "traces": { "type": "array", "description": "EVM trace filters, for internal calls and contract creations.", "items": { "type": "object", "additionalProperties": true } }, "stateDiffs": { "type": "array", "description": "EVM storage state-diff filters.", "items": { "type": "object", "additionalProperties": true } } } }, "Block": { "type": "object", "title": "Block", "description": "One line of a stream response. `header` always carries the requested header fields; the other keys appear only when the query asked for those item types.", "required": [ "header" ], "additionalProperties": true, "properties": { "header": { "type": "object", "description": "The header fields named in `fields.block`.", "additionalProperties": true, "properties": { "number": { "type": "integer", "format": "int64", "description": "Block number." }, "hash": { "type": "string", "description": "Block hash." } } }, "logs": { "type": "array", "description": "Matching logs.", "items": { "type": "object", "additionalProperties": true } }, "transactions": { "type": "array", "description": "Matching transactions.", "items": { "type": "object", "additionalProperties": true } }, "traces": { "type": "array", "description": "Matching traces.", "items": { "type": "object", "additionalProperties": true } }, "stateDiffs": { "type": "array", "description": "Matching state diffs.", "items": { "type": "object", "additionalProperties": true } }, "instructions": { "type": "array", "description": "Matching Solana instructions.", "items": { "type": "object", "additionalProperties": true } } } }, "ConflictResponse": { "type": "object", "title": "ConflictResponse", "description": "Returned when the requested range starts on an orphaned block. Carries the standard error envelope (error.code is base_block_mismatch) plus recent blocks on the current chain.", "additionalProperties": true, "properties": { "previousBlocks": { "type": "array", "description": "Recent blocks on the current chain, newest last.", "items": { "type": "object", "required": [ "number", "hash" ], "properties": { "number": { "type": "integer", "format": "int64", "description": "Block number." }, "hash": { "type": "string", "description": "Block hash." } } } }, "error": { "type": "object", "description": "The error itself. Present on every failing response.", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "description": "Error class.", "examples": [ "invalid_request_error" ] }, "code": { "type": "string", "description": "Stable, machine-matchable identifier.", "examples": [ "unknown_dataset", "malformed_request", "method_not_allowed", "not_found" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "request_id": { "type": "string", "description": "Opaque identifier for this request, returned on some errors (rate limiting among them). Quote it when reporting a problem." } } } } }, "ErrorResponse": { "type": "object", "title": "ErrorResponse", "description": "The single error envelope, returned as JSON on every failing status code. Match on `error.code`; `error.message` is written for humans and may be reworded.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "The error itself. Present on every failing response.", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "description": "Error class.", "examples": [ "invalid_request_error" ] }, "code": { "type": "string", "description": "Stable, machine-matchable identifier.", "examples": [ "unknown_dataset", "malformed_request", "method_not_allowed", "not_found" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "request_id": { "type": "string", "description": "Opaque identifier for this request, returned on some errors (rate limiting among them). Quote it when reporting a problem." } } } }, "examples": [ { "error": { "type": "invalid_request_error", "code": "unknown_dataset", "message": "Unknown dataset: not-a-real-dataset" } } ] } } } }