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

• History API protobufs

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

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

{
  "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

{
  "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

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