# gRPC Integration

This guide describes how to use the **Omniston** swap functionality over the gRPC API from a trader's perspective. It parallels [Swap overview (WebSocket)](/developer-section/omniston/swap/overview.md) 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.

## gRPC Endpoints (TLS)

**Production:** `omni-grpc.ston.fi:443` **Sandbox:** `omni-grpc-sandbox.ston.fi:443`

> ⚠️ gRPC endpoints are **host:port** targets over TLS and are not HTTP REST URLs. Do not use `https://...` as if it were a REST API.

## 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`, `maxOutgoingMessages` (for TON), or `flexibleReferrerFee` flag

   You receive an **Observable** (RxJS style in the SDK) or a stream of `QuoteResponseEvent` messages over gRPC:

   * **First**, you'll receive a `QuoteRequestAck` message containing the `rfq_id` (a SHA-256 hex string) that uniquely identifies your quote request
   * **Then**, 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`)
   * Optional: `refundAddress` - where funds should be returned if the transaction fails (defaults to sender's wallet) 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`.

> **TON-only note**: This page uses the TON-only blockchain code model. Here, `607` refers to TON in that model and is not part of the current cross-chain `chain_id` map. For current cross-chain identifiers, see [Omniston API v1beta8](/developer-section/omniston/v1beta8.md).

* **`Address`**\
  An object:

  ```json
  {
    "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`.
* **`QuoteRequestAck`**\
  Acknowledgment message sent immediately after receiving a quote request:

  ```protobuf
  message QuoteRequestAck {
    string rfq_id = 1;  // SHA-256 hex string uniquely identifying the RFQ
  }
  ```
* **`SwapStep` and `SwapChunk`**
  * Each step is a transition from `bidAssetAddress` to `askAssetAddress`.
  * For TON: typically exactly one chunk per step.
  * A chunk includes:

    ```protobuf
    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](/developer-section/omniston/resolvers/guide.md). For Node.js or TypeScript usage, see [omniston-nodejs.md](/developer-section/omniston/sdk/nodejs.md) or the [omniston-react.md](/developer-section/omniston/sdk/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.


---

# Agent Instructions: 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:

```
GET https://docs.ston.fi/developer-section/omniston/swap/grpc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.