Swap grpc

This guide describes how to use the Omniston swap functionality over the gRPC API from a trader's perspective. It parallels Swap overview (WebSocket) but shows the gRPC specifics.

Key Differences from WebSocket API

  1. Protocol Field For the gRPC API, the protocol field in each swap chunk must be a string:

    • "StonFiV1", "StonFiV2", "DeDust", or "TonCo". In contrast, the WebSocket API uses numeric codes 1, 2, 3, or 4.

  2. Extra Version Currently, only extraVersion = 1 is supported.

  3. Steps vs. Chunks

    • Each SwapStep moves from one asset to another (e.g., TON → USDC).

    • Each step can have multiple SwapChunk objects, but on TON you typically see exactly one chunk per step.

  4. Method Names In the gRPC API, traders use similar calls to requestForQuote, buildTransfer, trackTrade, etc., but these are exposed via protobuf messages, not JSON-RPC. The underlying fields are the same.

Typical Flow (Traders)

A typical gRPC-based swap flow from a trader's viewpoint is:

  1. Send a Quote Request Using Omniston.requestForQuote (or the corresponding gRPC call), providing:

    • bidAssetAddress, askAssetAddress

    • The desired amount (either bidUnits or askUnits)

    • Optional referrerAddress and referrerFeeBps

    • settlementMethods = [SETTLEMENT_METHOD_SWAP] if you want a swap

    • settlementParams such as maxPriceSlippageBps or maxOutgoingMessages (for TON)

    You receive an Observable (RxJS style in the SDK) or a stream of QuoteResponseEvent messages over gRPC. The server may update your quote repeatedly if a more favorable price arrives.

  2. Build the Transfer When you have a valid Quote, call Omniston.buildTransfer with:

    • The quote you accepted

    • Your sourceAddress (on bidBlockchain)

    • Your destinationAddress (on askBlockchain) The API returns an object with blockchain-specific transaction data (for TON, a list of messages).

  3. Sign/Send the Transaction

    • On TON, you typically pass these messages to your wallet (e.g., TonConnect, Tonkeeper, etc.).

    • Wait for the transaction to be mined.

  4. Track the Trade You can then call Omniston.trackTrade to receive streaming updates about the trade status. This includes whether the trade was filled, partially filled, or aborted.

Important Data Types

  • Blockchain A numeric code following SLIP-044. For TON, this is 607.

  • Address An object:

    {
  "blockchain": 607,
  "address": "EQDA3..."
}

  • Protocol Must be one of:

    • "StonFiV1"

    • "StonFiV2"

    • "DeDust"

    • "TonCo"

  • SettlementMethod For now, typically [0] for swap in numerical form, or (in your SDK) SettlementMethod.SETTLEMENT_METHOD_SWAP.

  • SwapStep and SwapChunk

    • Each step is a transition from bidAssetAddress to askAssetAddress.

    • For TON: typically exactly one chunk per step.

    • A chunk includes:

      string protocol = 1;       // e.g. "StonFiV2"
string offer_amount = 2;
string ask_amount = 3;
uint64 extra_version = 4;  // must be 1
bytes extra = 5;           // base64-encoded data for your DEX

  • Quote The server provides a quoteId, bidUnits, askUnits, quoteTimestamp, tradeStartDeadline, etc. Includes params with settlement info for the chosen method (SwapSettlementParams).

Rejected Quotes

If you pass extraVersion != 1 (e.g., 3), the quote or the route gets rejected with a message like:

Invalid extra version for step 0: 3

Make sure to use extraVersion = 1.

Next Steps

For a complete, low-level definition of the gRPC service (resolver side, plus the underlying messages), see Resolver Integration Guide. For Node.js or TypeScript usage, see omniston-nodejs.md or the omniston-react.md for React apps. Both rely on the same underlying gRPC/WS backend.

If you have any questions or issues, please reach out in our STON.fi Discord.

PreviousSwap extraNextReact

Last updated