openapi: 3.1.0
info:
  title: SQD Portal API - Substrate Dataset Endpoints
  description: API endpoints for interacting with Substrate datasets under the SQD Portal, specifically for the Polkadot dataset.
  version: 1.0.0
servers:
  - url: https://portal.sqd.dev/datasets/polkadot
    description: SQD Portal's endpoint for Polkadot
paths:
  /metadata:
    get:
      summary: Dataset Metadata
      operationId: getSubstrateDatasetMetadata
      x-mint:
        href: "/en/api/substrate/metadata"
        metadata:
          description: "Get Substrate dataset metadata from the SQD Portal API."
      x-codeSamples:
        - lang: shell
          source: |
            curl --compressed 'https://portal.sqd.dev/datasets/polkadot/metadata'
        - lang: python
          label: "Dataset Metadata"
          source: |
            import requests

            response = requests.get(
                "https://portal.sqd.dev/datasets/polkadot/metadata"
            )
            data = response.json()
        - lang: javascript
          label: "Dataset Metadata"
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/metadata");
            const data = 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"
        "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: streamSubstrateBlocks
      x-mint:
        href: "/en/api/substrate/stream"
        metadata:
          description: "Stream Substrate blockchain data with the SQD Portal API."

      x-codeSamples:
        - lang: shell
          label: Query Balances.Transfer Events
          source: |
            curl --compressed -X POST 'https://portal.sqd.dev/datasets/polkadot/stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "event": {
                    "name": true,
                    "args": true
                  }
                },
                "events": [{
                  "name": ["Balances.Transfer"]
                }]
              }'
        - lang: shell
          label: Query Calls with Extrinsics
          source: |
            curl --compressed -X POST 'https://portal.sqd.dev/datasets/polkadot/stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "call": {
                    "name": true,
                    "args": true,
                    "success": true
                  },
                  "extrinsic": {
                    "hash": true,
                    "fee": true,
                    "success": true
                  }
                },
                "calls": [{
                  "name": ["Balances.transfer_keep_alive"],
                  "extrinsic": true
                }]
              }'
        - lang: shell
          label: Query EVM.Log Events (Frontier)
          source: |
            curl --compressed -X POST 'https://portal.sqd.dev/datasets/astar-substrate/stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 5000000,
                "toBlock": 5000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "event": {
                    "name": true,
                    "args": true
                  }
                },
                "evmLogs": [{
                  "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
                }]
              }'
        - lang: python
          label: "Query Balances.Transfer Events"
          source: |
            import requests

            response = requests.post(
                "https://portal.sqd.dev/datasets/polkadot/stream",
                json={
                    "type": "substrate",
                    "fromBlock": 20000000,
                    "toBlock": 20000100,
                    "fields": {
                        "block": {
                            "number": True,
                            "timestamp": True
                        },
                        "event": {
                            "name": True,
                            "args": True
                        }
                    },
                    "events": [{
                        "name": ["Balances.Transfer"]
                    }]
                }
            )
            data = response.json()
        - lang: javascript
          label: "Query Balances.Transfer Events"
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/stream", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    type: "substrate",
                    fromBlock: 20000000,
                    toBlock: 20000100,
                    fields: {
                        block: {
                            number: true,
                            timestamp: true
                        },
                        event: {
                            name: true,
                            args: true
                        }
                    },
                    events: [{
                        name: ["Balances.Transfer"]
                    }]
                })
            });
            const data = await response.json();
      description: "Streams a list of blocks matching the provided data query. Substrate datasets contain only finalized blocks. 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:
              balances-transfer:
                summary: Query Balances.Transfer Events
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    event:
                      name: true
                      args: true
                  events:
                    - name:
                        - "Balances.Transfer"
              calls-with-extrinsics:
                summary: Query Calls with Extrinsics
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    call:
                      name: true
                      args: true
                      success: true
                    extrinsic:
                      hash: true
                      fee: true
                      success: true
                  calls:
                    - name:
                        - "Balances.transfer_keep_alive"
                      extrinsic: true
              evm-logs:
                summary: Query EVM.Log Events (Frontier)
                value:
                  type: substrate
                  fromBlock: 5000000
                  toBlock: 5000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    event:
                      name: true
                      args: true
                  evmLogs:
                    - topic0:
                        - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      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:
                balances-transfer-response:
                  summary: Balances.Transfer events response
                  value:
                    - header:
                        number: 20000050
                        hash: "0xabc123def456789abc123def456789abc123def456789abc123def456789abcd"
                        parentHash: "0x789012abc345678901234567890123456789012345678901234567890123abcd"
                        timestamp: 1700000000000
                      events:
                        - index: 3
                          extrinsicIndex: 1
                          name: "Balances.Transfer"
                          phase: "ApplyExtrinsic"
                          args:
                            from: "15oF4uVJwmo4TdGW7VfQxNLavjCXviqWrztPu9BFKHEtaqry"
                            to: "14E5nqKAp3oAJcg4aM6hEYyLT2JAPi6ixST1VRkNg8wAKPe"
                            amount: "10000000000"
        "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: streamSubstrateFinalizedBlocks
      x-mint:
        href: "/en/api/substrate/finalized-stream"
        metadata:
          description: "Stream finalized Substrate blockchain data with the SQD Portal API."

      x-codeSamples:
        - lang: shell
          label: Query Balances.Transfer Events
          source: |
            curl --compressed -X POST 'https://portal.sqd.dev/datasets/polkadot/finalized-stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "event": {
                    "name": true,
                    "args": true
                  }
                },
                "events": [{
                  "name": ["Balances.Transfer"]
                }]
              }'
        - lang: shell
          label: Query Calls with Extrinsics
          source: |
            curl --compressed -X POST 'https://portal.sqd.dev/datasets/polkadot/finalized-stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "call": {
                    "name": true,
                    "args": true,
                    "success": true
                  },
                  "extrinsic": {
                    "hash": true,
                    "fee": true,
                    "success": true
                  }
                },
                "calls": [{
                  "name": ["Balances.transfer_keep_alive"],
                  "extrinsic": true
                }]
              }'
        - lang: python
          label: "Query Balances.Transfer Events"
          source: |
            import requests

            response = requests.post(
                "https://portal.sqd.dev/datasets/polkadot/finalized-stream",
                json={
                    "type": "substrate",
                    "fromBlock": 20000000,
                    "toBlock": 20000100,
                    "fields": {
                        "block": {
                            "number": True,
                            "timestamp": True
                        },
                        "event": {
                            "name": True,
                            "args": True
                        }
                    },
                    "events": [{
                        "name": ["Balances.Transfer"]
                    }]
                }
            )
            data = response.json()
        - lang: javascript
          label: "Query Balances.Transfer Events"
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/finalized-stream", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    type: "substrate",
                    fromBlock: 20000000,
                    toBlock: 20000100,
                    fields: {
                        block: {
                            number: true,
                            timestamp: true
                        },
                        event: {
                            name: true,
                            args: true
                        }
                    },
                    events: [{
                        name: ["Balances.Transfer"]
                    }]
                })
            });
            const data = 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 blocks. Request body may be gzipped (Content-Encoding: gzip)."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataQuery"
            examples:
              balances-transfer:
                summary: Query Balances.Transfer Events
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    event:
                      name: true
                      args: true
                  events:
                    - name:
                        - "Balances.Transfer"
              calls-with-extrinsics:
                summary: Query Calls with Extrinsics
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    call:
                      name: true
                      args: true
                      success: true
                    extrinsic:
                      hash: true
                      fee: true
                      success: true
                  calls:
                    - name:
                        - "Balances.transfer_keep_alive"
                      extrinsic: true
      responses:
        "200":
          description: A stream of finalized blocks in JSON lines format, optionally gzipped. Never returns blocks above the finalized head.
          content:
            application/jsonl:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Block"
              examples:
                balances-transfer-response:
                  summary: Balances.Transfer finalized events response
                  value:
                    - header:
                        number: 20000050
                        hash: "0xabc123def456789abc123def456789abc123def456789abc123def456789abcd"
                        parentHash: "0x789012abc345678901234567890123456789012345678901234567890123abcd"
                        timestamp: 1700000000000
                      events:
                        - index: 3
                          extrinsicIndex: 1
                          name: "Balances.Transfer"
                          phase: "ApplyExtrinsic"
                          args:
                            from: "15oF4uVJwmo4TdGW7VfQxNLavjCXviqWrztPu9BFKHEtaqry"
                            to: "14E5nqKAp3oAJcg4aM6hEYyLT2JAPi6ixST1VRkNg8wAKPe"
                            amount: "10000000000"
        "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: Dataset Head
      operationId: getSubstrateHead
      x-mint:
        href: "/en/api/substrate/head"
        metadata:
          description: "Get the latest Substrate block number and hash available from SQD Portal."

      x-codeSamples:
        - lang: shell
          source: |
            curl --compressed 'https://portal.sqd.dev/datasets/polkadot/head'
        - lang: python
          label: "Dataset Head"
          source: |
            import requests

            response = requests.get(
                "https://portal.sqd.dev/datasets/polkadot/head"
            )
            data = response.json()
        - lang: javascript
          label: "Dataset Head"
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/head");
            const data = 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. 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: Block head info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockHead"
        "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: Finalized Dataset Head
      operationId: getSubstrateFinalizedHead
      x-mint:
        href: "/en/api/substrate/finalized-head"
        metadata:
          description: "Get the latest finalized Substrate block number and hash from SQD Portal."

      x-codeSamples:
        - lang: shell
          source: |
            curl --compressed 'https://portal.sqd.dev/datasets/polkadot/finalized-head'
        - lang: python
          label: "Finalized Dataset Head"
          source: |
            import requests

            response = requests.get(
                "https://portal.sqd.dev/datasets/polkadot/finalized-head"
            )
            data = response.json()
        - lang: javascript
          label: "Finalized Dataset Head"
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/finalized-head");
            const data = 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: Finalized block head info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockHead"
        "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: resolveSubstrateTimestampToBlock
      x-mint:
        href: "/en/api/substrate/timestamp-block"
        metadata:
          description: "Resolve a Unix timestamp to a Substrate block with the SQD Portal API."
      x-codeSamples:
        - lang: shell
          label: Resolve timestamp to block
          source: |
            curl 'https://portal.sqd.dev/datasets/polkadot/timestamps/1700000000/block'
        - lang: python
          label: Resolve timestamp to block
          source: |
            import requests

            response = requests.get(
                "https://portal.sqd.dev/datasets/polkadot/timestamps/1700000000/block"
            )
            block_number = response.json()["block_number"]
        - lang: javascript
          label: Resolve timestamp to block
          source: |
            const response = await fetch("https://portal.sqd.dev/datasets/polkadot/timestamps/1700000000/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: 1700000000
            example: 1700000000
          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:
                "polkadot":
                  summary: First block at or after the timestamp
                  value:
                    block_number: 18169650
        "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
        aliases:
          type: array
          items:
            type: string
          description: Alternative names for the dataset
        real_time:
          type: boolean
          description: Indicates if the dataset has real-time data
        start_block:
          type: integer
          format: int64
          description: The block number of the first known block
      required:
        - dataset
        - aliases
        - real_time
    DataQuery:
      type: object
      properties:
        type:
          type: string
          enum: ["substrate"]
          default: "substrate"
        fromBlock:
          type: integer
          format: int64
          description: The number of the first block to fetch. If unsure how far into the past this can go consult /metadata
          default: 20000000
        toBlock:
          type: integer
          format: int64
          description: "The block number to fetch up to (inclusive). Optional; if omitted, streams until dataset height or timeout."
          default: 20000100
        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
          default: false
        fields:
          type: object
          description: Field selector. See the HTTP 200 response description for details on fields that aren't self-explanatory
          properties:
            block:
              type: object
              description: Field selector for block headers (the .header objects of JSON block records)
              properties:
                number:
                  type: boolean
                  description: Block number
                hash:
                  type: boolean
                  description: Block hash
                parentHash:
                  type: boolean
                  description: Hash of the parent block
                stateRoot:
                  type: boolean
                  description: Root hash of the state trie after this block
                extrinsicsRoot:
                  type: boolean
                  description: Root hash of the extrinsics trie for this block
                digest:
                  type: boolean
                  description: Block digest as JSON object
                specName:
                  type: boolean
                  description: Runtime spec name
                specVersion:
                  type: boolean
                  description: Runtime spec version
                implName:
                  type: boolean
                  description: Runtime implementation name
                implVersion:
                  type: boolean
                  description: Runtime implementation version
                validator:
                  type: boolean
                  description: Block validator/author address
                timestamp:
                  type: boolean
                  description: Block timestamp in milliseconds since Unix epoch
            extrinsic:
              type: object
              description: Field selector for extrinsics
              properties:
                index:
                  type: boolean
                  description: Index of the extrinsic in the block
                version:
                  type: boolean
                  description: Extrinsic format version
                success:
                  type: boolean
                  description: Whether the extrinsic executed successfully
                hash:
                  type: boolean
                  description: Extrinsic hash
                fee:
                  type: boolean
                  description: Extrinsic fee as a decimal string
                tip:
                  type: boolean
                  description: Extrinsic tip as a decimal string
                signature:
                  type: boolean
                  description: Extrinsic signature as JSON object
                error:
                  type: boolean
                  description: Extrinsic error as JSON object (if failed)
            call:
              type: object
              description: Field selector for calls
              properties:
                extrinsicIndex:
                  type: boolean
                  description: Index of the parent extrinsic in the block
                address:
                  type: boolean
                  description: Call address within the extrinsic call tree (array of integers)
                name:
                  type: boolean
                  description: "Qualified call name (e.g. Balances.transfer_keep_alive)"
                success:
                  type: boolean
                  description: Whether the call executed successfully
                args:
                  type: boolean
                  description: Call arguments as JSON
                origin:
                  type: boolean
                  description: Call origin as JSON
                error:
                  type: boolean
                  description: Call error as JSON (if failed)
            event:
              type: object
              description: Field selector for events
              properties:
                index:
                  type: boolean
                  description: Index of the event in the block
                extrinsicIndex:
                  type: boolean
                  description: Index of the parent extrinsic in the block
                name:
                  type: boolean
                  description: "Qualified event name (e.g. Balances.Transfer)"
                phase:
                  type: boolean
                  description: Event phase (ApplyExtrinsic, Finalization, Initialization)
                callAddress:
                  type: boolean
                  description: Address of the call that emitted this event
                topics:
                  type: boolean
                  description: Event topics as an array of hex strings
                args:
                  type: boolean
                  description: Event arguments as JSON
          default:
            block:
              number: true
              hash: true
              parentHash: true
            event:
              name: true
            call:
              name: true
        events:
          type: array
          description: Event data requests. An empty object matches all events; an empty array matches no events
          items:
            type: object
            properties:
              name:
                description: "Filter by qualified event name (e.g. Balances.Transfer)"
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack (all parent calls) for matching events
                type: boolean
        calls:
          type: array
          description: Call data requests. An empty object matches all calls; an empty array matches no calls
          items:
            type: object
            properties:
              name:
                description: "Filter by qualified call name (e.g. Balances.transfer_keep_alive)"
                type: array
                items:
                  type: string
              subcalls:
                description: Fetch all child calls (subcalls) for matching calls
                type: boolean
              extrinsic:
                description: Fetch parent extrinsics for matching calls
                type: boolean
              stack:
                description: Fetch all parent calls in the call tree
                type: boolean
              events:
                description: Fetch all events emitted by matching calls
                type: boolean
        evmLogs:
          type: array
          description: "EVM.Log event requests for Frontier EVM parachains (e.g. Astar). Filters on EVM.Log events specifically"
          items:
            type: object
            properties:
              address:
                description: Filter by EVM contract address (lowercase hex)
                type: array
                items:
                  type: string
              topic0:
                description: Filter by first topic (event signature hash)
                type: array
                items:
                  type: string
              topic1:
                description: Filter by second topic
                type: array
                items:
                  type: string
              topic2:
                description: Filter by third topic
                type: array
                items:
                  type: string
              topic3:
                description: Filter by fourth topic
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        ethereumTransactions:
          type: array
          description: "Ethereum.transact call requests for Frontier EVM parachains. Filters on Ethereum.transact calls specifically"
          items:
            type: object
            properties:
              to:
                description: Filter by destination EVM contract address (lowercase hex)
                type: array
                items:
                  type: string
              sighash:
                description: Filter by function signature hash (4-byte hex)
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching calls
                type: boolean
              stack:
                description: Fetch all parent calls in the call tree
                type: boolean
              events:
                description: Fetch all events emitted by matching calls
                type: boolean
        contractsEvents:
          type: array
          description: "Contracts.ContractEmitted event requests for ink! smart contracts. Contract addresses must be hexadecimal (decoded from SS58) and lowercase"
          items:
            type: object
            properties:
              contractAddress:
                description: Filter by contract address (hexadecimal, lowercase)
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        gearMessagesEnqueued:
          type: array
          description: "Gear.UserMessageEnqueued event requests for Gear/Vara networks"
          items:
            type: object
            properties:
              programId:
                description: Filter by Gear program ID
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        gearUserMessagesSent:
          type: array
          description: "Gear.UserMessageSent event requests for Gear/Vara networks"
          items:
            type: object
            properties:
              programId:
                description: Filter by Gear program ID
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        reviveContractEmitted:
          type: array
          description: "Revive.ContractEmitted event requests for Revive smart contracts"
          items:
            type: object
            properties:
              contract:
                description: Filter by contract address
                type: array
                items:
                  type: string
              topic0:
                description: Filter by first topic
                type: array
                items:
                  type: string
              topic1:
                description: Filter by second topic
                type: array
                items:
                  type: string
              topic2:
                description: Filter by third topic
                type: array
                items:
                  type: string
              topic3:
                description: Filter by fourth topic
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
      required:
        - fromBlock
    Block:
      type: object
      properties:
        header:
          type: object
          properties:
            number:
              type: integer
              format: uint64
            hash:
              type: string
            parentHash:
              type: string
            stateRoot:
              type: string
            extrinsicsRoot:
              type: string
            digest:
              type: object
              description: Block digest containing consensus engine data
            specName:
              type: string
              description: Runtime spec name
            specVersion:
              type: integer
              description: Runtime spec version
            implName:
              type: string
              description: Runtime implementation name
            implVersion:
              type: integer
              description: Runtime implementation version
            validator:
              type: string
              description: Block validator/author address
            timestamp:
              type: integer
              format: uint64
              description: Block timestamp in milliseconds since Unix epoch
        extrinsics:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the extrinsic in the block
              version:
                type: integer
              success:
                type: boolean
              hash:
                type: string
                description: Extrinsic hash
              fee:
                type: string
                description: Extrinsic fee as a decimal string
              tip:
                type: string
                description: Extrinsic tip as a decimal string
              signature:
                type: object
                description: Extrinsic signature data
              error:
                type: object
                description: Error data if the extrinsic failed
        calls:
          type: array
          items:
            type: object
            properties:
              extrinsicIndex:
                type: integer
                description: Index of the parent extrinsic
              address:
                type: array
                items:
                  type: integer
                description: Call address within the extrinsic call tree
              name:
                type: string
                description: "Qualified call name (e.g. Balances.transfer_keep_alive)"
              success:
                type: boolean
              args:
                type: object
                description: Call arguments
              origin:
                type: object
                description: Call origin
              error:
                type: object
                description: Error data if the call failed
        events:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the event in the block
              extrinsicIndex:
                type: integer
                description: Index of the parent extrinsic
              callAddress:
                type: array
                items:
                  type: integer
                description: Address of the call that emitted this event
              name:
                type: string
                description: "Qualified event name (e.g. Balances.Transfer)"
              phase:
                type: string
                description: Event phase (ApplyExtrinsic, Finalization, Initialization)
              topics:
                type: array
                items:
                  type: string
              args:
                type: object
                description: Event arguments
      required:
        - header
    BlockHead:
      type: [object, "null"]
      properties:
        number:
          type: integer
          format: int64
          description: Block number of the highest available block
        hash:
          type: string
    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: 21780871
            hash: "0xab12cd..."
          - number: 21780872
            hash: "0xf6a96a29..."
