> 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/swap/overview.md). # WebSocket API v1beta8 Current JSON-RPC methods, quote subscriptions, transaction building, and settlement tracking. This guide describes the trader JSON-RPC surface used by SDK 0.8.x and API v1beta8. Start by connecting to the trading WebSocket in [Environments and endpoints](/developer-section/omniston/environments.md). Select your [assets](/developer-section/omniston/chains.md#supported-assets) and specify amounts using the [API amount fields](/developer-section/omniston/swap/v1beta8.md#amounts-and-fee-fields). The [SDK transport implementation](https://github.com/ston-fi/omniston-sdk/tree/main/packages/omniston-sdk/src/api-client) and [protobuf definitions](https://github.com/ston-fi/omniston-sdk/tree/main/packages/omniston-sdk/src/api/proto) are the sources for method names and message shapes. JSON uses snake\_case fields and named oneof members. SDK `$case`/`value`, `chain`, and `params` wrappers are not wire JSON wrappers. ## Request quotes Send this JSON-RPC message over the WebSocket. It requests a swap quote for one TON to TON USDT with 1% maximum slippage. ```json { "jsonrpc": "2.0", "id": 1, "method": "stonfi.omni.v1beta8.QuoteRpc.Quote", "params": { "input_asset": { "ton": { "native": {} } }, "output_asset": { "ton": { "jetton": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs" } }, "input_units": "1000000000", "settlement_params": [ { "swap": { "max_price_slippage_pips": 10000 } } ] } } ``` The JSON-RPC response correlates with `id` and returns a numeric subscription ID: ```json {"jsonrpc":"2.0","id":1,"result":17} ``` Notifications use the same fully qualified method. `params.subscription` identifies the stream, and `params.result` contains a `QuoteEvent`: ```json { "jsonrpc": "2.0", "method": "stonfi.omni.v1beta8.QuoteRpc.Quote", "params": { "subscription": 17, "result": { "ack": { "rfq_id": "" } } } } ``` Handle `ack`, `quote_updated`, `no_quote`, and `keep_alive` events. `quote_updated` carries the executable Quote, including its `quote_id` and `swap` or `order` settlement data. Quotes change and expire; check the selected quote’s deadline before committing. `no_quote` indicates that no executable quote is currently available for this RFQ. For order quotes, enable an order branch with `settlement_params: [{"order":{}}]`. Enable both swap and order branches to accept either settlement mode. Follow the branch returned in the selected quote. ## Build, sign, and submit | Selected branch | Method | Next action | | ------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- | | TON-source swap | `stonfi.omni.v1beta8.TonRpc.BuildSwap` | Submit the complete returned TON transaction | | TON-source order | `stonfi.omni.v1beta8.TonRpc.BuildEscrowTransfer` | Submit the complete returned TON transaction | | EVM-source order | `stonfi.omni.v1beta8.EvmRpc.BuildOrderPayload` | Sign with the required EVM wallet mode, then register the signed order | | Signed order registration | `stonfi.omni.v1beta8.OrderRpc.RegisterSignedOrder` | Preserve the serialized order details produced by the builder | A TON swap build request has this shape. Replace the quote ID and addresses with the values for the accepted quote and wallet: ```json { "jsonrpc": "2.0", "id": 2, "method": "stonfi.omni.v1beta8.TonRpc.BuildSwap", "params": { "quote_id": "", "transfer_src_address": {"ton":""}, "trader_dst_address": {"ton":""}, "refund_src_address": {"ton":""}, "gas_excess_address": {"ton":""} } } ``` Order builders have different required inputs; use the corresponding protobuf request rather than renaming this request. A cross-chain destination address belongs to the output chain. TON responses contain an ordered `messages` list with hex BoC payloads; convert the encoding and preserve state init as shown in [TON wallet integration](/developer-section/omniston/sdk/ton.md). For EVM/other chains, use the relevant [wallet guide](/developer-section/omniston/sdk.md#wallet-integration). `RegisterSignedOrder` takes `signed_order`, `owner_src_address`, and, where required, the builder’s unchanged `serialized_order_details`. Do not deserialize/reserialize those details before registering: their bytes participate in the signed intent. JSON bytes fields use the serializer’s base64 representation; TON message payload strings are explicitly hex. ## Track the result * Swap: subscribe with `stonfi.omni.v1beta8.SwapRpc.Track`, passing `quote_id`, source `trader_address`, and `outgoing_tx_query`. * Order: subscribe with `stonfi.omni.v1beta8.OrderRpc.Track`, passing `quote_id` and source `trader_address`. * Restore active orders: request `stonfi.omni.v1beta8.OrderRpc.GetActive` with `trader_address`. * HTLC disclosure: use `stonfi.omni.v1beta8.OrderRpc.DiscloseHtlcSecret` only when the destination-side execution phase permits it. `outgoing_tx_query` is a supported transaction/external-message identifier, not the quote ID or inner payload. See the [TON adapter](/developer-section/omniston/sdk/ton.md#submit-and-identify-a-swap) for deriving an external-message hash from TonConnect. Tracking methods use the same subscription/notification envelope as quotes. Interpret the resulting swap progress or order snapshot using [Settlement lifecycle](/developer-section/omniston/how-omniston-works.md). Broadcast, successful RPC response, stream closure, and settlement success are separate events. ## Errors, cancellation, and reconnection Handle JSON-RPC `error` responses and stream notifications containing `params.error`. Match responses to request IDs and notifications to subscription IDs. A `.closed` notification closes a subscription; retain the last known order state. To stop the quote subscription in this example: ```json {"jsonrpc":"2.0","id":3,"method":"stonfi.omni.v1beta8.QuoteRpc.Quote.unsubscribe","params":[17]} ``` `SwapRpc.Track.unsubscribe` and `OrderRpc.Track.unsubscribe` use the same subscription-ID array. Unsubscribing stops observation; it does not cancel an on-chain operation. Order cancellation uses its own signed/on-chain flow and response; consult the [OrderRpc schema](https://github.com/ston-fi/omniston-sdk/tree/main/packages/omniston-sdk/src/api/proto/stonfi/omni/v1beta8/trader/order.proto). After a connection drops, re-open required subscriptions and use the new IDs. Do not automatically resubmit an accepted operation to recover its UI state. Use order tracking/active-order lookup, and [History](/developer-section/omniston/history.md) for finalized-order reporting. For an existing v1beta7 client, see [Versions and migrations](/developer-section/omniston/migration.md) and its [versioned WebSocket reference](/developer-section/omniston/migration/websocket.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 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/swap/overview.md?ask=&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.