> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Block at Timestamp

> 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`).




## OpenAPI

````yaml /en/api/catalog/tron/openapi.yaml get /timestamps/{timestamp}/block
openapi: 3.1.0
info:
  title: SQD Portal API - Tron Dataset Endpoints
  description: >
    API endpoints for interacting with the Tron dataset under the SQD Portal,
    specifically the Tron Mainnet dataset.


    Tron-specific conventions:

    - **Addresses in filters and transaction parameters** (`owner`, `to`,
    `contract`, `caller`, `transferTo`, and the addresses inside a transaction's
    `parameter`) use the native Tron 41-prefixed, lowercase hex form (21 bytes),
    e.g. the USDT contract `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` is
    `41a614f803b6fd780986a42c78ec9c7f77e6ded13c`.

    - **Log addresses and addresses encoded inside log topics** use the 20-byte
    EVM-style hex form without the `41` prefix (e.g.
    `a614f803b6fd780986a42c78ec9c7f77e6ded13c`), because the Tron Virtual
    Machine (TVM) is EVM-compatible. TRC-20 events therefore share the same
    `topic0` signatures as their ERC-20 counterparts.

    - **Timestamps** (`block.timestamp`, transaction `expiration` and
    `timestamp`) are Unix time in **milliseconds**.

    - **Numeric resource/value fields** (`fee`, `feeLimit`, `energyFee`,
    `energyUsageTotal`, `netUsage`, `netFee`, TRX amounts, …) are returned as
    decimal strings or `null` to preserve precision.
  version: 1.0.0
servers:
  - url: https://portal.sqd.dev/datasets/tron-mainnet
    description: SQD Portal's endpoint for Tron Mainnet
security: []
paths:
  /timestamps/{timestamp}/block:
    get:
      summary: Block at Timestamp
      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: 1768435200
            example: 1768435200
          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:
                tron-mainnet:
                  summary: First block at or after the timestamp
                  value:
                    block_number: 79257136
        '404':
          description: No block found at or after the given timestamp.
        '500':
          description: Internal server error. Do not retry.
        '503':
          description: Upstream data source temporarily unavailable. Retry later.
      x-codeSamples:
        - lang: shell
          label: Resolve timestamp to block
          source: >
            curl
            'https://portal.sqd.dev/datasets/tron-mainnet/timestamps/1768435200/block'
        - lang: python
          label: Resolve timestamp to block
          source: |
            import requests

            response = requests.get(
                "https://portal.sqd.dev/datasets/tron-mainnet/timestamps/1768435200/block"
            )
            block_number = response.json()["block_number"]
        - lang: javascript
          label: Resolve timestamp to block
          source: >
            const response = await
            fetch("https://portal.sqd.dev/datasets/tron-mainnet/timestamps/1768435200/block");

            const { block_number } = await response.json();
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: 79257136
      required:
        - block_number

````