> 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 Endpoints: * gRPC: `omni-history-grpc.ston.fi:443` * JSON-RPC over WebSocket: `wss://omni-history-ws.ston.fi` * JSON-RPC over HTTP: `https://omni-history.ston.fi/json-rpc` The gRPC endpoint is a gRPC target, not a REST URL. Use the JSON-RPC endpoints when your client stack is built around JSON-RPC calls. ## 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 [Omniston API v1beta8](/developer-section/omniston/v1beta8.md). --- # 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, and the optional `goal` query parameter: ``` GET https://docs.ston.fi/developer-section/omniston/history.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.