# 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)](https://docs.ston.fi/developer-section/omniston/swap/overview) 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`.
* **`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](https://docs.ston.fi/developer-section/omniston/resolvers/guide). For Node.js or TypeScript usage, see [omniston-nodejs.md](https://docs.ston.fi/developer-section/omniston/sdk/nodejs) or the [omniston-react.md](https://docs.ston.fi/developer-section/omniston/sdk/react) 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.