openapi: 3.1.0 info: title: SQD Portal API - EVM Dataset Endpoints description: API endpoints for interacting with EVM datasets under the SQD Portal, specifically for the Ethereum Mainnet dataset. version: 1.0.0 servers: - url: https://portal.sqd.dev/datasets/ethereum-mainnet description: SQD Portal's endpoint for Ethereum Mainnet paths: /metadata: get: summary: Dataset Metadata operationId: getEvmDatasetMetadata x-mint: href: "/en/api/evm/metadata" metadata: description: "Get EVM dataset metadata from the SQD Portal API." x-codeSamples: - lang: shell label: Get Ethereum Mainnet Metadata source: | curl --compressed 'https://portal.sqd.dev/datasets/ethereum-mainnet/metadata' - lang: python label: Get Ethereum Mainnet Metadata source: | import requests response = requests.get( "https://portal.sqd.dev/datasets/ethereum-mainnet/metadata" ) metadata = response.json() - lang: javascript label: Get Ethereum Mainnet Metadata source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/metadata"); const metadata = await response.json(); description: "Retrieves metadata describing the dataset, including its name, aliases, start block, and real-time status." responses: "200": description: Dataset metadata response content: application/json: schema: $ref: "#/components/schemas/DatasetMetadata" examples: ethereum-mainnet: summary: Ethereum Mainnet metadata value: dataset: "ethereum-mainnet" aliases: [] real_time: true start_block: 0 "404": description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" /stream: post: summary: Stream Blocks operationId: streamEvmBlocks x-mint: href: "/en/api/evm/stream" metadata: description: "Stream EVM blockchain data with the SQD Portal API." x-codeSamples: - lang: shell label: ERC-20 Transfers source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "log": { "address": true, "topics": true, "data": true, "transactionHash": true, "logIndex": true } }, "logs": [{ "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }' - lang: shell label: Track NFT Transfers source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "log": { "address": true, "topics": true, "transactionHash": true } }, "logs": [{ "address": [ "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "0x60E4d786628Fea6478F785A6d7e704777c86a7c6", "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB" ], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }' - lang: shell label: Transactions source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "transaction": { "hash": true, "from": true, "to": true, "value": true, "input": true, "gasUsed": true, "status": true } }, "transactions": [{ "to": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"] }] }' - lang: python label: ERC-20 Transfers source: | import requests response = requests.post( "https://portal.sqd.dev/datasets/ethereum-mainnet/stream", json={ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": True, "timestamp": True }, "log": { "address": True, "topics": True, "data": True, "transactionHash": True, "logIndex": True } }, "logs": [{ "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] } ) blocks = response.json() - lang: javascript label: ERC-20 Transfers source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/stream", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "evm", fromBlock: 21000000, toBlock: 21000100, fields: { block: { number: true, timestamp: true }, log: { address: true, topics: true, data: true, transactionHash: true, logIndex: true } }, logs: [{ address: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], topic0: ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }) }); const blocks = await response.json(); description: "Streams a list of blocks matching the provided data query, potentially including real-time data. Required request headers: `Content-Type: application/json`; optional request headers: `Accept-Encoding: gzip`, `Content-Encoding: gzip`." requestBody: description: "Data query to filter and retrieve blocks. Request body may be gzipped (Content-Encoding: gzip)." required: true content: application/json: schema: $ref: "#/components/schemas/DataQuery" examples: erc20-transfers: summary: ERC-20 Transfers value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true log: address: true topics: true data: true transactionHash: true logIndex: true logs: - address: - "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" topic0: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" nft-transfers: summary: Track NFT Transfers value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true log: address: true topics: true transactionHash: true logs: - address: - "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" - "0x60E4d786628Fea6478F785A6d7e704777c86a7c6" - "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB" topic0: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" transactions: summary: Transactions value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true transaction: hash: true from: true to: true value: true input: true gasUsed: true status: true transactions: - to: - "0xdAC17F958D2ee523a2206206994597C13D831ec7" responses: "200": description: A stream of blocks in JSON lines format, optionally gzipped. Can be empty if the data query has a bounded range and all blocks in the range have been skipped. May include X-Sqd-Finalized-Head-Number and X-Sqd-Finalized-Head-Hash headers, indicating the latest finalized block that's on the same chain as the returned blocks. headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: Block number of the latest finalized block. Returned blocks can be above, at, or below this block number. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: Hash of the latest finalized block. All returned blocks are guaranteed to belong to the same (not necessarily final) chain as this block. required: false content: application/jsonl: schema: type: array items: $ref: "#/components/schemas/Block" examples: erc20-transfer: summary: Block with ERC-20 transfer log value: - header: number: 21000042 hash: "0x1a2b3c4d5e6f..." parentHash: "0x9a8b7c6d5e4f..." timestamp: 1728000000 logs: - logIndex: 127 transactionIndex: 45 address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" topics: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" - "0x000000000000000000000000ab5801a7d398351b8be11c439e05c5b3259aec9b" - "0x00000000000000000000000061edcdf5bb737adffe5043706e7c5bb1f1a56eea" data: "0x00000000000000000000000000000000000000000000000000000000003d0900" transactionHash: "0xabc123..." transactions: [] traces: [] stateDiffs: [] "204": description: No new blocks available in the requested range - the range is entirely above the current dataset head. Not an error and the response has no body; wait and retry to keep following the chain head. The portal may wait for up to 5s before returning this. headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: Block number of the latest finalized block. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: Hash of the latest finalized block. required: false "400": description: > Invalid request or query (`error.code` is `malformed_request`; `error.param` names the request field at fault when one is). Possible causes: (1) request headers or body encoding are incorrect; (2) the query is invalid - `error.message` includes an explanation; (3) fromBlock is below the dataset's start_block (see /metadata). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: malformed_request message: "Bad request: fromBlock must be a non-negative integer" param: fromBlock "404": description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" "409": description: Parent block hash mismatch (`error.code` is `base_block_mismatch`) - the query's parentBlockHash does not match the canonical parent of the first requested block, typically after a chain reorganization. Walk the top-level previousBlocks list to find the most recent block you have already processed, roll back your data to it, then resume the stream from the next block, passing that block's hash as parentBlockHash. If nothing in the list matches your records, restart from an earlier fromBlock, again with parentBlockHash. content: application/json: schema: $ref: "#/components/schemas/ConflictResponse" "429": description: Rate limited (`error.type` is `rate_limit_error`). Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "500": description: Internal server error (`error.type` is `api_error`). Do not retry; report the error together with its request_id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: api_error code: internal_error message: Internal server error request_id: "0198c3f1-..." "502": description: A data source the Portal depends on is unavailable (`error.code` is `upstream_unavailable`) - retry later. A proxied upstream failure keeps the upstream's own 5xx status content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: upstream_unavailable message: Upstream data source is unavailable, please try again later request_id: "0198c3f1-..." "503": description: Service temporarily unavailable (`error.type` is `availability_error`, typically `no_workers` or `retries_exhausted`) - retry later. May carry Retry-After; honor it when present content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: no_workers message: No workers available for dataset request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "529": description: Overloaded (`error.code` is `overloaded`) - the Portal or a data source is at capacity. Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) /finalized-stream: post: summary: Stream Finalized Blocks operationId: streamEvmFinalizedBlocks x-mint: href: "/en/api/evm/finalized-stream" metadata: description: "Stream finalized EVM blockchain data with the SQD Portal API." x-codeSamples: - lang: shell label: ERC-20 Transfers source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "log": { "address": true, "topics": true, "data": true, "transactionHash": true, "logIndex": true } }, "logs": [{ "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }' - lang: shell label: Track NFT Transfers source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "log": { "address": true, "topics": true, "transactionHash": true } }, "logs": [{ "address": [ "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "0x60E4d786628Fea6478F785A6d7e704777c86a7c6", "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB" ], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }' - lang: shell label: Transactions source: | curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": true, "timestamp": true }, "transaction": { "hash": true, "from": true, "to": true, "value": true, "input": true, "gasUsed": true, "status": true } }, "transactions": [{ "to": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"] }] }' - lang: python label: ERC-20 Transfers source: | import requests response = requests.post( "https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-stream", json={ "type": "evm", "fromBlock": 21000000, "toBlock": 21000100, "fields": { "block": { "number": True, "timestamp": True }, "log": { "address": True, "topics": True, "data": True, "transactionHash": True, "logIndex": True } }, "logs": [{ "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] } ) blocks = response.json() - lang: javascript label: ERC-20 Transfers source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-stream", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "evm", fromBlock: 21000000, toBlock: 21000100, fields: { block: { number: true, timestamp: true }, log: { address: true, topics: true, data: true, transactionHash: true, logIndex: true } }, logs: [{ address: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], topic0: ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }] }) }); const blocks = await response.json(); description: "Streams only finalized blocks matching the provided data query (finalized data does not reorganize; a 409 here only means the provided parentBlockHash is stale). Query structure is identical to that of the /stream endpoint. Required request headers: `Content-Type: application/json`; optional request headers: `Accept-Encoding: gzip`, `Content-Encoding: gzip`." requestBody: description: "Data query to filter and retrieve finalized blocks. Request body may be gzipped (Content-Encoding: gzip)." required: true content: application/json: schema: $ref: "#/components/schemas/DataQuery" examples: erc20-transfers: summary: ERC-20 Transfers value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true log: address: true topics: true data: true transactionHash: true logIndex: true logs: - address: - "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" topic0: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" nft-transfers: summary: Track NFT Transfers value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true log: address: true topics: true transactionHash: true logs: - address: - "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" - "0x60E4d786628Fea6478F785A6d7e704777c86a7c6" - "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB" topic0: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" transactions: summary: Transactions value: type: evm fromBlock: 21000000 toBlock: 21000100 fields: block: number: true timestamp: true transaction: hash: true from: true to: true value: true input: true gasUsed: true status: true transactions: - to: - "0xdAC17F958D2ee523a2206206994597C13D831ec7" responses: "200": description: A stream of finalized blocks in JSON lines format, optionally gzipped. Can be empty if the data query has a bounded range and all blocks in the range have been skipped. content: application/jsonl: schema: type: array items: $ref: "#/components/schemas/Block" examples: erc20-transfer: summary: Block with ERC-20 transfer log value: - header: number: 21000042 hash: "0x1a2b3c4d5e6f..." parentHash: "0x9a8b7c6d5e4f..." timestamp: 1728000000 logs: - logIndex: 127 transactionIndex: 45 address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" topics: - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" - "0x000000000000000000000000ab5801a7d398351b8be11c439e05c5b3259aec9b" - "0x00000000000000000000000061edcdf5bb737adffe5043706e7c5bb1f1a56eea" data: "0x00000000000000000000000000000000000000000000000000000000003d0900" transactionHash: "0xabc123..." transactions: [] traces: [] stateDiffs: [] "204": description: No new blocks available in the requested range - the range is entirely above the current dataset head. Not an error and the response has no body; wait and retry to keep following the chain head. The portal may wait for up to 5s before returning this. "400": description: > Invalid request or query (`error.code` is `malformed_request`; `error.param` names the request field at fault when one is). Possible causes: (1) request headers or body encoding are incorrect; (2) the query is invalid - `error.message` includes an explanation; (3) fromBlock is below the dataset's start_block (see /metadata). content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: malformed_request message: "Bad request: fromBlock must be a non-negative integer" param: fromBlock "404": description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" "409": description: Parent block hash mismatch (`error.code` is `base_block_mismatch`). Finalized data does not reorganize, so the provided parentBlockHash is stale or was carried over from an unfinalized block. Recover as for /stream by walking the top-level previousBlocks list. content: application/json: schema: $ref: "#/components/schemas/ConflictResponse" "429": description: Rate limited (`error.type` is `rate_limit_error`). Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "500": description: Internal server error (`error.type` is `api_error`). Do not retry; report the error together with its request_id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: api_error code: internal_error message: Internal server error request_id: "0198c3f1-..." "502": description: A data source the Portal depends on is unavailable (`error.code` is `upstream_unavailable`) - retry later. A proxied upstream failure keeps the upstream's own 5xx status content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: upstream_unavailable message: Upstream data source is unavailable, please try again later request_id: "0198c3f1-..." "503": description: Service temporarily unavailable (`error.type` is `availability_error`, typically `no_workers` or `retries_exhausted`) - retry later. May carry Retry-After; honor it when present content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: no_workers message: No workers available for dataset request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "529": description: Overloaded (`error.code` is `overloaded`) - the Portal or a data source is at capacity. Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) /head: get: summary: Latest Block operationId: getEvmHead x-mint: href: "/en/api/evm/head" metadata: description: "Get the latest EVM block number and hash available from SQD Portal." x-codeSamples: - lang: shell label: Get Latest Ethereum Block source: | curl --compressed 'https://portal.sqd.dev/datasets/ethereum-mainnet/head' - lang: python label: Get Latest Ethereum Block source: | import requests response = requests.get( "https://portal.sqd.dev/datasets/ethereum-mainnet/head" ) head = response.json() - lang: javascript label: Get Latest Ethereum Block source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/head"); const head = await response.json(); description: "Returns the block number and hash of the highest block available in the dataset, or null if no blocks are available. Takes real-time data into account. Useful mostly for diagnostics, as clients using /stream can get this info from the X-Sqd-Finalized-Head-Number and X-Sqd-Finalized-Head-Hash response headers." responses: "200": description: Highest block information content: application/json: schema: $ref: "#/components/schemas/BlockHead" examples: ethereum-head: summary: Latest Ethereum block value: number: 26054966 hash: "0xf84ce852086978972bfa81fcb75621d1f8f74106b7ef4a690d6e373e348d4165" "404": description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" /finalized-head: get: summary: Latest Finalized Block operationId: getEvmFinalizedHead x-mint: href: "/en/api/evm/finalized-head" metadata: description: "Get the latest finalized EVM block number and hash from SQD Portal." x-codeSamples: - lang: shell label: Get Latest Finalized Ethereum Block source: | curl --compressed 'https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-head' - lang: python label: Get Latest Finalized Ethereum Block source: | import requests response = requests.get( "https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-head" ) head = response.json() - lang: javascript label: Get Latest Finalized Ethereum Block source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/finalized-head"); const head = await response.json(); description: "Returns the block number and hash of the highest finalized block available in the dataset, or null if no blocks are available. Useful mostly for diagnostics, as clients using /stream can get this info from the X-Sqd-Finalized-Head-Number and X-Sqd-Finalized-Head-Hash response headers." responses: "200": description: Highest finalized block information content: application/json: schema: $ref: "#/components/schemas/BlockHead" examples: ethereum-finalized: summary: Latest finalized Ethereum block value: number: 26054870 hash: "0xf1446d7200a26c087bec396be12ddfe5c438b5222ce4e80e9384b3306ef0aa9a" "404": description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" /timestamps/{timestamp}/block: get: summary: Block at Timestamp operationId: resolveEvmTimestampToBlock x-mint: href: "/en/api/evm/timestamp-block" metadata: description: "Resolve a Unix timestamp to an EVM block with the SQD Portal API." x-codeSamples: - lang: shell label: Resolve timestamp to block source: | curl 'https://portal.sqd.dev/datasets/ethereum-mainnet/timestamps/1693066895/block' - lang: python label: Resolve timestamp to block source: | import requests response = requests.get( "https://portal.sqd.dev/datasets/ethereum-mainnet/timestamps/1693066895/block" ) block_number = response.json()["block_number"] - lang: javascript label: Resolve timestamp to block source: | const response = await fetch("https://portal.sqd.dev/datasets/ethereum-mainnet/timestamps/1693066895/block"); const { block_number } = await response.json(); description: > Resolves a Unix timestamp (in seconds) to a block number. Returns the first block whose timestamp is greater than or equal to `timestamp`. Resolution prefers archival data and falls back to the real-time source when available; the `x-sqd-data-source` response header reports which source served the result (`network` or `real_time`). parameters: - name: timestamp in: path required: true schema: type: integer format: int64 default: 1693066895 example: 1693066895 description: Unix timestamp in seconds. responses: "200": description: Block number resolved. headers: x-sqd-data-source: schema: type: string enum: [network, real_time] description: Source that served the result. content: application/json: schema: $ref: "#/components/schemas/BlockNumberResponse" examples: "ethereum-mainnet": summary: First block at or after the timestamp value: block_number: 18000000 "400": description: Unparseable `timestamp` path segment (`error.code` is `malformed_request`), or the real-time source refused the query the Portal generated on the client's behalf; read `error.message` content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: malformed_request message: "Bad request: fromBlock must be a non-negative integer" param: fromBlock "404": description: No block at or after the given timestamp yet (`error.code` is `not_found`) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: invalid_request_error code: not_found message: No block at or after the given timestamp "429": description: Rate limited (`error.type` is `rate_limit_error`). Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "500": description: Internal server error (`error.type` is `api_error`). Do not retry; report the error together with its request_id content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: api_error code: internal_error message: Internal server error request_id: "0198c3f1-..." "502": description: A data source the Portal depends on is unavailable (`error.code` is `upstream_unavailable`) - retry later. A proxied upstream failure keeps the upstream's own 5xx status content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: upstream_unavailable message: Upstream data source is unavailable, please try again later request_id: "0198c3f1-..." "503": description: Service temporarily unavailable (`error.type` is `availability_error`, typically `no_workers` or `retries_exhausted`) - retry later. May carry Retry-After; honor it when present content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: availability_error code: no_workers message: No workers available for dataset request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) "529": description: Overloaded (`error.code` is `overloaded`) - the Portal or a data source is at capacity. Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later request_id: "0198c3f1-..." headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) components: schemas: BlockNumberResponse: type: object properties: block_number: type: integer format: int64 description: Number of the first block whose timestamp is greater than or equal to the requested timestamp. example: 18000000 required: - block_number DatasetMetadata: type: object properties: dataset: type: string description: The default name used to reference this dataset (e.g., ethereum-mainnet). example: "ethereum-mainnet" aliases: type: array items: type: string description: Alternative names for the dataset. example: [] real_time: type: boolean description: Indicates if the dataset has real-time data. example: true start_block: type: integer format: int64 description: The block number of the first known block. example: 0 required: - dataset - aliases - real_time DatasetState: type: object properties: worker_ranges: type: object description: Keys are workers' peer IDs. additionalProperties: type: object properties: ranges: type: array items: type: object properties: begin: type: integer format: int64 end: type: integer format: int64 required: - begin - end highest_seen_block: type: integer format: uint64 description: The highest block number seen in the dataset. first_gap: type: integer format: uint64 description: The first block number where a gap in data exists, if any. required: - worker_ranges - highest_seen_block DataQuery: type: object properties: type: type: string enum: ["evm"] default: "evm" description: The type of blockchain data (fixed to EVM for this API). fromBlock: type: integer format: int64 description: The block number to start fetching from (inclusive). toBlock: type: integer format: int64 description: The block number to fetch up to (inclusive). Optional; if omitted, streams until dataset height or timeout. parentBlockHash: type: string description: Expected hash of the parent of the first requested block. includeAllBlocks: type: boolean description: If true, includes blocks with no matching data in the response. default: false fields: type: object description: Field selector for data items to retrieve. properties: block: type: object description: Field selector for block headers. properties: hash: type: boolean description: Block hash. number: type: boolean description: Block number. parentHash: type: boolean description: Hash of the parent block. timestamp: type: boolean description: Block timestamp in unix seconds. nonce: type: boolean description: Block nonce used in proof-of-work. sha3Uncles: type: boolean description: Hash of the list of uncle block headers. uncles: type: boolean description: Hashes of the block's uncle (ommer) headers; empty on post-Merge/L2/sidechains. logsBloom: type: boolean description: Bloom filter for logs in this block. transactionsRoot: type: boolean description: Root hash of the transactions trie. stateRoot: type: boolean description: Root hash of the state trie. receiptsRoot: type: boolean description: Root hash of the receipts trie. mixHash: type: boolean description: Hash used in the proof-of-work algorithm. miner: type: boolean description: Address of the block producer. difficulty: type: boolean description: Block difficulty value. totalDifficulty: type: boolean description: Cumulative difficulty of the chain up to this block. extraData: type: boolean description: Arbitrary data included by the block producer. size: type: boolean description: Block size in bytes. gasLimit: type: boolean description: Maximum gas allowed in this block. gasUsed: type: boolean description: Total gas used by all transactions in this block. baseFeePerGas: type: boolean description: Base fee per gas for this block (EIP-1559). withdrawalsRoot: type: boolean description: Root of the block's withdrawals trie (post-Shanghai). withdrawals: type: boolean description: Validator withdrawals included in the block (post-Shanghai). blobGasUsed: type: boolean description: Total blob gas consumed by the block (post-Cancun). excessBlobGas: type: boolean description: Running excess blob gas for the block (post-Cancun). parentBeaconBlockRoot: type: boolean description: Parent beacon block root (EIP-4788, post-Cancun). requestsHash: type: boolean description: Commitment to the block's execution-layer requests (EIP-7685, post-Prague). l1BlockNumber: type: boolean description: L1 block number for L2 networks. default: hash: true number: true parentHash: true transaction: type: object description: Field selector for transactions. properties: transactionIndex: type: boolean description: Index of the transaction in the block. from: type: boolean description: Sender address. to: type: boolean description: Recipient address. hash: type: boolean description: Transaction hash. gas: type: boolean description: Gas limit provided by the sender. gasPrice: type: boolean description: Gas price in wei provided by the sender. maxFeePerGas: type: boolean description: Maximum fee per gas the sender is willing to pay (EIP-1559). maxPriorityFeePerGas: type: boolean description: Maximum priority fee per gas (EIP-1559). input: type: boolean description: Call data sent with the transaction. nonce: type: boolean description: Number of transactions sent by the sender prior to this one. value: type: boolean description: Value transferred in wei. v: type: boolean description: ECDSA recovery id. r: type: boolean description: ECDSA signature r value. s: type: boolean description: ECDSA signature s value. yParity: type: boolean description: Parity of the y-coordinate of the public key (EIP-2930). chainId: type: boolean description: Chain ID specified by the transaction. gasUsed: type: boolean description: Gas used by this transaction. cumulativeGasUsed: type: boolean description: Total gas used in the block up to and including this transaction. effectiveGasPrice: type: boolean description: Actual gas price paid per unit of gas. contractAddress: type: boolean description: Address of the contract created, if this is a contract creation transaction. type: type: boolean description: Transaction type (0 for legacy, 2 for EIP-1559). status: type: boolean description: Transaction status (1 for success, 0 for failure). accessList: type: boolean description: EIP-2930 access list (type-1 and type-2 transactions). logsBloom: type: boolean description: Bloom filter over the logs emitted by this transaction's receipt. sighash: type: boolean description: First 4 bytes of the transaction input (function selector). l1Fee: type: boolean description: L1 fee for L2 transactions. l1FeeScalar: type: boolean description: L1 fee scalar for L2 transactions. l1GasPrice: type: boolean description: L1 gas price for L2 transactions. l1GasUsed: type: boolean description: L1 gas used for L2 transactions. l1BlobBaseFee: type: boolean description: L1 blob base fee for L2 transactions. l1BlobBaseFeeScalar: type: boolean description: L1 blob base fee scalar for L2 transactions. l1BaseFeeScalar: type: boolean description: L1 base fee scalar for L2 transactions. maxFeePerBlobGas: type: boolean description: Max fee per blob gas the sender will pay (type-3 blob transactions). blobVersionedHashes: type: boolean description: Versioned hashes committing to the transaction's blobs (type-3 blob transactions). blobGasUsed: type: boolean description: Blob gas used by this transaction (type-3 blob transactions). blobGasPrice: type: boolean description: Blob gas price paid by this transaction (type-3 blob transactions). default: hash: true log: type: object description: Field selector for logs. properties: logIndex: type: boolean description: Index of the log in the block. transactionIndex: type: boolean description: Index of the parent transaction in the block. address: type: boolean description: Contract address that emitted the log. data: type: boolean description: Non-indexed log data. topics: type: boolean description: Indexed log topics. transactionHash: type: boolean description: Hash of the parent transaction. default: topics: true trace: type: object description: Field selector for traces. properties: transactionIndex: type: boolean description: Index of the parent transaction in the block. traceAddress: type: boolean description: Position of this trace in the trace tree. type: type: boolean description: Trace type (create, call, suicide, or reward). subtraces: type: boolean description: Number of child traces. error: type: boolean description: Error message if the trace reverted. createFrom: type: boolean description: Address that initiated the contract creation. createValue: type: boolean description: Value sent with the contract creation in wei (hex-encoded in the raw response, returned as action.value). createGas: type: boolean description: Gas provided for the contract creation. createInit: type: boolean description: Initialization bytecode for the contract creation. createResultGasUsed: type: boolean description: Gas used by the contract creation. createResultCode: type: boolean description: Deployed bytecode from the contract creation. createResultAddress: type: boolean description: Address of the newly created contract. callFrom: type: boolean description: Address that initiated the call. callTo: type: boolean description: Address that received the call. callValue: type: boolean description: Value sent with the call in wei (hex-encoded in the raw response, returned as action.value). callGas: type: boolean description: Gas provided for the call. callSighash: type: boolean description: Function selector (first 4 bytes of input) for the call. callInput: type: boolean description: Input data for the call. callResultGasUsed: type: boolean description: Gas used by the call. callResultOutput: type: boolean description: Output data returned by the call. suicideAddress: type: boolean description: Address of the self-destructed contract. suicideRefundAddress: type: boolean description: Address that received the remaining balance. suicideBalance: type: boolean description: Balance sent to the refund address. rewardAuthor: type: boolean description: Address that received the block reward. rewardValue: type: boolean description: Reward amount in wei. rewardType: type: boolean description: Type of reward (block or uncle). stateDiff: type: object description: Field selector for state diffs. properties: transactionIndex: type: boolean description: Index of the parent transaction in the block. address: type: boolean description: Address of the account or contract whose state changed. key: type: boolean description: Storage key or special key (balance, code, nonce). kind: type: boolean description: "Type of state change: = (unchanged), + (added), * (modified), - (removed)." prev: type: boolean description: Previous value before the state change. next: type: boolean description: New value after the state change. logs: type: array description: Log data requests. items: type: object properties: address: type: array items: type: string description: Contract addresses emitting the logs (lowercase). topic0: type: array items: type: string description: First topic of the log (e.g., event signature). topic1: type: array items: type: string topic2: type: array items: type: string topic3: type: array items: type: string transaction: type: boolean description: Fetch parent transactions for matching logs. transactionTraces: type: boolean description: Fetch traces for parent transactions. transactionLogs: type: boolean description: Fetch all logs emitted by parent transactions. description: An empty object matches all logs; an empty array matches no logs. transactions: type: array description: Transaction data requests. items: type: object properties: from: type: array items: type: string description: Sender addresses (lowercase). to: type: array items: type: string description: Recipient addresses (lowercase). sighash: type: array items: type: string description: Function signature hashes (e.g., 0xa9059cbb for transfer). logs: type: boolean description: Fetch all logs emitted by matching transactions. traces: type: boolean description: Fetch all traces for matching transactions. stateDiffs: type: boolean description: Fetch all state diffs caused by matching transactions. description: An empty object matches all transactions; an empty array matches no transactions. traces: type: array description: Trace data requests. items: type: object properties: type: type: array items: type: string enum: ["create", "call", "suicide", "reward"] description: Type of trace. createFrom: type: array items: type: string description: Address initiating a create trace. callFrom: type: array items: type: string description: Address initiating a call trace. callTo: type: array items: type: string description: Address receiving a call trace. callSighash: type: array items: type: string description: Function signature hash for call traces. suicideRefundAddress: type: array items: type: string description: Refund address for suicide traces. rewardAuthor: type: array items: type: string description: Author receiving a reward trace. transaction: type: boolean description: Fetch parent transactions for matching traces. transactionLogs: type: boolean description: Fetch all logs emitted by parent transactions. subtraces: type: boolean description: Fetch all subtraces of matching traces. parents: type: boolean description: Fetch parent traces of matching traces. description: An empty object matches all traces; an empty array matches no traces. stateDiffs: type: array description: State diff data requests. items: type: object properties: address: type: array items: type: string description: Contract or account addresses (lowercase). key: type: array items: type: string description: Storage keys or special keys (balance, code, nonce). kind: type: array items: type: string enum: ["=", "+", "*", "-"] description: Type of state change. transaction: type: boolean description: Fetch parent transactions for matching state diffs. description: An empty object matches all state diffs; an empty array matches no state diffs. required: - type - fromBlock Block: type: object properties: header: type: object description: Block header data. Fields are conditionally returned based on the `fields.block` parameter in the request. Only requested fields will be included in the response. properties: number: type: integer format: uint64 description: Block number. hash: type: string description: Block hash. parentHash: type: string description: Parent block hash. timestamp: type: integer description: Block timestamp. nonce: type: string description: Block nonce. sha3Uncles: type: string description: Keccak hash of the uncles (ommers) data in the block. uncles: type: array items: type: string description: Hashes of the block's uncle (ommer) headers. Empty on chains without uncles (e.g. post-Merge Ethereum and most L2s/sidechains). logsBloom: type: string transactionsRoot: type: string stateRoot: type: string receiptsRoot: type: string mixHash: type: string miner: type: string difficulty: type: integer format: uint64 totalDifficulty: type: integer format: uint64 extraData: type: string size: type: integer format: uint64 gasLimit: type: integer format: uint64 gasUsed: type: integer format: uint64 baseFeePerGas: type: integer format: uint64 withdrawalsRoot: type: string description: Root of the block's withdrawals trie (post-Shanghai). withdrawals: type: array description: Validator withdrawals included in the block (post-Shanghai). items: type: object properties: index: type: integer format: uint64 description: Withdrawal index, monotonically increasing across the chain. validatorIndex: type: integer format: uint64 description: Index of the validator that produced the withdrawal. address: type: string description: Recipient address (lowercase). amount: type: integer format: uint64 description: Withdrawn amount in Gwei. blobGasUsed: type: integer format: uint64 description: Total blob gas consumed by the block (post-Cancun). excessBlobGas: type: integer format: uint64 description: Running excess blob gas, used to compute the block's blob base fee (post-Cancun). parentBeaconBlockRoot: type: string description: Root of the parent beacon block (EIP-4788, post-Cancun). Null on chains without a beacon chain. requestsHash: type: string description: Commitment to the execution-layer requests included in the block (EIP-7685, post-Prague). Null on chains that have not enabled it. l1BlockNumber: type: integer description: L1 block number for L2 networks. transactions: type: array items: type: object properties: transactionIndex: type: integer description: Index of the transaction in the block. from: type: string description: Sender address (lowercase). to: type: string description: Recipient address (lowercase). hash: type: string description: Transaction hash. gas: type: integer format: uint64 gasPrice: type: integer format: uint64 maxFeePerGas: type: integer format: uint64 maxPriorityFeePerGas: type: integer format: uint64 input: type: string accessList: type: array description: EIP-2930 access list (type-1 and type-2 transactions). Empty for transactions without one. items: type: object properties: address: type: string description: Address whose storage is pre-warmed (lowercase). storageKeys: type: array items: type: string description: Storage slot keys pre-warmed for the address. nonce: type: integer value: type: integer format: uint64 v: type: integer format: uint64 r: type: string s: type: string yParity: type: integer chainId: type: integer gasUsed: type: integer format: uint64 cumulativeGasUsed: type: integer format: uint64 effectiveGasPrice: type: integer format: uint64 contractAddress: type: string type: type: integer description: Transaction type (e.g., 0 for legacy, 2 for EIP-1559). status: type: integer description: Transaction status (1 for success, 0 for failure). logsBloom: type: string description: Bloom filter over the logs emitted by this transaction's receipt. sighash: type: string l1Fee: type: integer format: uint64 l1FeeScalar: type: number l1GasPrice: type: integer format: uint64 l1GasUsed: type: integer format: uint64 l1BlobBaseFee: type: integer format: uint64 l1BlobBaseFeeScalar: type: number l1BaseFeeScalar: type: number maxFeePerBlobGas: type: integer format: uint64 description: Maximum fee per blob gas the sender is willing to pay (type-3 blob transactions). blobVersionedHashes: type: array items: type: string description: Versioned hashes committing to the transaction's blobs (type-3 blob transactions). blobGasUsed: type: integer format: uint64 description: Blob gas used by this transaction (type-3 blob transactions). blobGasPrice: type: integer format: uint64 description: Blob gas price paid by this transaction (type-3 blob transactions). logs: type: array items: type: object properties: logIndex: type: integer description: Index of the log in the block. transactionIndex: type: integer description: Index of the parent transaction. address: type: string description: Contract address emitting the log (lowercase). data: type: string description: Log data. topics: type: array items: type: string description: Log topics. transactionHash: type: string description: Hash of the parent transaction. traces: type: array items: type: object properties: transactionIndex: type: integer description: Index of the parent transaction. traceAddress: type: array items: type: integer description: Address of the trace in the trace tree. type: type: string enum: ["create", "call", "suicide", "reward"] description: Type of trace. subtraces: type: integer description: Number of subtraces. error: type: string description: Error message, if any. action: type: object properties: from: type: string description: Initiator address for create/call. value: type: string description: Value transferred, hex-encoded wei (e.g. "0x0"). gas: type: string description: Gas provided, hex-encoded. init: type: string description: Initialization code for create. to: type: string description: Recipient address for call. sighash: type: string description: Function signature hash for call. input: type: string description: Input data for call. address: type: string description: Contract address for suicide. refundAddress: type: string description: Refund address for suicide. balance: type: string description: Balance for suicide, hex-encoded wei. author: type: string description: Reward recipient. rewardType: type: string description: Type of reward. result: type: object properties: gasUsed: type: string description: Gas used by create/call, hex-encoded. code: type: string description: Deployed code for create. address: type: string description: Created contract address. output: type: string description: Output data for call. stateDiffs: type: array items: type: object properties: transactionIndex: type: integer description: Index of the parent transaction. address: type: string description: Contract or account address (lowercase). key: type: string description: Storage key or special key (balance, code, nonce). kind: type: string enum: ["=", "+", "*", "-"] description: Type of state change. prev: type: string description: Previous value. next: type: string description: New value. BlockHead: type: [object, "null"] properties: number: type: integer format: int64 description: Block number of the highest available block. example: 26054966 hash: type: string description: Hash of the highest available block. example: "0xf84ce852086978972bfa81fcb75621d1f8f74106b7ef4a690d6e373e348d4165" ErrorDetail: type: object description: Machine-readable error detail. Branch on `type`; match on `code` for one specific case. properties: type: type: string description: Coarse category to branch on. One of `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, `availability_error`, or `api_error`. The two credential types answer 403 and appear only on a Portal that requires an API key. Treat an unknown `code` according to its `type`. example: invalid_request_error code: type: string description: Specific cause, stable across releases. Match on this rather than on `message`. example: base_block_mismatch message: type: string description: Human-readable detail. Prose, not stable; do not parse or match on it. param: type: string description: The request parameter at fault, when the error is about one. request_id: type: string description: Echo of the `x-request-id` response header, included in the body on 5xx errors. Quote it when reporting a problem. required: - type - code - message ErrorResponse: type: object description: Error body shared by every failing response. properties: error: $ref: "#/components/schemas/ErrorDetail" required: - error example: error: type: invalid_request_error code: unknown_dataset message: "Unknown dataset: no-such-chain" ConflictResponse: type: object description: The 409 body carries the standard error envelope plus a top-level `previousBlocks` list - a slice of the current canonical chain at and below the conflict point, in ascending block-number order. properties: error: $ref: "#/components/schemas/ErrorDetail" previousBlocks: type: array description: "`{ number, hash }` pairs from the current canonical chain in ascending order; the last entry is the most recent block at or below the conflict point. Guaranteed to contain at least the parent of the requested fromBlock." items: type: object properties: number: type: integer format: int64 hash: type: string required: - number - hash required: - error - previousBlocks example: error: type: invalid_request_error code: base_block_mismatch message: Base block mismatch previousBlocks: - number: 26054870 hash: "0xf1446d7200a26c087bec396be12ddfe5c438b5222ce4e80e9384b3306ef0aa9a" - number: 26054966 hash: "0xf84ce852086978972bfa81fcb75621d1f8f74106b7ef4a690d6e373e348d4165"