How Omniston Works

Protocol-level Omniston concepts for RFQs, settlement modes, orders, executions, HTLC-based cross-chain settlement, timings, and fees.

Omniston provides a single RFQ-based integration for swaps on TON and cross-chain swaps.

For swaps on TON, Omniston aggregates liquidity from connected TON sources, including AMM DEXs and RFQ resolvers, and returns the best available terms.

For cross-chain swaps, the trader sends an RFQ, resolvers return quotes, and the selected resolver settles the trade so the output asset is delivered on the destination blockchain. HTLC-based settlement uses hashlocks and timelocks to make the cross-chain flow verifiable and atomic.

In cross-chain flows, the selected resolver provides the destination-side liquidity. The protocol links the source-side and destination-side legs with HTLC rules, so integrators do not need to pre-fund destination-side inventory on every chain they support.

For role and object definitions, see the glossary. Glossary terms match the names used in protocol messages and SDKs.

Conceptual Model

Actors:

• Trader - sends an RFQ, accepts a quote, and funds a position or signs an order.

• Resolver - returns a Quote and performs the required settlement actions. In cross-chain flows, the resolver also provides the destination-side liquidity for the selected route.

• Integrator - an optional partner that may receive an integrator fee in the Output asset on the destination blockchain.

Core objects and how they chain together:

1. The Trader sends an RFQ (request for quote).

2. Resolvers return Quote for that RFQ. Several quotes may be available for the same request.

3. In order settlement, an Order is created from the selected Quote and has its own lifecycle.

4. An Order may contain multiple Executions. Each Execution represents one fill attempt or fill fragment, such as a partial fill.

5. Input position and Output position represent the protocol state of the Input asset and Output asset for a given Execution. Output position is used in HTLC-based cross-chain settlement and is not used for intrachain swaps.

Swap settlement does not create a persistent Order object in the API flow. It uses immediate swap routes instead. Order settlement introduces Order, Execution, reservations, and cancellation semantics.

Settlement Modes

	Swap settlement	Order settlement
When settlement happens	Immediately through one or more swap routes made of chunks and steps.	An Order is created first, and resolvers fill it over time.
Trader action	Accepts a quote with a swap payload and follows the swap transaction flow.	Creates or registers an Order, either escrow-backed or signed-order / gasless.
Resolver role	Provides liquidity according to the selected route.	May reserve, complete, or roll back Executions; exclusivity and HTLC windows apply.
Why data shapes differ	A quote carries routes, slippage hints, and gas estimates.	A quote carries OrderSettlementData: protocol contracts, HTLC parameters, deadlines, and optional exclusivity.

Use swap settlement for immediate execution through a selected route. Use order settlement when the protocol must represent an ongoing position, such as escrow, HTLC, partial fills, or timed phases.

Intrachain Swaps vs Cross-chain Swaps

In an intrachain swap, the trader sends and receives assets on the same blockchain. In a cross-chain swap, the trader sends the input asset on the source blockchain and receives the output asset on the destination blockchain.

HTLC-specific fields are used only for cross-chain swaps, where the source blockchain and destination blockchain differ.

In intrachain swaps, there is no cross-chain HTLC leg, so HTLC-only fields such as output positions, secret hashes, and security deposits are not included.

HTLC-based cross-chain settlement uses:

• Secret hashes based on protocol-generated secrets or trader-provided hashes.

• A distinct Output position on the destination blockchain, with its own ExecutionPhase lifecycle alongside the Input position.

• Completion and rollback windows, plus security deposits on source and/or destination where applicable.

If a field's comment in the schema says (HTLC-only) or omitted for intrachain, the field is expected to be missing in that flow.

Cross-chain Execution Model

For integrators, the most important operational distinction is this:

• the trader funds the source-side leg

• the selected resolver funds the destination-side leg

• the HTLC rules link both legs so the flow can move toward completion or timed rollback

This is why Omniston cross-chain execution is different from a separate wrapped-asset bridge transfer. Clients integrate one RFQ and settlement model, while resolvers supply the destination-side liquidity per route.

Atomic Outcomes in HTLC Settlement

For app logic, treat an HTLC-based cross-chain execution as converging to one of these outcomes:

Scenario	Result
The destination-side leg completes and the secret is disclosed at the required phase	The trader receives the destination-side assets and the resolver can complete the linked source-side claim.
The destination-side leg is not completed in time	The source-side position follows its refund or rollback path under the HTLC deadlines.
A cross-chain execution rolls back after liquidity was locked	The locked positions are unwound according to the same HTLC windows for that execution.

The intended safety property is that the flow resolves through successful settlement or timed rollback, rather than an unresolved mid-transfer state.

Supported Chains

Each supported blockchain has a fixed chain_id that identifies the chain where the input asset is provided or the output asset is delivered.

TRON is listed for upcoming support and are not available yet.

Supported chains and chain_id values:

• 1 — Arbitrum (arbitrum)

• 2 — Avalanche C-Chain (avalanche)

• 3 — Base (base)

• 4 — BNB Chain (bnb)

• 5 — Ethereum (ethereum)

• 6 — Polygon (polygon)

• 7 — Robinhood Chain (robinhood)

• 50 — TON (ton)

• 60 — TRON (tron)

• 196 — X Layer (xlayer)

Chain matching rules:

• chain_id must stay consistent across the asset and address used on the same side of the trade.

• The source-side input asset and source-side address must use the same chain.

• The destination-side output asset and destination-side address must use the same chain.

• intrachain means source and destination use the same chain.

• cross-chain means source and destination use different chains.

• EVM chains use EIP-55 addresses and currently support ERC-20 assets only. Native assets should be wrapped. ERC-1155 assets are not supported yet.

• TON uses a valid TON address string and supports native and jetton assets.

Lifecycle and Timing

The main timers have different meanings:

1. quote_validity_timeout - protocol parameter visible in resolver events: the maximum duration after quote generation during which the trader must make a valid deposit.

2. trade_start_deadline - latest timestamp, in UTC seconds, for trade start. Depending on the flow, trade start means that funds are received by the protocol contract or that an order is signed. Resolver behavior after this deadline depends on the specific flow.

3. exclusivity_timeout - after the trader creates a position, the window in which a resolver must reserve it, including a security deposit where required. When it ends, exclusivity ends: the position may become withdrawable or subject to auction rules per escrow configuration.

4. cancellation_available_timestamp - on order updates: time after which the trader may cancel the unfilled remainder. Any exclusivity period also ends at this timestamp.

Simplified order-settlement timeline:

RFQ -> quote accepted -> trader opens a position or signs an order -> exclusivity window -> optional public fill phase -> per-Execution completion or rollback timestamps -> terminal Execution state.

Authoritative Streams After Submit

Use different streams for different stages:

• RFQ stream (requestForQuote() / useRfq) is for pricing and reservation updates before you commit to a route.

• swapTrack() is the authoritative settlement stream for swap settlement.

• orderTrack() is the authoritative settlement stream for order settlement.

RFQ keep-alives and quote refreshes cover the pre-submit pricing stage. After a signed order or escrow transfer is submitted, the settlement tracking stream becomes the lifecycle source of truth.

Execution Phases

ExecutionPhase represents the lifecycle state of a position. Phases exist separately for the Input position and, in HTLC-based cross-chain settlement, for the Output position.

Non-final phase groups:

• Created - position exists; resolver that holds reservation may proceed where rules allow.

• Ready for private completion (HTLC) - on-chain finality reached; reserved resolver may drive successful completion.

• Ready for public completion (HTLC) - private window ended; other authorized resolvers may complete under protocol rules.

• Ready for private rollback - reserved resolver may initiate rollback.

• Ready for public rollback - public rollback; only the Input position enters this phase per schema comments.

Final states are Completed (successful settlement) and Rolled back (assets returned per rules).

HTLC-only phases and Output position fields are absent for intrachain swaps by design.

Amounts and Fees

At quote level:

• input_units - total Input asset the trader sends, including fees charged in that leg where applicable.

• output_units - net Output asset the trader receives after integrator and protocol fees.

• resolver_sends_units (order settlement) - total Output asset the resolver must move, including protocol and integrator fees. It is greater than the trader's net output when fees are non-zero, and equal when fees are zero.

• integrator_fee_units / protocol_fee_units - fee portions taken in Output asset as quoted.

On each Execution, the same distinction appears: output_units vs resolver_sends_units for that slice of the trade.

Secrets and Disclosure in HTLC

HTLC-based cross-chain settlement depends on hashlocks:

• secret_hash on an Execution is HTLC-only and is not included in intrachain swaps.

• Order details (VersionedHtlcOrderDetails) carry secret_hashes, destination receive address, and optional trader_dst_disclose_address when disclosure must happen at an address distinct from the destination payout address.

Secrets may be generated by the protocol or provided by the trader as ordered secret hashes, aligned with execution/chunk indexing and the quote's hashing function. The secret preimage is disclosed later to complete the cryptographic leg that unlocks funds according to protocol rules.

For integrators: never assume every Execution carries secret fields. Check the settlement mode and whether the swap is intrachain or cross-chain first.

When to Call orderDiscloseHtlcSecret()

In cross-chain HTLC flows, the source-side Input position and destination-side Output position do not necessarily advance in lockstep.

Important implementation rule:

• do not disclose purely because the source leg looks completion-ready

• prefer disclosing only after the destination-side Output position is present and has entered the completion-ready phase required by your flow

In practice, this means your app should usually key disclosure off outputPositionPhase, not only inputPositionPhase.

Also note:

• a successful orderDiscloseHtlcSecret() RPC response does not by itself prove that the destination assets are already received by the trader

• orderTrack() remains the source of truth for the trade lifecycle after disclosure

Reading Completion in Order Settlement

For order settlement, the primary completion signal is Order.status.

Treat these values as the main user-facing outcomes:

• TRADE_STATUS_FULLY_FILLED

• TRADE_STATUS_PARTIALLY_FILLED

• TRADE_STATUS_CANCELLED

• TRADE_STATUS_FAILED

For cross-chain HTLC flows, correlate Order.status with per-execution phases:

• use Order.status as the headline trade result

• use Input position and Output position phases to drive operational steps such as secret disclosure, support diagnostics, and advanced UI

If your client stores stream state, keep the last order snapshot even if the stream later emits unsubscribed. The end of the subscription does not mean the order rolled back.

How to Read Raw Settlement Data

This section is an advanced/reference guide for integrator UIs that expose a panel called Settlement Data or a similar debug block.

It is easiest to read after the lifecycle, phase, fee, and HTLC sections above, because those sections explain the timing and state concepts that many settlement fields point to.

Two practical rules help avoid confusion:

• docs and protobuf schemas use snake_case, while app UIs often render the same keys in camelCase

• not every field shown under one UI heading necessarily comes from the same protobuf message

For current cross-chain order quotes, most of the contract, HTLC, and timing fields below come from OrderSettlementData. Related fee/config values may come from quote-level fields or resolver-side protocol parameters and are often shown nearby in advanced tooling.

Field availability depends on the quote type, settlement path, source and destination chains, and API version. Do not build UI logic that assumes every field below is always present.

Common OrderSettlementData Fields

Raw field	Meaning
src_protocol_contract_address / srcProtocolContractAddress	Protocol contract on the Source blockchain that enforces settlement. This is the source-side contract your app is ultimately settling against.
src_wrapped_native_token_address / srcWrappedNativeTokenAddress	Wrapper contract for the Input asset when that asset is native on the source chain, such as pTON or wETH. Omitted when the input asset is not native.
src_initial_resolver_address / srcInitialResolverAddress	Resolver wallet on the Source blockchain for which the position is initially reserved during the exclusivity window. If omitted, the position is not exclusively reserved at creation time.
src_htlc_security_deposit_asset / srcHtlcSecurityDepositAsset	HTLC-only asset used for the source-side security deposit. This is not part of simple intrachain settlement.
src_htlc_security_deposit_units / srcHtlcSecurityDepositUnits	HTLC-only amount of the source-side security deposit, denominated in src_htlc_security_deposit_asset.
htlc_hashing_function / htlcHashingFunction	HTLC-only hashing function the trader must use when generating secret hashes. If your app provides hashes rather than protocol-generated secrets, they must match this function.
dst_protocol_contract_address / dstProtocolContractAddress	HTLC-only protocol contract on the Destination blockchain that enforces the output-side leg.
resolver_sends_units / resolverSendsUnits	Total Output asset moved by the resolver for this order-settlement quote, including protocol and integrator fees. This is not the same as the trader's net output_units.
dst_wrapped_native_token_address / dstWrappedNativeTokenAddress	Wrapper contract for the Output asset when that asset is native on the destination chain. Omitted when the output asset is not native.
dst_security_deposit_asset / dstSecurityDepositAsset	HTLC-only asset used for the destination-side security deposit.
dst_security_deposit_units / dstSecurityDepositUnits	HTLC-only amount of the destination-side security deposit, denominated in dst_security_deposit_asset.
trade_start_deadline / tradeStartDeadline	Latest UTC timestamp when the trade must start. In practice, trade start means either funds reach the source-side protocol contract or the order is signed, depending on the flow.
exclusivity_timeout / exclusivityTimeout	Duration after position creation during which the initially selected resolver can reserve or fill under exclusivity rules. When this period ends, the flow may move toward public fill, withdrawal, or Dutch-auction logic depending on the escrow conditions.

Related Fee and Config Fields Often Shown Nearby

• integrator_fee_pips / integratorFeePips is the requested partner fee rate on the RFQ. In v1beta8, one pip is 1/1,000,000 or 0.0001%.

• protocol_fee_pips / protocolFeePips is the protocol fee rate in pips. In resolver-side protocol parameters, protocol fees are collected in the Output asset.

• protocol_fee_recipient_address / protocolFeeRecipientAddress should be treated as advanced/debug metadata. If your UI exposes it, document which API object or protocol message your implementation reads it from.

UI Guidance for Settlement-Data Panels

• Prefer product-language labels over raw protocol keys in the main user-facing flow.

• If you expose raw keys, keep them in an advanced/debug view and link them back to the quote or order object they came from.

• Do not assume every HTLC-related field will be present. Intrachain flows intentionally omit HTLC-only fields.

• Do not assume fields shown in one panel all come from Quote.order. Some tools combine quote settlement data, quote-level fee fields, and resolver-side parameters into one visual block.