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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://trevo.gitbook.io/trevo-docs/trevo-platform/trevo-datagate/data-consistency.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.