Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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. Select your assets and specify amounts using the API amount fields.

The SDK transport implementation and protobuf definitions 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.

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

Notifications use the same fully qualified method. params.subscription identifies the stream, and params.result contains a QuoteEvent:

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:

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. For EVM/other chains, use the relevant wallet guide.

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 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. 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 <method>.closed notification closes a subscription; retain the last known order state.

To stop the quote subscription in this example:

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.

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 for finalized-order reporting.

For an existing v1beta7 client, see Versions and migrations and its versioned WebSocket reference.

Last updated