> For the complete documentation index, see [llms.txt](https://trevo.gitbook.io/trevo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://trevo.gitbook.io/trevo-docs/trevo-platform/trevo-datagate/data-consistency.md).

# Data consistency

## Introduction

The Trevo blockchain produces a new block approximately every 6 seconds. Each block can introduce changes such as token transfers, updated balances, and other relevant state modifications. When interacting with blockchain data through multiple DataGate API requests, it's crucial to ensure consistency — meaning that all retrieved data accurately reflects the blockchain state at the same specific point in time.

## Importance of Data Consistency

Consider the following example:

* **Initial blockchain state (block #1000):**
  * Alice: 100 Crystals
  * Bob: 150 Crystals
* **Blockchain state after block #1001:**
  * Alice transfers 10 Crystals to Bob.
  * Alice: 90 Crystals
  * Bob: 160 Crystals

If two separate API requests are made with a slight delay between them (one during block #1000 and one after block #1001), the results can become inconsistent:

* Request 1 returns Alice's balance: 100 Crystals (block #1000 state).
* Request 2 returns Bob's balance: 160 Crystals (block #1001 state).

This inconsistency can lead to incorrect interpretations and operational errors. To avoid this, both requests must reference the same blockchain state (block #1000 or block #1001).

## Request Context

DataGate API manages consistency through a mechanism known as "Request Context." This context defines the specific blockchain state from which the requested data is retrieved.

* For **historical data** (blocks, transactions, transfers): The request context defines the latest block included in the response.
* For **current blockchain state data** (balances, storage state): The request context defines the exact blockchain state (specific block) provided in the response.

Every API request and response contains a request context. You can explicitly define this context by setting the appropriate subfields of `block_receipt` in your request JSON. If not explicitly set, DataGate automatically uses the latest available blockchain state.

You can always check the context used in a response by inspecting the `metadata.request_context` field.

**Important:** DataGate API supports blockchain state queries for contexts not older than approximately 24 hours. Attempts to retrieve states older than this will result in an HTTP error.

## Ensuring Consistency Across Paginated Results

When API requests return multiple pages of data, DataGate automatically maintains consistency. The request context set during the initial request is consistently applied across all subsequent paginated responses. No additional action is required to maintain consistency.

## Ensuring Consistency Across Multiple Requests

When querying multiple endpoints, manual setting of the request context ensures consistent data across requests.

For example, to consistently fetch token balances and corresponding token transfers:

1. Execute a request to `/tokens/balances` without explicitly setting the request context to retrieve the latest data.
2. Capture the `metadata.request_context` from this response.
3. Execute subsequent requests to other endpoints (such as `/tokens/transfers`) explicitly using this captured context by setting the `block_receipt.block_hash` field.

This method ensures that all retrieved data reflects a consistent blockchain state.