> 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/grpc.md).

# gRPC API v1beta8

Generate current protobuf trader clients, receive streaming quotes, build settlement, and track its result.

Use a TLS gRPC client for the trader services in `stonfi.omni.v1beta8`. This guide uses the current [protobuf definitions](https://github.com/ston-fi/omniston-sdk/tree/main/packages/omniston-sdk/src/api/proto) published with the SDK. Choose a target from [Environments and endpoints](/developer-section/omniston/environments.md); gRPC targets are `host:port`, not REST URLs.

## Generate the client

Generate bindings for your language from the complete proto tree, including `stonfi.common.v1` and standard protobuf imports. Trader entry files are:

* `stonfi/omni/v1beta8/trader/quote.proto`
* `stonfi/omni/v1beta8/trader/swap.proto`
* `stonfi/omni/v1beta8/trader/order.proto`
* `stonfi/omni/v1beta8/trader/chains/ton.proto`
* `stonfi/omni/v1beta8/trader/chains/evm.proto`

Use generated oneof accessors and enum values for your language. SDK `$case`/`value` wrappers and JSON-RPC subscription IDs are not gRPC message fields. Do not copy a legacy v1beta7 `Address` or settlement enum into the v1beta8 client.

## First quote request

Call `stonfi.omni.v1beta8.QuoteRpc/Quote` with a `QuoteRequest`. The following protobuf-JSON representation requests one TON to TON USDT using swap settlement and 1% maximum slippage:

```json
{
  "input_asset": {
    "ton": {
      "native": {}
    }
  },
  "output_asset": {
    "ton": {
      "jetton": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
    }
  },
  "input_units": "1000000000",
  "settlement_params": [
    {
      "swap": {
        "max_price_slippage_pips": 10000
      }
    }
  ]
}
```

For a generated client, construct the corresponding native message. Use the [asset addresses](/developer-section/omniston/chains.md#supported-assets) for your selected pair and the [API amount fields](/developer-section/omniston/swap/v1beta8.md#amounts-and-fee-fields).

`Quote` is a server-streaming RPC. Process the `QuoteEvent` oneof: `ack`, `quote_updated`, `no_quote`, and `keep_alive`. Select a valid quote and inspect whether its settlement data is `swap` or `order`. The quote stream is for pricing; it is not the post-submit settlement stream. Cancel the stream when pricing is no longer needed.

## Settlement services

| Service/method                 | Request                         | Response/action                                        |
| ------------------------------ | ------------------------------- | ------------------------------------------------------ |
| `TonRpc/BuildSwap`             | `BuildTonSwapRequest`           | Unsigned `TonTransaction` for a TON-source swap        |
| `TonRpc/BuildEscrowTransfer`   | `BuildTonEscrowTransferRequest` | Unsigned `TonTransaction` for a TON-source order       |
| `EvmRpc/BuildOrderPayload`     | `BuildEvmOrderPayloadRequest`   | Payload for the selected EVM signing mode              |
| `OrderRpc/RegisterSignedOrder` | `RegisterSignedOrderRequest`    | Register the exact signed order and serialized details |
| `SwapRpc/Track`                | `TrackSwapRequest`              | Server-streaming swap progress                         |
| `OrderRpc/Track`               | `TrackOrderRequest`             | Server-streaming order snapshots                       |
| `OrderRpc/GetActive`           | `ActiveOrdersRequest`           | Active orders for a source-side trader address         |
| `OrderRpc/DiscloseHtlcSecret`  | `DiscloseHtlcSecretRequest`     | Disclose a preimage for the eligible execution         |

Every method is in package `stonfi.omni.v1beta8`. Build requests use the accepted quote ID and chain-specific source/destination addresses. TON source and destination can differ by family for cross-chain orders. Read the relevant request definition; swap, escrow transfer, and signed-order registration are not interchangeable requests.

## Wallet submission

A TON transaction contains all ordered messages. `payload` and `jetton_wallet_state_init` are explicitly hex BoC strings; use the [TON adapter](/developer-section/omniston/sdk/ton.md) to convert them for a wallet that expects base64. Preserve the complete message list.

For an EVM order, apply the [wallet-kind, allowance, and signature flow](/developer-section/omniston/sdk/evm.md). Preserve the builder's `serialized_order_details` bytes when registering the signed order. For TRON, use the [TRON wallet guide](/developer-section/omniston/sdk/tron.md) and its supported settlement path.

## Result and recovery

After submission, track a swap using its quote ID, source trader address, and `outgoing_tx_query`; track an order using quote ID and source trader address. A build/registration response does not prove that the output was received.

Interpret statuses and HTLC execution phases with [Settlement lifecycle](/developer-section/omniston/how-omniston-works.md). Retain the last order snapshot after a stream ends. Restore active state with `GetActive`, and use [History](/developer-section/omniston/history.md) for finalized orders. HTLC disclosure depends on the destination-side phase; do not trigger it solely on source-side readiness.

Handle gRPC errors, stream cancellation, and reconnects explicitly. Re-open observation streams after a disconnect rather than submitting an operation again. Cancelling a client stream stops observation; order cancellation has its own signed/on-chain requests.

See [Resolver integration](/developer-section/omniston/resolvers/guide.md) for enrollment, authentication, and bidirectional event streams. Existing v1beta7 clients have a [separate gRPC reference](/developer-section/omniston/migration/grpc.md) and [migration path](/developer-section/omniston/migration.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/grpc.md?ask=<question>&goal=<user_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.