> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/history.md).

# History API

Read finalized Omniston orders and aggregate historical swap metrics through gRPC or JSON-RPC.

The Omniston History API provides read-only access to finalized Omniston orders. Use it for order history, analytics, fee accounting, and support tools.

Swap integrations use Omniston RFQ, quote, build, submit, and tracking methods to execute trades. History API methods read data after an order has reached a final state.

## Endpoints

Use the History service entries in [Environments and endpoints](/developer-section/omniston/environments.md#service-endpoints). Trading/RFQ and History are different services. Select the gRPC target for a gRPC client, or JSON-RPC over HTTP/WebSocket for a JSON-RPC client.

## Reference

Use the live schema and protobuf definitions as the source of truth:

* [JSON-RPC schema and playground](https://omni-history.ston.fi/docs/json-rpc)
* [History API protobufs](https://github.com/ston-fi/stonfi-proto/tree/main/proto/stonfi/omni/history/v1)

## Methods

History API currently exposes:

* finalized order lists with stable `lt` pagination
* one finalized order by `quote_id`
* aggregate statistics over finalized orders

| Service              | Method                     | Purpose                                                     |
| -------------------- | -------------------------- | ----------------------------------------------------------- |
| `FinalizedOrdersRpc` | `List`                     | Returns finalized orders sorted by `lt` in ascending order. |
| `FinalizedOrdersRpc` | `GetByQuoteId`             | Returns one finalized order for a known quote ID.           |
| `AggregatesRpc`      | `FinalizedOrderAggregates` | Returns aggregate statistics for finalized orders.          |

JSON-RPC method names use the full protobuf path:

* `stonfi.omni.history.v1.FinalizedOrdersRpc.List`
* `stonfi.omni.history.v1.FinalizedOrdersRpc.GetByQuoteId`
* `stonfi.omni.history.v1.AggregatesRpc.FinalizedOrderAggregates`

## Cross-chain and Intrachain

### Source of Classification

History reports finalized orders by source and destination chain. Use those chain fields to separate cross-chain and intrachain orders.

### Classification

Classify finalized history by source and destination chain:

* cross-chain: source chain and destination chain are different
* intrachain: source chain and destination chain are the same

For aggregate rows, request `src_chain_id` and `dst_chain_id` as dimensions and compare them in the response.

For finalized order rows returned by `FinalizedOrdersRpc.List`, read the chains from `input_asset` and `output_asset` or from the source/destination address objects. For example, `input_asset.ton` and `output_asset.polygon` is cross-chain; `input_asset.ton` and `output_asset.ton` is intrachain.

Use chain filters when you know the chains you want. For "all cross-chain" or "all intrachain" reporting, request aggregate rows grouped by source and destination chain, then split the rows client-side.

### Volume

For executed volume, use `filled_orders_volume_usd`. Use `finalized_orders_volume_usd` only when you need quoted input volume for finalized orders.

## Examples

The examples below use UTC timestamps in seconds. Replace `from_timestamp` and `to_timestamp` with the reporting window you need.

### TON-to-TON Orders

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "stonfi.omni.history.v1.FinalizedOrdersRpc.List",
  "params": {
    "filters": [
      {
        "time_range": {
          "from_timestamp": "1787216333",
          "to_timestamp": "1787302733"
        }
      },
      {
        "src_chain_in_list": {
          "values": ["ton"]
        }
      },
      {
        "dst_chain_in_list": {
          "values": ["ton"]
        }
      }
    ],
    "limit": 100
  }
}
```

### Volume by Chain Pair

Rows where `src_chain_id` and `dst_chain_id` are different are cross-chain rows. Rows where they are equal are intrachain rows.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "stonfi.omni.history.v1.AggregatesRpc.FinalizedOrderAggregates",
  "params": {
    "filters": [
      {
        "time_range": {
          "from_timestamp": "1787216333",
          "to_timestamp": "1787302733"
        }
      }
    ],
    "dimensions": {
      "values": ["src_chain_id", "dst_chain_id"]
    },
    "aggregates_list": {
      "values": ["filled_orders_volume_usd", "finalized_orders_count"]
    }
  }
}
```

To calculate total cross-chain volume, sum `filled_orders_volume_usd` for rows where `src_chain_id` and `dst_chain_id` are different. To calculate total intrachain volume, sum rows where they are equal.

### TON-to-TON Volume

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "stonfi.omni.history.v1.AggregatesRpc.FinalizedOrderAggregates",
  "params": {
    "filters": [
      {
        "time_range": {
          "from_timestamp": "1787216333",
          "to_timestamp": "1787302733"
        }
      },
      {
        "src_chain_in_list": {
          "values": ["ton"]
        }
      },
      {
        "dst_chain_in_list": {
          "values": ["ton"]
        }
      }
    ],
    "aggregates_list": {
      "values": ["filled_orders_volume_usd", "finalized_orders_count"]
    }
  }
}
```

### Aggregate Response Shape

```json
{
  "rows": [
    {
      "src_chain_id": "ton",
      "dst_chain_id": "ton",
      "filled_orders_volume_usd": "123.45",
      "finalized_orders_count": "10"
    },
    {
      "src_chain_id": "ton",
      "dst_chain_id": "polygon",
      "filled_orders_volume_usd": "456.78",
      "finalized_orders_count": "20"
    }
  ]
}
```

## Practical Notes

* History contains finalized orders only. It does not stream active RFQs, live quotes, or in-progress settlement state.
* Use `quote_id` to connect order to historical data.
* Use `lt` for finalized order scans and pagination.
* JSON-RPC uses protobuf JSON encoding. 64-bit integers are encoded as strings, and `StringList` fields such as `dimensions` use `{ "values": [...] }`.
* Aggregate requests can be grouped by time, chain, asset, trader, resolver, integrator, and final status. See the JSON-RPC schema for the exact request shape.
* For live execution state, use the Omniston swap tracking APIs described in [Settlement lifecycle](/developer-section/omniston/how-omniston-works.md#authoritative-streams-after-submit).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/omniston/history.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.