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

# TON wallet integration

Convert built TON messages to wallet input, preserve all messages, and obtain a tracking identifier.

Use this page after selecting a quote in the [JS/TS](https://docs.ston.fi/developer-section/omniston/sdk/nodejs.md) or [React](https://docs.ston.fi/developer-section/omniston/sdk/react.md) guide. It adapts API v1beta8 TON transactions to a wallet and ties submission to settlement tracking; general wallet sending is described in [TON transaction sending](https://docs.ston.fi/developer-section/common/transaction-sending.md).

## Build the selected settlement

* Swap quote: `tonBuildSwap()` returns an unsigned `TonTransaction`.
* Order quote with a TON source: `tonBuildEscrowTransfer()` returns an unsigned `TonTransaction`.

Supply the accepted quote ID, TON source/owner address, and the real destination-chain address. An order’s destination address need not be TON. For HTLC orders, follow the selected secret mode and the quote’s hashing function; never generate unrelated hashes after signing.

## Adapt all messages

`TonTransaction.messages` is an ordered list expected to be sent by the same wallet in one transaction. Each message has `targetAddress`, `sendAmount` (nanotons), a hex-encoded BoC `payload`, and optionally hex-encoded `jettonWalletStateInit`. TonConnect expects base64 BoCs. Preserve every message, its order, and state init.

```ts
import { Cell } from "@ton/core";
import type { TonTransaction } from "@ston-fi/omniston-sdk";

function toTonConnectMessages(transaction: TonTransaction) {
  return transaction.messages.map((message) => ({
    address: message.targetAddress,
    amount: message.sendAmount,
    payload: message.payload
      ? Cell.fromHex(message.payload).toBoc().toString("base64")
      : undefined,
    stateInit: message.jettonWalletStateInit
      ? Cell.fromHex(message.jettonWalletStateInit).toBoc().toString("base64")
      : undefined,
  }));
}
```

The source wallet must match the builder’s transfer address and be connected to the correct network. Check its advertised message capacity; if it cannot send the complete builder result, choose a compatible wallet/flow rather than dropping messages or splitting this transaction silently.

## Submit and identify a swap

The following recipe uses `tonConnectUI` from your existing TonConnect integration, `swapTx` from `tonBuildSwap()`, and the accepted `quote`/TON `traderAddress` from the SDK guide. `validUntil` is a Unix timestamp in seconds.

```ts
const result = await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  messages: toTonConnectMessages(swapTx),
});

const outgoingTxQuery = Cell.fromBase64(result.boc)
  .hash()
  .toString("hex");

const tracking = omniston.swapTrack({
  quoteId: quote.quoteId,
  traderAddress,
  outgoingTxQuery,
});
```

TonConnect returns the signed external-message BoC. Its original external-message hash is one supported `outgoingTxQuery` form; the API also accepts a transaction hash, a normalized external-message hash, or the supported external-message body representation. Do not use an inner contract payload or a wallet `seqno` as a transaction identifier.

Other TON senders must expose a supported identifier too; a send method returning `void` does not provide one. Use the relevant wallet/RPC transaction lookup before tracking.

## Track an order and its result

Send all messages from `tonBuildEscrowTransfer()` through the same adapter. Then use `orderTrack({ quoteId, traderAddress })`, where `traderAddress` is the source-side owner used for the order. Order tracking does not take a swap `outgoingTxQuery`.

Follow [Settlement lifecycle](https://docs.ston.fi/developer-section/omniston/how-omniston-works.md) for terminal statuses, partial fills, disclosure timing, and rollback. Keep the last order snapshot even after `unsubscribed`; restore active orders with `orderGetActive()`. A successful broadcast is the beginning of settlement, not proof that the output asset has arrived.


---

# 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/sdk/ton.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.
