DEV Community: Web3KD

HTLC Timelocks in Cross-Chain Swap Design: A STONfi/Omniston Case Study

Web3KD — Mon, 28 Sep 2026 12:29:22 +0000

HTLC Timelocks in Cross-Chain Swap Design: A STONfi/Omniston Case Study

Every cross-chain swap has to answer one uncomfortable question: what stops one side from taking the money and walking away? There's no referee sitting between two blockchains. Ethereum doesn't know what happened on TON, and TON doesn't know what happened on Base. So the protocol has to build a referee out of pieces that both chains can already understand: a hash, a secret, and a clock.

The clock is the part people skip. Hashlocks get the attention because they're the clever bit, but the timelock is what decides what happens when things go wrong, and in cross-chain design, things going wrong is the whole design brief. This article walks through how timelocks work in HTLC-based swaps in plain language, why the two clocks in a swap must never be equal, and how all of it shows up in Omniston, the resolver-based execution layer behind STONfi's cross-chain swaps.

One honest caveat before we start. The STONfi write-up I'm drawing on describes the structure of Omniston's swaps (linked HTLCs, resolvers, refund paths) but doesn't publish exact timeout durations. Wherever I use numbers below, they're illustrative. The reasoning is what carries over, not the specific values.

🧩 Two chains, no referee

Forget the jargon for a second and picture a locker with two rules written on the door. Rule one: until Friday, this locker opens for anyone who brings the secret word. Rule two: after Friday, it opens only for the person who put the money in. That's an HTLC, a Hashed Timelock Contract. The "hashed" part is the secret word (stored as a fingerprint, so nobody can read it off the locker). The "timelock" part is Friday.

Now put one of those lockers on each chain, both protected by the same secret word. The moment someone uses the secret to open one locker, the secret becomes public, and that makes it usable on the other locker too. One event settles both sides. That's the whole trick.

Omniston builds every cross-chain swap out of exactly this pair. According to STONfi's own description, there's a bid HTLC on the source chain, where the user's assets get locked, and an ask HTLC on the destination chain, where the resolver locks its own assets, both sharing one hashlock. The protocol generates the secret on the user's behalf, so you never handle it yourself. If you're curious what that lock looks like mechanically, it's nothing exotic:

import { createHash, randomBytes } from "node:crypto";

const secret   = randomBytes(32);                                    // known to one party at first
const hashlock = createHash("sha256").update(secret).digest("hex");  // safe to publish

// Anyone can check a claimed secret against the lock...
const isValid = (candidate: Buffer) =>
  createHash("sha256").update(candidate).digest("hex") === hashlock;
// ...but nobody can work backwards from the hashlock to the secret.

That snippet is only here for intuition, since in Omniston the protocol does this step for you. What matters is the outcome. STONfi describes exactly three ways a swap can end:

The secret is disclosed: both parties receive the assets they were quoted.
The resolver fails to respond: the user is refunded by the timelock.
The secret is never disclosed: the resolver is refunded by the timelock.

There's no fourth ending where someone is left holding both sides, or neither. Endings two and three are the ones that depend on the clock, and they're the reason this article exists.

⏳ What a timelock is, and what it isn't

Here's the misunderstanding I see most often: people read "timelock" and assume it's how long the swap takes. It isn't. It's the deadline after which a stuck swap unwinds itself. In the normal case nobody waits for it at all. STONfi says most cross-chain swaps complete in roughly 15 to 40 seconds, while a timelock is a far longer safety deadline. The timelock is the worst case written down as a number, the answer to "how long could my funds sit in escrow if the other side vanishes?"

Each lock has two windows. Before the deadline, only someone who knows the secret can claim. After the deadline, only the original owner can take the funds back. Those windows never overlap on a single chain. Here's a simplified version of that logic in Solidity, the language behind most EVM contracts. It's an illustration, not Omniston's actual contracts and not production code:

struct Lock {
    address sender;     // who funded it, gets the refund
    address receiver;   // who can claim with the secret
    uint256 amount;
    bytes32 hashlock;   // sha256(secret)
    uint256 timelock;   // unix timestamp: the deadline
    bool    settled;
}

function claim(bytes32 id, bytes calldata secret) external {
    Lock storage l = locks[id];
    require(!l.settled,                    "already settled");
    require(block.timestamp < l.timelock,  "too late to claim");
    require(sha256(secret) == l.hashlock,  "wrong secret");
    l.settled = true;
    emit Claimed(id, secret);              // the secret is now public on-chain
    _pay(l.receiver, l.amount);
}

function refund(bytes32 id) external {
    Lock storage l = locks[id];
    require(!l.settled,                    "already settled");
    require(block.timestamp >= l.timelock, "not expired yet");
    l.settled = true;
    _pay(l.sender, l.amount);
}

Look at the two comparison operators. claim demands the current time be before the deadline, refund demands it be at or after it. On a single contract there's never a moment when both work, which is exactly what you want. And notice the emit Claimed(id, secret) line: claiming doesn't just move money, it publishes the secret. That one line is what links the two chains together. When the user claims on the destination side, the secret goes public, and the resolver can use it on the source side.

The thing I like most about timelocks is how boring they are. No oracle, no committee, no "trust us." Just a number and a comparison. In security design, boring is a compliment.

🎯 The rule that matters: two clocks, never equal

So far there's one clock per chain, and it all looks tidy. The subtle part is that the two clocks have to be set differently, and the difference isn't a detail. It's the entire safety argument.

Trace the order of events in an Omniston swap. The user's assets go into the bid HTLC on the source chain. A resolver reserves the order, then locks its own assets in the ask HTLC on the destination chain. The user claims the destination asset, which reveals the secret. Only then can the resolver use that secret to claim the source asset from the bid HTLC.

Look at who has to move last: the resolver. After the secret appears on the destination chain, the resolver needs enough time to notice it and get a claim confirmed on the source chain. If the source-side lock expires before that happens, the user can refund the source assets while already holding the destination asset. Here's how that failure plays out if the two deadlines are equal, or set in the wrong order:

The user's assets sit in the bid HTLC on the source chain, expiring at time T.
The resolver's assets sit in the ask HTLC on the destination chain, also expiring at T.
Just before T, the user claims the ask side, and the secret becomes public.
The resolver sees it and submits a claim on the bid side, but congestion delays it past T.
The bid HTLC has expired. The user refunds the source assets and keeps the destination asset. The resolver ends up with neither.

The fix is to make the source-side (bid) timelock expire later than the destination-side (ask) timelock, by at least the resolver's reaction time. That gap is the protection for whoever acts second. (To be clear, this is a property any correct two-party HTLC swap needs, not a claim about Omniston's specific settings.) There's a side effect worth noticing, too: if a swap never gets its secret revealed, the user's refund arrives when the longer, source-side lock expires. So the same gap that keeps the resolver safe also shapes your worst-case wait.

Here's a sketch of how you might pick those deadlines. Again, this is my illustrative model, not Omniston's implementation:

interface ChainTiming {
  finalitySeconds: number;  // how long until it's safe to act on what you saw
  worstInclusion: number;   // bad-day delay before a transaction actually lands
}

function pickTimelocks(source: ChainTiming, dest: ChainTiming, buffer = 900) {
  // Ask HTLC (destination): the user needs time to see the lock and claim it.
  const askWindow = dest.finalitySeconds + dest.worstInclusion + buffer;

  // Bid HTLC (source) must outlive the ask HTLC by the resolver's reaction time:
  // see the revealed secret on dest, then land a claim on source.
  const reaction = dest.finalitySeconds + source.worstInclusion + buffer;

  return { askWindow, bidWindow: askWindow + reaction };  // bid strictly later, by design
}

🌐 Why two chains make the margin genuinely hard

If both chains ticked at the same speed, sizing that gap would be trivial. They don't, and that's where real engineering starts. A few things feed into the margin:

Finality. Ethereum's full finality takes roughly 12 to 13 minutes, while TON confirms in seconds. "Safe to act on what I saw" means very different things on each side.
Inclusion delay on a bad day. Fee spikes and congestion can push a transaction back. The margin has to cover the worst plausible delay, not the average one.
Timestamp behavior. Contracts see block timestamps, not your wall clock. Block time can drift slightly from real time, and the margin must absorb that.
A buffer for the unexpected. Outages, retries, and a resolver that needs a second attempt all eat time.

Run the sketch above with made-up numbers and the direction of the swap starts to matter. Say an Ethereum-like source chain has 780 seconds of finality and a 300-second worst-case inclusion delay, while a TON-like destination has 10 seconds of finality and 60 seconds of worst-case inclusion. With a 15-minute buffer, the ask window comes out to 970 seconds, the reaction time to 1,210 seconds, and the bid lock to about 2,180 seconds, so a worst-case escrow of around 36 minutes. Flip the direction, with TON as the source and the slow chain as the destination, and the same function returns 1,980 seconds for the ask side and 3,720 seconds (about 62 minutes) for the bid side. Same protocol, same buffer, very different worst case, purely because of which chain has to wait for which.

That's also the trade-off in one sentence. Make the margin too tight and the party acting second gets squeezed. Make it too generous and every failed swap holds funds in escrow longer than it needs to. There's no free setting, only a deliberate one.

Whenever someone says a cross-chain swap "takes a few seconds," I want to ask about the bad day. Systems get judged by their worst case, and for HTLCs the worst case is literally written into the contract as a number.

🧭 How Omniston puts this together

With that background, the shape of Omniston's design reads differently. Here's how STONfi describes a swap end to end: the user signs an order with the hashlock embedded and their assets get locked on the source chain. A resolver reserves the order and locks its own assets on the destination chain under the same hashlock. The secret is revealed on-chain, the user claims the destination asset, the resolver claims the source asset, and both sides settle from one event.

Three details stand out once you're looking at it through the timelock lens.

Resolvers have skin in the game. A resolver doesn't just promise to deliver. It locks its own destination-side assets in the ask HTLC the moment it commits. If the swap fails, it gets those assets back only when its timelock expires, and it doesn't collect anything from the user's side without the secret. Its capital is tied up until the outcome is settled one way or the other.

Partial fills use independent clocks. STONfi's example is a 1,000 USDT order settling as four parallel 25% sub-swaps, each with its own secret, hashlock, and HTLC pair. If three complete and one doesn't, the three are final and the fourth refunds. Since each slice carries its own timelock, a stuck slice can't hold the others hostage. Smaller independent units mean a smaller blast radius when something misbehaves.

Sometimes the clock never starts. If no resolver returns a quote, nothing gets locked and no source-side asset is touched. The user keeps their original assets and can retry later, with nothing to recover because nothing was committed.

There's also the question of whether the contracts enforcing all this are any good, and comparisons like < versus <= are exactly the sort of thing that go wrong quietly. According to STONfi's audit write-up, TonTech reviewed every line of Omniston's escrow contracts using automated and manual checks and found no critical or high-severity issues. That's a positive signal, though it's a review of a specific scope at a specific time, not a permanent guarantee.

What I appreciate in STONfi's approach is that the failure story gets told up front: three endings, no fourth. Most cross-chain products make you go digging for what happens when something breaks.

✅ What this means for you

For people just using the swap, the takeaways are practical rather than technical:

A stuck swap has a bounded outcome. Your funds come back by rule, when the timelock expires, not by filing a support ticket and hoping.
If a swap takes longer than expected, check the bid HTLC's status on a TON explorer before doing anything else. STONfi specifically advises against resubmitting, since duplicate submissions just muddy the picture.
Keep a small TON balance in the source wallet. The STONfi post notes the SDK defaults to 0.3 TON for swap-related calls, and a wallet near zero can stall a request before it even reaches resolvers.
Verify the destination chain and token address before initiating. An address that's valid on one chain isn't valid on another, and no timelock protects you from sending to the wrong place.

For builders integrating cross-chain flows, three lessons carry over from the design. Make the timeout asymmetry explicit in your code and your tests, because "equal by accident" is precisely the bug that passes every happy-path test. Size margins from the worst case for each direction rather than borrowing one number for both. And show users what happens on failure and roughly when, since a swap that's safely unwinding looks identical to a broken one if the interface stays silent.

Timelocks are easy to overlook because when everything works, they do nothing at all. They exist for the day something doesn't, and the difference between a well-designed pair and a sloppy one only appears then. Omniston's approach, two linked locks, resolvers with real capital committed, and every ending accounted for, is a good example of a design where the boring part was taken seriously.

❓ FAQ

Is the timelock the same as how long my swap takes?
No. It's the deadline for refunds if something stalls. Most swaps finish in seconds and never come near it.

Why can't both timelocks simply be equal?
Because the party who claims second needs time to react after the secret is revealed. Equal deadlines can let one side collect both assets when congestion delays a claim.

What happens if no resolver quotes my swap?
Nothing gets locked, so there's nothing to time out. Your assets stay where they were and you can retry later.

Does Omniston publish its exact timelock durations?
The STONfi material I used describes the mechanism but not specific durations, so any figures in this article are illustrative. For current parameters, check STONfi's documentation.

📚 Sources

Code samples are simplified illustrations, not Omniston's contracts. Not financial advice, DYOR. Disclosure: Official STONfi Ambassador.

A Production Architecture for a STONfi-Powered Swap App: Front End, Quote Layer, Wallet, Indexer, and Monitoring

Web3KD — Mon, 28 Sep 2026 12:02:51 +0000

A Production Architecture for a STONfi-Powered Swap App: Front End, Quote Layer, Wallet, Indexer, and Monitoring

Getting a swap to work on your laptop takes an afternoon. STONfi's docs are good, the SDKs handle a lot, and there's even a public demo app you can read line by line. Getting that swap to keep working for real users, on a bad network day, with support tickets coming in, is a different job, and almost none of it is about the swap itself.

This article is about that second job. It walks through the five layers I'd put around a swap built on STONfi and Omniston: the front end, the quote layer, the wallet, the indexer, and monitoring. For each one I'll say what it's for, what breaks if you skip it, and where STONfi ends and your own work begins. I'll keep the language plain and define the jargon as it shows up.

Two honest notes first. If all you need is a swap button, you probably shouldn't build any of this: STONfi offers a ready-made swap widget, and that's a perfectly good answer. And the code below is a sketch, not a drop-in. It follows the names in the current Omniston docs, which introduced a more explicit API model with native cross-chain support in v1beta8, and the SDK's event shapes have changed between versions. Pin your version and check the types you actually have installed.

🗺️ The big picture: who owns what

Start with the split of responsibilities, because everything else follows from it. STONfi and Omniston give you liquidity, routing, quotes, and execution: the part where a request for the best price gets answered by competing sources and settled on-chain. You don't build that. What you build is everything that makes it usable and trustworthy inside your product.

Follow a single swap through the system and the five layers appear in order:

Front end: the user picks assets and an amount and sees what they'd get.
Quote layer: a live stream of quotes gets turned into something stable enough to show and to decide on.
Wallet: the user reviews the exact transaction and signs it with their own keys.
Tracking and indexer: the app follows the swap to its end and keeps a durable record of what happened.
Monitoring: you find out something is wrong before your users tell you.

One rule sits over all five: your servers never hold keys or funds. The wallet signs, the chain settles, and everything you build is a window onto that, not a replacement for it. That's what non-custodial means for your architecture, and it's also why so much of the work below is about records and visibility rather than moving money.

Omniston offers three ways in. The SDKs (Node.js and React) are the recommended route and handle the WebSocket connection, quote streaming, transaction building, and error handling for you. A low-level WebSocket JSON-RPC API exists for custom clients, and gRPC over TLS is the primary low-level option for backend integrations. For most teams the SDK is the right call, and the rest of this article assumes it.

🖥️ Front end and quote layer: quotes are a stream, not an answer

The most common conceptual mistake in a first swap UI is treating a quote like the response to an ordinary API call: you ask, you get a number, you display it. Omniston works differently. You send a request for quote, and quotes keep arriving as resolvers and liquidity sources respond and update. The best one can change while the user is still looking at the screen. That's good for the price, and it's a design problem for the interface.

So the front end needs a small layer in the middle that turns a moving stream into something a person can safely act on. I call it the quote layer, and its job is boring on purpose: take whatever the SDK emits, convert it into one internal shape, and stamp it with the moment you received it. If the UI renders SDK objects directly, every SDK upgrade becomes a change to every component. If it renders your own QuoteView, an upgrade touches one mapping function.

import { Omniston, useRfq, type QuoteRequest } from "@ston-fi/omniston-sdk-react";

// Sandbox for development and CI. Production only for real traffic.
const OMNISTON_URL =
  import.meta.env.VITE_ENV === "production"
    ? "wss://omni-ws.ston.fi"
    : "wss://omni-ws-sandbox.ston.fi";

export const omniston = new Omniston({ apiUrl: OMNISTON_URL });

// The UI renders this, never the raw SDK object.
interface QuoteView {
  quoteId: string;
  receivedAt: number;    // when WE saw it, used for staleness checks
  estimatedOut: string;  // the number people hope for
  minimumOut: string;    // the number we can actually promise
}

function QuotePanel({ request }: { request: QuoteRequest }) {
  // useRfq streams events; quotes keep updating until you stop listening.
  const { data: event, error } = useRfq(request);

  if (error) return <NoQuote reason="connection" />;
  if (!event) return <Loading />;

  // Event shapes differ between SDK versions: check your installed types.
  if (event.$case === "quoteUpdated") {
    return <QuoteCard quote={toQuoteView(event.value, Date.now())} />;
  }

  // Any other event (for example, no quote available) is handled explicitly,
  // not treated as a crash.
  return <NoQuote reason="unavailable" />;
}

What should that layer actually be responsible for? A short list:

Normalizing the SDK's quote into your own shape, so upgrades stay local.
Freshness: if no update has arrived for a set number of seconds, mark the quote stale and disable the confirm button rather than letting someone sign against a number that may have moved.
Guardrails: warn or block when price impact crosses a threshold you choose, and enforce minimum amounts.
Logging what was shown: quote ID, estimated and minimum output, timestamp. When a user later says "it told me I'd get more," this is the record that settles it.
A kill switch: a config flag that turns off a route, for example cross-chain, without a redeploy.

If you want to earn from the flow, this is also where referral fees live. Omniston lets you attach referral data to a quote request so a share of the swap fee goes to your address, configurable from 0.01% to 1% per swap and paid on-chain in the same transaction. There's a flexible_referrer_fee option that lets the protocol lower your cut when that gets the user a better rate, which I think is the right default for an app that wants users to keep coming back.

👛 The wallet layer: where the user, not you, makes the decision

The wallet layer is the smallest in code and the largest in consequences. On TON the usual path is TON Connect, with @tonconnect/ui-react giving you the connect button and session handling. The flow has two separate stages, and your UI should respect that separation: connecting shares an address and lets your app propose transactions, and signing is the only moment anything actually moves. Nothing you write should blur those two.

A few things belong here that people tend to skip.

Build the transaction from the quote you showed. The React SDK provides build helpers for this, such as useTonBuildSwap, so the transaction the wallet is asked to sign is derived from the exact quote on screen, not from a fresh request that might have a different price. Show the user the same numbers, especially the minimum they're guaranteed, right before the wallet prompt.

Treat a rejected signature as a result, not an error. The user looked at the terms and said no. That should return them to the swap screen with their inputs intact and no red banner. Genuine failures, like a network error or a transaction the chain rejected, deserve a different message and a different log entry, because you'll want to count them separately later.

I treat a rejected signature as the app working correctly. Someone read the terms and decided no. That's the best failure mode you can have, so don't dress it up as a crash.

Be strict about addresses. For cross-chain swaps STONfi's flow only needs the source wallet connected, and offers an option to receive at a different destination address. If your app supports that, the destination is a manually entered value with no connected wallet to sanity-check it. Validate the format for the destination chain (an address that's valid on one chain isn't valid on another), and display the full address back before signing. Omniston's newer API models source and destination chains as separate fields for exactly this reason, and your UI should keep them separate too.

🔎 Tracking and the indexer: two clocks, two kinds of memory

Once the user signs, two different needs appear, and they need different tools.

The first is live: the person is staring at your screen and wants to know what's happening right now. Omniston's SDK covers this with a tracking stream. You give it the quote ID, the trader's address, and an identifier for the outgoing transaction (the docs call it outgoingTxQuery), and it emits events as the swap moves along. Model those events as a small state machine rather than a pile of booleans:

type SwapStage =
  | { kind: "awaiting-transfer" }
  | { kind: "in-progress"; status: string }
  | { kind: "closed" };   // the stream ended: reconcile, don't assume success

async function watchSwap(omniston, quote, traderAddress, outgoingTxQuery, onStage) {
  const stream = await omniston.swapTrack({
    quoteId: quote.quoteId,
    traderAddress,
    outgoingTxQuery,      // identifies the transaction the wallet just sent
  });

  const sub = stream.subscribe({
    next(event) {
      switch (event?.$case) {
        case "awaitingTransfer": onStage({ kind: "awaiting-transfer" }); break;
        case "progress":         onStage({ kind: "in-progress", status: String(event.value.status) }); break;
        case "unsubscribed":     onStage({ kind: "closed" }); break;
      }
      // Persist every stage change to your own store here, not just in React state.
    },
  });

  return () => sub.unsubscribe();
}

Notice the comment on closed. A stream ending means tracking ended, not that the swap succeeded. Treat it as a reason to check the outcome, never as good news.

The second need is durable, and this is where the indexer comes in. An indexer is just a service that reads chain data and keeps a searchable copy of the events you care about. You don't need to index the whole chain, only your own users' swaps and, if you use them, your referral earnings. Why bother? Because users close tabs, phones lose signal mid-swap, and support will eventually get the question "where is my swap?" React state can't answer it. A row in your database can.

CREATE TABLE swap_attempts (
  id             UUID PRIMARY KEY,        -- idempotency key, created when the user confirms
  quote_id       TEXT NOT NULL,
  wallet_address TEXT NOT NULL,
  route_kind     TEXT NOT NULL,           -- 'ton-swap' or 'cross-chain'
  bid_asset      TEXT NOT NULL,
  ask_asset      TEXT NOT NULL,
  bid_amount     NUMERIC NOT NULL,
  quoted_out     NUMERIC NOT NULL,
  minimum_out    NUMERIC NOT NULL,
  final_out      NUMERIC,                 -- filled during reconciliation, never from the UI
  stage          TEXT NOT NULL,           -- last stage we observed
  sdk_version    TEXT NOT NULL,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  reconciled_at  TIMESTAMPTZ              -- set after checking against the source of truth
);

Two words in there deserve a plain explanation. Idempotency means doing the same thing twice has the same effect as doing it once: the id is created when the user confirms, so a double-tapped button creates one record, not two. Reconciliation means comparing your records against a source of truth and fixing the differences. For finalized order history, reconciliation, and aggregate reporting, Omniston provides a dedicated History API, so a nightly job can walk your recent swap_attempts, compare them against it and against the chain, and fill in final_out with the real number. The UI's opinion of what happened is a guess. The reconciled value is the record.

Cross-chain swaps add one more thing to track. As covered in the earlier piece on HTLC timelocks, a cross-chain swap that stalls unwinds itself at a deadline. So your records should distinguish slow from stuck, and your interface should tell a waiting user that their funds return by rule if the swap doesn't complete, rather than nudging them to try again.

📡 Monitoring: knowing before your users do

The last layer is the one teams add after the first bad incident. I'd add it before. The goal isn't dashboards for their own sake; it's answering four questions quickly: is the quote stream healthy, are swaps completing, are failures spiking, and is anything stuck.

Here's what I'd put alerts on:

Quote stream health: WebSocket disconnects, reconnect loops, and time-to-first-quote. If quotes stop arriving, your swap screen is quietly broken even though nothing crashed.
Funnel drop-off: quote shown, confirm clicked, signature approved, swap completed. A sudden drop at one step points straight at the cause.
Failure taxonomy: user rejections, wallet errors, chain-level failures, and swaps that never completed, counted separately. One blended "failure rate" hides every useful signal.
Completion time tail: the median matters less than the slowest few percent. A healthy swap finishes in seconds, so a growing tail is your early warning.
Stuck orders: anything past the time you'd expect, especially cross-chain, checked against the refund deadline.
SDK version drift: run the sandbox in your CI so a dependency update that changes event shapes fails a test instead of a customer.

"No quote" is an answer, not an outage. Apps that flash a red error when no resolver responds train users to distrust the one moment the system is being honest with them.

That distinction matters for how you build alerts too. On a thin pair at an odd hour, no quote is a normal market state, so show it calmly and don't page an engineer. Reserve the loud alarms for the things that indicate your system is unhealthy. And keep a status page or at least a feature flag, so that if a route misbehaves you can switch it off for users deliberately instead of letting them discover it.

A note on the front end itself, since it's the part attackers can actually reach. Pin your dependencies, use a strict content security policy, and never let your interface ask for a seed phrase or a signature the user hasn't been shown. A swap app that's perfectly architected behind the scenes but ships a compromised script is still a compromised swap app.

🧭 What I'd build first, and what can wait

If I were starting this week, I'd build in this order: the quote layer with its own QuoteView, the wallet flow with clean separation of rejection versus failure, then the swap_attempts table written from the first day, and only then the reconciliation job and alerts. Referral fees, custom destinations, and cross-chain routes can arrive later, one at a time, each behind a flag. The order reflects a simple idea: build the record of what happened before you build anything fancy on top of it.

If I could build only one thing beyond the happy path, it would be the record of what the user was shown. Nearly every support question I can imagine starts with "what did it say?"

STONfi has done the hard part of this stack, the routing and the settlement. The architecture around it is where a swap becomes a product, and none of it is glamorous: normalize the quote, respect the signature, write things down, watch the tail. Get those four right and most of what goes wrong stays small and explainable.

❓ FAQ

Should the quote layer run in the browser or on my backend?
The browser with the React SDK is the simplest start and is how the public demo app works. A backend layer earns its place when you need shared logging, rate limiting, kill switches, or analytics, and you can add it later without changing the SDK contract.

Do I need my own indexer, or is the History API enough?
The History API is the source for finalized order history and reconciliation, but you still want your own table of attempts, because it holds what the user was shown and where your app observed the swap, which no external source can tell you.

How do I avoid duplicate swaps if a user double-taps confirm?
Create an idempotency key when the user confirms, use it as the record's ID, and ignore repeat submissions carrying the same key.

Can I use the sandbox for testing?
Yes, and you should for development and CI. The docs describe it as for development and testing only, so keep production traffic on the production endpoint.

📚 Sources

Code samples are simplified sketches. Verify names and types against your installed SDK version. Not financial advice, DYOR. Disclosure: Official STONfi Ambassador.

Router Contracts, Pool Contracts, and Why Their Upgrade Models Differ

Web3KD — Sun, 20 Sep 2026 10:37:00 +0000

Router Contracts, Pool Contracts, and Why Their Upgrade Models Differ

In most DeFi architectures, "which contracts are upgradeable" is a governance question. On STON.fi it's an architectural one — and the answer is unusually clean: the Router can be upgraded, and pools structurally cannot. Understanding why that asymmetry exists, rather than just noting it, explains a surprising amount about how the entire DEX is designed to behave under change.

🗨️ "The router is the only contract that can be upgraded. Each Jetton that goes through the DEX is owned by the router. The router does not store anything about pairs." — STON.fi, Architecture documentation

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🧩 Two Contracts, Two Completely Different Jobs

The asymmetry starts with what each contract is actually responsible for:

◆ Router — the single entrypoint for every DEX call. It owns the Jetton wallets, receives transfer_notification messages, decodes the custom payload, and forwards to the correct pool. It holds no pair-specific state at all.
◇ Pool — holds the AMM state for one specific pair: reserves, fee configuration, the actual pricing math. One pool per pair, each with its own address derived from its own state.

That split is the whole story. The Router is stateless with respect to pairs, which makes it safe to replace. A Pool is nothing but pair state, which makes replacing it a fundamentally different and more dangerous operation.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

⚙️ The Detail That Explains Everything: Pool Code Lives Inside Router State

This is the architectural fact most people miss, and it reframes the entire question.

Calling getRouterData() returns the Router's state, and among its fields are poolCode, jettonLpWalletCode, and lpAccountCode:

async getRouterData(provider: ContractProvider): Promise<{
  isLocked: boolean;
  adminAddress: Address;
  tempUpgrade: Cell;      // pending code/admin upgrade, zeros = none pending
  poolCode: Cell;         // ← the Pool contract's code, stored in the Router
  jettonLpWalletCode: Cell;
  lpAccountCode: Cell;
}>

Pools don't carry their own upgrade mechanism because they don't need one in the usual sense. The Router holds the code template from which pools are deployed. On TON, a contract's address is derived from its StateInit — its code plus initial data — which means changing pool code doesn't mutate existing pools. It produces pools at different addresses entirely.

🗨️ "Changing pool code doesn't upgrade a pool. It defines what the next pool will be."

Existing pools keep running the code they were deployed with, holding the liquidity that was deposited under those exact rules. That's not a limitation — it's a guarantee.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🔐 The Router's Upgrade Path Is Deliberately Slow

Being upgradeable doesn't mean being instantly mutable. STON.fi's Router upgrade flow is a two-phase commit with enforced timelocks:

Initiate — admin submits the new Router code. Nothing changes yet.
Wait — a minimum seven-day delay before a code upgrade can be finalized. Admin changes carry a separate minimum two-day delay.
Finalize — only once finalize_upgrades is received does the new code take effect.

The pending state is publicly readable the entire time, through the tempUpgrade field — zero values mean nothing is pending, non-zero means an upgrade is in flight and anyone can see it coming.

🗨️ "Seven days isn't a delay for the team's benefit. It's a window for everyone else."

There's also cancel_admin_upgrade, which exists specifically so a pending admin change can be revoked before it lands — an explicit escape hatch rather than a one-way door.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🛑 What the Router Can Do Without an Upgrade

Not every change requires replacing code, and the distinction matters for understanding the actual trust surface:

◆ set_fees (0x58274069) — adjust a specific pool's liquidity, protocol, and referral fees. Fee ratios are expressed against a divider of 10000, so 1% is the value 100. Note the direction here: the Router sends this message to the Pool. Pools don't govern themselves.
◇ Lock / unlock trading — flipping is_locked blocks transfer_notification messages from being processed, which effectively halts all swaps and liquidity provision through that Router. A circuit breaker, no code change required.

This is a meaningful design choice. Routine parameter changes and emergency response both happen without touching the timelocked upgrade path — which is exactly why that path can afford to be slow.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

📨 Why TON's Message Model Makes This Design Natural

On a synchronous chain, a "router" is often just a helper library — a convenience wrapper around direct pool calls. On TON, asynchronous message passing makes it something structurally heavier.

A jetton-to-jetton swap moves through a real chain of messages:

User → their Jetton wallet
     → Router's Jetton wallet  (transfer_notification#7362d09c)
     → Router                  (decodes payload, op: swap 0x6664de2a)
     → Pool                    (executes AMM math against its own reserves)
     → LpAccount / payout      (settlement)

Because the Router genuinely owns the Jetton wallets for everything flowing through the DEX, it isn't optional infrastructure you could route around. Every swap and every liquidity provision physically passes through it. That's precisely why it's the contract worth making upgradeable — and precisely why that upgrade capability needs a seven-day window attached to it.

There's also cross_swap (0x69cf1a5b), a payload op for chaining swaps on the same Router — multi-hop routing implemented as message chaining rather than as a nested synchronous call, which is simply what multi-hop has to look like in an async execution model.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🔀 What This Means for Anyone Building On Top

The practical consequence for integrators is direct, and STON.fi's own SDK documentation states it plainly: don't hardcode a router address.

// ❌ Hardcoded — a Router upgrade silently invalidates this
const router = dexFactory('EQB3ncy...');

// ✅ Let the API resolve the current router, every time
const simulationResult = await api.simulateSwap(params);
const router = dexFactory(simulationResult.router);

There's a second consequence worth naming: because pool code is a Router-held template and pool addresses derive from StateInit, multiple pool types can coexist simultaneously. v2 introduced CPI pools alongside the existing types, and the SDK migration notes are explicit that base Router and Pool method calls are deprecated in favor of specifying pool type explicitly. That's not an inconvenience — it's the visible surface of an architecture where new pool designs ship as additions, never as forced migrations of existing liquidity.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

✅ Why This Asymmetry Is the Right Call

The stateless contract is the upgradeable one. Routing logic can evolve without ever touching deposited liquidity, because the Router holds no pair state to corrupt.
Immutable pools mean LPs face fixed rules. Someone who deposits into a pool is trading against the exact code they deposited under — nobody can rewrite that pool's math underneath them.
Parameter changes and emergency stops bypass the timelock entirely. set_fees and is_locked handle routine and urgent needs, which frees the upgrade path to be genuinely, usefully slow.

⚠️ Worth Understanding Correctly

"Only the Router is upgradeable" isn't a security weakness — it's a narrowed trust surface. One contract with a seven-day public timelock is a far smaller thing to monitor than every pool being independently mutable.
is_locked is real, immediate admin power. No timelock applies. That's appropriate for a circuit breaker, but it's an honest part of the trust model and shouldn't be glossed over.
New pool code means new pool addresses, not upgraded pools. Liquidity doesn't migrate itself; LPs move deliberately, or stay exactly where they are under unchanged rules.

🏁 Bottom Line

Router and Pool contracts have different upgrade models because they hold fundamentally different things. The Router holds routing logic and custody of Jetton wallets but no pair state, making it both worth upgrading and safe to upgrade — behind a seven-day timelock with publicly visible pending state. Pools hold nothing but pair state, so they're deployed from a Router-held code template and left immutable, with new designs arriving as new addresses rather than rewrites of existing liquidity. On an async chain where the Router is a mandatory message hop rather than an optional convenience, that split isn't a compromise. It's the shape the architecture was always going to take.

🔗 Sources & Further Reading

STON.fi — Architecture Overview (router as sole upgradeable contract) — https://docs.ston.fi/docs/developer-section/architecture
STON.fi — Router (v2) Contract Reference (upgrade delays, governance messages) — https://docs.ston.fi/developer-section/dex/smart-contracts/v2/router
STON.fi — v2 Op Codes Reference — https://docs.ston.fi/developer-section/dex/smart-contracts/v2/op-codes
STON.fi — SDK v1 Reference (getRouterData, tempUpgrade structure) — https://docs.ston.fi/developer-section/dex/sdk/v1/reference
STON.fi — SDK Migration Guide v1 to v2 (CPI pools, explicit pool types) — https://docs.ston.fi/developer-section/dex/sdk/migration/v1-to-v2

This article reflects independent research based on STON.fi's public developer documentation as of mid-2026. Contract behavior, upgrade delays, and op codes evolve as the protocol ships updates — always verify current details directly on docs.ston.fi before shipping a production integration.

HTLC Timelocks in Cross-Chain Swap Design: A STONfi/Omniston Case Study

Web3KD — Sun, 20 Sep 2026 10:23:35 +0000

⏳ HTLC Timelocks in Cross-Chain Swap Design: A STON.fi/Omniston Case Study

Most explanations of atomic swaps stop at "funds are locked behind a hash and a timer, so either both sides complete or both refund." That sentence is true and almost entirely useless for understanding why the design works, what it costs, or how a production system builds a real product on top of it.

The interesting part isn't the hashlock. Hashlocks are trivial — a one-way function, a preimage, a comparison. The interesting part is the timelock, and specifically the relationship between two timelocks on two chains that don't know each other exists. Get that relationship backwards and the atomicity guarantee inverts into an exploitable free option. Get it right and you have settlement that needs no bridge, no custodian, and no governance intervention when things go wrong.

"The hashlock is the part everyone explains. The timelock ordering is the part that actually keeps you from losing money."

🔐 Section 1: The Primitive — Two Doors, Never Both Open

An HTLC holds funds behind exactly two release conditions, and the entire discipline of the design is that these two paths can never be open simultaneously.

A minimal shape, expressed as the state a contract actually stores:

interface HtlcState {
  hashlock: Uint8Array;   // sha256(secret) — public from the start
  deadline: number;       // unix timestamp, after which refund opens
  sender: Address;        // gets funds back via refund()
  receiver: Address;      // gets funds via claim(secret)
  amount: bigint;
}

Two methods, and the guard on each is what matters:

function claim(secret: Uint8Array) {
  require(now() < state.deadline,              "claim window closed");
  require(sha256(secret) === state.hashlock,   "wrong preimage");
  transfer(state.receiver, state.amount);
}

function refund() {
  require(now() >= state.deadline,             "too early to refund");
  require(caller() === state.sender,           "not the sender");
  transfer(state.sender, state.amount);
}

Look at the two now() checks. claim requires before the deadline; refund requires at or after it. They are exact complements — there is no timestamp at which both succeed, and no timestamp at which both fail. Before the deadline, exactly one party can act (the receiver, if they have the preimage). After it, exactly one party can act (the sender). There is no third state and no gap.

The academic framing describes this as a tuple of three algorithms — Lock, Unlock, Refund — and that framing is worth internalizing, because it makes explicit that "failure" here is a first-class designed outcome, not an exception path bolted on afterward. A refund isn't the protocol breaking. It's the protocol working.

Why the hash function choice actually matters. The preimage has to be unguessable and the hash has to be identically computable on both chains. That second requirement is more constraining than it sounds — it rules out any pairing of chains that don't share a hash primitive, and it's why SHA-256 dominates in practice rather than anything more exotic:

// The secret must be generated with real entropy, not derived
// from anything predictable — a timestamp, a nonce, a counter.
const secret = crypto.randomBytes(32);
const hashlock = sha256(secret);

// hashlock is published immediately and publicly.
// secret stays private until the moment of claim.

A secret derived from anything guessable — a block hash, a sequence number, a timestamp — hands the counterparty the ability to claim without waiting. The randomness isn't a detail; it's load-bearing.

There's also a subtlety in where the secret becomes public. It isn't revealed by any out-of-band message or any trusted relay. It becomes public as a side effect of being used — the claim transaction carries it, and once that transaction is in a block, the preimage is simply readable chain state that anyone can observe. That's what makes the second leg trustless: nobody has to send the counterparty anything.

Here's where one HTLC stops being enough: this construction gives you a conditional payment, not a swap. Alice can pay Bob conditionally. Nothing above causes Bob to pay Alice. A cross-chain swap needs two of these, one per chain, and coordinating their deadlines is the genuinely hard problem.

⚖️ Section 2: The Asymmetry That Makes It Atomic

Two HTLCs, two chains, same hashlock. Alice locks on the source chain, Bob locks on the destination chain. Alice generated the secret, so initially only Alice can unlock anything.

The question that decides whether this is safe or catastrophically broken:

             ┌─────────────────────────────────────────┐
  SOURCE     │  Alice's lock          deadline: ???     │
             └─────────────────────────────────────────┘
             ┌─────────────────────────────────────────┐
  DEST       │  Bob's lock            deadline: ???     │
             └─────────────────────────────────────────┘

             Which deadline comes first?

The answer: they must be staggered, not synchronized, and the direction is not arbitrary. The party holding the secret must have the later deadline.

// The one invariant the entire protocol rests on:
assert(takerDeadline < originatorDeadline);

Why this direction, specifically? Run the broken ordering and watch it fail.

Suppose Bob's deadline came after Alice's. Alice, holding the secret, simply does nothing. Her own lock expires first and she refunds — she has her original funds back, free and clear. But Bob's lock is still live, still behind the same hash, and Alice still knows the preimage. She reveals it, claims Bob's asset, and leaves holding both sides. The hashlock performed flawlessly. The deadline ordering destroyed the trade.

Now the correct ordering. Alice wants the destination asset, so she must reveal the secret on the destination chain — and she must do it before the earlier deadline. The moment she does, the preimage is public chain state. Bob reads it and claims on the source chain, and he is guaranteed a window to do so, because the source deadline is strictly later:

  t₀ ─────────────────────────────────────────────────────▶ time

  DEST    [ Bob's lock ────────────────── ✕ takerDeadline ]
                          ▲
                          │ Alice reveals secret here
                          │ (must be before ✕)
                          ▼
  SOURCE  [ Alice's lock ─────────────────────── ✕ originatorDeadline ]
                          └──── Bob's safety window ────┘

That gap — the span between the two deadlines — is Bob's protection. It isn't slack or padding. It's the entire reason he can safely go second.

The formal literature states this tightly: HTLCs realize cross-chain atomic swaps by coordinating two contracts on different chains with synchronized hashlocks and staggered timelocks, and atomicity holds in the sense that either both assets transfer or both parties refund. Synchronized hash, staggered time. Those four words are the protocol.

Enumerate every branch and it holds:

What happens	Source leg	Destination leg
Alice reveals and claims	Bob claims with revealed secret	Alice claims
Alice never reveals	Refunds at later deadline	Refunds at earlier deadline
Alice reveals at the last instant	Bob still has the full gap to act	Alice claims
Bob never locks at all	Alice's lock expires, refunds	Never existed

There is no ordering of events in which one side claims while the other side fails to either claim or refund. And note what's absent from that table: any row requiring a human to intervene. No multisig committee, no admin key, no bridge operator adjudicating whose claim is legitimate. Recovery is encoded in the contract and fires on a timer whether or not anyone is watching.

Sizing that gap is its own engineering decision. It can't be arbitrarily tight, because the second party needs real wall-clock time to observe the revealed secret, build a transaction, broadcast it, and get it confirmed — under whatever congestion exists at that moment:

const takerDeadline      = now + destinationChainFinality * SAFETY_FACTOR;
const originatorDeadline = takerDeadline + reactionWindow;

// reactionWindow must exceed:
//   worst-case source-chain confirmation time
// + realistic reorg depth
// + the counterparty's own detection latency

Too tight, and a congestion spike or reorg genuinely costs someone the trade. Too wide, and capital sits locked far longer than necessary in the failure case. Every production HTLC system is making a claim about the worst-case latency of the slower chain and encoding that claim as a number.

🔄 Section 3: What Omniston Adds — Discovery Before Settlement

The textbook atomic swap has a problem that makes it useless as a consumer product: it assumes Alice and Bob have already found each other and already agreed a price. In reality, finding a counterparty willing to take the other side of a cross-chain trade — competitively, right now, for your size — is the hard part. HTLC solves settlement. It does nothing about discovery.

Omniston's architecture puts a competitive quoting layer in front of settlement, and the ordering is the whole point:

  PHASE 1 — off-chain, free, reversible
  ────────────────────────────────────────────────────────
  user intent
      └─▶ RFQ broadcast ──▶ resolver A  ─┐
                        ──▶ resolver B  ─┼─▶ best quote wins
                        ──▶ resolver C  ─┘
                        ──▶ AMM pool reads

      ⚠️  NO HTLC EXISTS YET. Nothing has touched any chain.

  PHASE 2 — on-chain, committed, timelocked
  ────────────────────────────────────────────────────────
  winning quote
      └─▶ user locks source side    (later deadline)
      └─▶ resolver locks dest side  (earlier deadline)
      └─▶ reveal ──▶ claim ──▶ claim

Phase one costs nothing. Resolvers — independent market makers running their own pricing services over persistent gRPC streams — each decide independently what to offer for that size and pair. Quotes come back, get compared against AMM pool liquidity, best terms win.

If no acceptable quote arrives, the RFQ simply expires. No HTLC was created. There is nothing to refund and nothing to unwind. This is exactly the right place to put the "no counterparty found" failure: free, off-chain, and instant.

Phase two instantiates the two-contract construction for real — but only after a specific resolver has won at a specific price.

The boundary between those two phases deserves attention, because it's where a surprising amount of practical safety lives. A quote isn't a standing offer — it carries its own validity deadline, entirely separate from and much shorter than the HTLC timelocks that follow:

// Three distinct clocks, easy to conflate, doing different jobs:
quoteValidUntil       // seconds — how long this price is honored
takerDeadline         // minutes — destination-side HTLC expiry
originatorDeadline    // minutes — source-side HTLC expiry, strictly later

Conflating those is a genuine source of confusion. A user who hesitates past quoteValidUntil hasn't lost anything — no HTLC existed yet, and re-requesting simply produces a fresh price. A user who hesitates after locking is in a different regime entirely, where the relevant clocks are the timelocks and the outcome is a refund rather than a re-quote.

The structural detail worth highlighting: who funds the destination side. Not a bridge contract holding pooled user deposits. Not the protocol treasury. The resolver — a market maker who just won a competitive auction and is now putting its own capital behind the quote it gave.

// Bridge model — concentrated, permanent, growing target
bridgeContract.lockedValue += everyUserDeposit;

// Resolver model — per-trade, per-counterparty, time-bounded
resolverCapital.commit(thisTradeOnly, releasesAt: takerDeadline);

That's a materially different risk shape. Exposure is bounded per trade and expires on a timer, instead of accumulating in one contract that becomes a larger target every day.

This also explains something users routinely misread: why cross-chain swaps take noticeably longer than same-chain ones on STON.fi. A same-chain TON swap inherits atomicity from TON's own transaction model — complete or revert, settled as fast as the chain includes it. A cross-chain swap can inherit nothing, because two independent blockchains offer each other no guarantees whatsoever. The extra time isn't latency awaiting better engineering. It is the timelock window — a correctness guarantee, purchased in seconds.

TON's async execution adds a wrinkle the classic papers don't contemplate. The canonical atomic swap literature assumes synchronous execution: call a contract, it succeeds or reverts, you know immediately. TON passes messages instead — a message sent in one block resolves in a later one. A STON.fi swap already traverses a real message chain:

user's jetton wallet
  └─▶ Router's jetton wallet   (transfer_notification)
      └─▶ Router               (decode payload, dispatch)
          └─▶ Pool             (execute AMM math)
              └─▶ settlement

Layering HTLC settlement on top of that means "did the claim succeed?" is not answerable synchronously — which is precisely why trade tracking is a streaming subscription rather than a return value:

omniston.trackTrade({ rfqId }).subscribe(({ state }) => {
  // 'filled' | 'partiallyFilled' | 'aborted'
  // async settlement means you observe, you don't await
});

💸 Section 4: What Atomicity Actually Costs

An engineering article that only lists advantages isn't an engineering article. This guarantee is paid for in four distinct currencies.

⏱️ Latency — paid by the user. The timelock window can't compress below the slower chain's worst-case confirmation time plus margin. The trade-off is explicit in the literature: HTLCs trade a little latency — you pay for the timelock window — for the guarantee that at no point does any party hold the other's asset without an enforceable reason to release it. Seconds for certainty is usually a good trade. It's still a trade.
🔒 Capital lockup — paid by the resolver. From funding its leg until settlement, that capital is committed and unusable. If the swap refunds, the resolver recovers principal but earned nothing for the time it was immobilized. Pure opportunity cost — and a real component of why cross-chain quotes are structurally wider than same-chain AMM pricing. You are partly paying for the capital your trade froze.
⛽ Gas on the failure path — paid by whoever refunds. A refund is a transaction and costs gas. A swap that correctly returns everyone's funds is a successful outcome by design, but both parties are still slightly out of pocket on a trade that produced nothing. Small, but worth naming because it's the cost users least expect.
🎣 Griefing surface — paid in expected value. A counterparty who locks and then never reveals costs the other side nothing in principal — the refund handles it — but does cost them the window during which capital was frozen. Repeatedly initiating and abandoning swaps is a denial-of-service pattern against a resolver's working capital. The literature is candid that basic HTLCs aren't expressive enough for every multi-party scenario, and that advanced models exist specifically to improve incentive compatibility and resist bribery and collusion. Production systems generally mitigate this at the reputation layer — a resolver seeing repeated abandonment simply stops quoting that source — rather than cryptographically.

None of these invalidate the design. They define its domain of applicability. For a high-frequency, low-value, same-chain swap this would be absurd overhead. For moving meaningful size across a chain boundary, where the alternative is trusting a custodian or a bridge holding concentrated value, it's a sound trade.

🧭 Section 5: Walking Every Failure Mode

Understanding a settlement design means answering "what happens if" for every branch. Here is each realistic failure and exactly what the construction does.

📭 No resolver quotes the trade. RFQ expires. Nothing touched any chain, no HTLC existed, nothing to refund. Adjust size or slippage and re-submit. The cheapest possible failure, correctly placed first.
🚪 User gets a quote but never confirms. Same outcome — quotes carry their own validity deadline. Someone who walks away mid-flow loses nothing but time.
🔇 Resolver locks, user abandons before revealing. Source leg refunds at the later deadline, destination leg at the earlier one. Both recover principal; both are out refund gas; the resolver ate the opportunity cost of frozen capital. The trade simply didn't happen.
🐌 User reveals, destination chain congests severely. This is the exact scenario the gap exists for. The secret is now public. The resolver has the entire window between deadlines to use it on the source side. Sized with a realistic worst case, the claim succeeds despite congestion. Sized optimistically, this is where the design fails — which is why gap sizing is a serious parameter, not a config afterthought.
🔀 Chain reorganization reverses a claim. Functionally similar: re-broadcast, re-confirm, and survivability depends on whether the gap exceeds realistic reorg depth. Every cross-chain design makes a finality assumption here; an HTLC system just makes it legible as a number instead of burying it in a validator set.
✅ Everything works. User reveals on the destination chain and receives their asset. Resolver reads the secret from public chain state and claims on the source. Both legs settle. Elapsed time is roughly two chains' confirmation latency plus reaction time — measurably slower than same-chain, and correct by construction rather than by trust.

The property worth restating: across every branch above, no outcome requires manual intervention. No support ticket resolves a stuck HTLC, because there is no stuck state. The refund isn't a customer service process — it's a timer that fires whether or not anyone is paying attention.

🏁 Bottom Line

HTLC-based cross-chain settlement is one of the rare designs where the security argument is genuinely complete — you can enumerate every branch and verify each terminates fairly, without appealing to anyone's honesty or any committee's diligence. The hashlock provides conditional release. The staggered timelocks, with the secret-holder's leg expiring strictly later, provide atomicity. Reverse that stagger and you've converted a safe swap into a free option for whoever holds the preimage.

What Omniston contributes on top is the part HTLC alone can't: discovery. Running a competitive RFQ auction among independent resolvers before any funds touch any chain separates "can I get a good price" — which should be free and off-chain — from "will this settle safely," which is where the cryptography belongs. Resolvers funding the destination side with their own capital keeps failure exposure per-trade and time-bounded rather than concentrated and permanent.

The costs are real: users pay in latency, resolvers in immobilized capital, both in gas on the failure path. In exchange there's no custodian, no bridge validator set, and no state where funds sit stranded awaiting a human decision. For anyone evaluating cross-chain designs seriously, that last property — a failure mode that resolves on a timer rather than through governance — is the one worth weighing most heavily.

🔗 Sources & Further Reading

Bitcoin Optech — HTLC topic overview (hashlock and timelock clauses): https://bitcoinops.org/en/topics/htlc/
EmergentMind — Hash-Time-Lock Contracts (staggered timelock formalization): https://www.emergentmind.com/topics/hash-time-lock-htl-contracts
DEV Community — "Atomic cross-chain trades, explained: a hands-on walkthrough of HTLCs": https://dev.to/barissozen/atomic-cross-chain-trades-explained-a-hands-on-walkthrough-of-htlcs-4344
DEV Community — "FAQ: What Happens If a Swap Fails or Stalls?" (RFQ-before-HTLC failure ordering): https://dev.to/barissozen/faq-what-happens-if-a-hashlock-markets-swap-fails-or-stalls-3afm
arXiv — "xRWA: A Cross-Chain Framework for Interoperability of Real-World Assets" (Lock/Unlock/Refund formalization): https://arxiv.org/pdf/2509.12957
STON.fi Developer Docs — Omniston Protocol overview: https://docs.ston.fi/developer-section/omniston
STON.fi Blog — "What Is Atomic Swap Execution and Why Does It Matter?": https://blog.ston.fi/what-is-atomic-swap-execution-and-why-does-it-matter/

This article reflects public cryptographic literature and STON.fi's developer documentation as of mid-2026. Code samples are illustrative pseudocode written to clarify the mechanism — they are not copied from any production contract. Protocol mechanics, supported chains, and timelock parameters evolve as the system ships updates; verify against docs.ston.fi before building or trading against any of it.

⚛ Add STON.fi Swaps to a React App with TON Connect

Web3KD — Sat, 19 Sep 2026 13:25:30 +0000

⚛️ Add STON.fi Swaps to a React App with TON Connect

There's a specific moment in building a swap feature where the abstractions stop being theoretical: the user clicks a button, their wallet opens, and real tokens move. Everything before that is plumbing you can iterate on freely. Everything after it is irreversible.

This walkthrough builds that entire path in React — wallet connection through TON Connect, live quotes through STON.fi's Omniston aggregation layer, transaction construction, signing, and status tracking — and pays particular attention to the places where the two libraries meet, because that's where most integrations actually break.

The division of labor is worth stating up front, since confusing it causes most of the early confusion: Omniston knows prices and builds transactions. TON Connect signs them. Omniston never touches a private key; TON Connect never knows what a swap is. They're deliberately decoupled, and the code you write is mostly the seam between them.

"The SDK builds the message. The wallet decides whether it happens. Keep those two responsibilities separate in your head and the architecture makes sense."

🧰 What You'll Need

Node.js 18+ and a React project (Vite or Next.js both work; examples here are framework-agnostic React)
A TON wallet for testing — Tonkeeper or MyTonWallet, both TON Connect–compatible
A publicly reachable URL to host your TON Connect manifest (more on this below — it's the first thing that trips people up)
Basic React: hooks, component state, async/await

Install the two packages:

npm install @ston-fi/omniston-sdk-react
npm install @tonconnect/ui-react

@ston-fi/omniston-sdk-react is built on RxJS observables and TanStack Query under the hood, which means loading states, retries, and subscription cleanup come handled rather than hand-rolled. @tonconnect/ui-react gives you a drop-in connect button and the signing interface.

🔐 Section 1: Wallet Connection with TON Connect

Nothing else works until a wallet is connected, so start here.

TON Connect requires a manifest — a small JSON file describing your app to the wallet that's about to trust it. Create public/tonconnect-manifest.json:

{
  "url": "https://your-app-domain.com",
  "name": "My Swap App",
  "iconUrl": "https://your-app-domain.com/icon-180x180.png"
}

Three practical notes that save real debugging time:

🌐 The manifest must be reachable over public HTTPS. Wallet apps fetch it from their own servers or devices — they cannot reach your localhost. For local development, tunnel your dev server (ngrok, Cloudflare Tunnel) and point manifestUrl at the tunnel.
🖼️ The icon URL must actually resolve. A 404 here produces a connection failure that gives you no useful error message at all.
🔗 The url field should match the domain serving your app. Mismatches get flagged by some wallets.

Now wire up the provider. Create src/providers/AppProviders.tsx:

import { TonConnectUIProvider } from "@tonconnect/ui-react";

const manifestUrl = "https://your-app-domain.com/tonconnect-manifest.json";

export function AppProviders({ children }: React.PropsWithChildren) {
  return (
    <TonConnectUIProvider manifestUrl={manifestUrl}>
      {children}
    </TonConnectUIProvider>
  );
}

With that in place, a connect button is one line anywhere in your tree:

import { TonConnectButton } from "@tonconnect/ui-react";

export function Header() {
  return (
    <header className="flex justify-end p-4">
      <TonConnectButton />
    </header>
  );
}

TonConnectButton handles the wallet-selection modal, deep-linking into mobile wallet apps, session persistence across reloads, and the connected/disconnected states. You don't build any of that.

🔌 Section 2: The Omniston Provider

Next, give your component tree access to Omniston. Extend AppProviders.tsx:

import { TonConnectUIProvider } from "@tonconnect/ui-react";
import { Omniston, OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const manifestUrl = "https://your-app-domain.com/tonconnect-manifest.json";

const omniston = new Omniston({
  apiUrl: import.meta.env.VITE_OMNISTON_URL ?? "wss://omni-ws-sandbox.ston.fi",
});

export function AppProviders({ children }: React.PropsWithChildren) {
  return (
    <TonConnectUIProvider manifestUrl={manifestUrl}>
      <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>
    </TonConnectUIProvider>
  );
}

Two deliberate decisions here.

The Omniston instance is created outside the component. If you construct it inside the component body, every re-render creates a new client and tears down the previous WebSocket connection. Your quote stream will reconnect constantly and you'll spend an afternoon wondering why quotes keep vanishing.

The endpoint defaults to sandbox, not production. Omniston exposes wss://omni-ws-sandbox.ston.fi, which mirrors the production API surface exactly, letting you develop against real shapes without touching real liquidity. Defaulting to sandbox means a misconfigured build fails toward "nothing real happens" rather than "real swaps executed against production." Switch deliberately, via environment variable:

VITE_OMNISTON_URL=wss://omni-ws.ston.fi

If your app already uses TanStack Query, pass your existing client so Omniston reuses it rather than spinning up a second:

<QueryClientProvider client={queryClient}>
  <OmnistonProvider omniston={omniston} queryClient={queryClient}>
    {children}
  </OmnistonProvider>
</QueryClientProvider>

💬 Section 3: Requesting Live Quotes

Here's the concept that most distinguishes Omniston from a typical price API, and the one most worth internalizing before writing UI around it:

useRfq() is a subscription, not a fetch.

It doesn't resolve once with a price. It opens a stream that stays alive and emits updated quotes as market conditions change. Your component will re-render multiple times with new quotes for a single user input, and that's correct behavior, not a bug.

Start with settlement parameters — these tell Omniston which execution paths you'll accept. Create src/swap/settlement.ts:

import type {
  SettlementParams,
  SwapSettlementParams,
  OrderSettlementParams,
} from "@ston-fi/omniston-sdk-react";

export const swapAndOrderSettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "swap",
      value: {
        maxPriceSlippagePips: 10_000, // 1%
        flexibleIntegratorFee: true,
      } satisfies SwapSettlementParams,
    },
  },
  {
    params: {
      $case: "order",
      value: {} satisfies OrderSettlementParams,
    },
  },
];

⚠️ maxPriceSlippagePips is measured in pips — hundredths of a basis point. 10_000 is 1%. Not 100%. Not 1 bp. This is genuinely easy to get wrong by an order of magnitude, and a too-loose value doesn't throw an error — it just silently removes the protection slippage exists for. Annotate it with the percentage every time you write it.

Including both swap and order settlement types is the sensible default: swap routes through on-chain AMM pools, order routes through resolvers using signed orders or HTLC escrow. On thin pairs, order settlement is often the only path that returns a quote at all. Restricting to swap-only means seeing noQuote in situations where a perfectly good quote existed.

Now the assets and the hook. Create src/swap/useSwapQuote.ts:

import {
  useRfq,
  type AssetId,
  type QuoteRequest,
} from "@ston-fi/omniston-sdk-react";
import { swapAndOrderSettlementParams } from "./settlement";

export function tonJetton(address: string): AssetId {
  return {
    chain: {
      $case: "ton",
      value: { kind: { $case: "jetton", value: address } },
    },
  };
}

export function useSwapQuote(params: {
  inputAddress: string;
  outputAddress: string;
  inputBaseUnits: string;
  enabled: boolean;
}) {
  const quoteRequest: QuoteRequest = {
    inputAsset: tonJetton(params.inputAddress),
    outputAsset: tonJetton(params.outputAddress),
    amount: {
      $case: "inputUnits",
      value: params.inputBaseUnits,
    },
    settlementParams: swapAndOrderSettlementParams,
  };

  return useRfq(quoteRequest);
}

And the component consuming it, handling every event the stream can emit:

import { useSwapQuote } from "./useSwapQuote";

export function QuotePanel({
  inputAddress,
  outputAddress,
  inputBaseUnits,
}: {
  inputAddress: string;
  outputAddress: string;
  inputBaseUnits: string;
}) {
  const { data: event, error } = useSwapQuote({
    inputAddress,
    outputAddress,
    inputBaseUnits,
    enabled: inputBaseUnits !== "0",
  });

  if (error) {
    return <p className="text-red-500">Couldn't reach the quote service.</p>;
  }

  switch (event?.$case) {
    case "ack":
      return <p>Searching for the best route…</p>;
    case "quoteUpdated":
      return <QuoteCard quote={event.value} />;
    case "noQuote":
      return <p>No route available for this pair right now.</p>;
    case "unsubscribed":
      return <p>Quote stream closed — refresh to try again.</p>;
    default:
      return <p>Waiting for a quote…</p>;
  }
}

Handling only quoteUpdated — which is what most first attempts do — leaves your UI blank in three situations where it should be telling the user something specific:

📡 ack — Omniston received the request and assigned an rfqId. Good for a loading state; essential for debugging a stream that then produces nothing.
✅ quoteUpdated — a quote arrived. Fires repeatedly. Not a completion signal.
❌ noQuote — no connected source could fill this. Normal on illiquid pairs or oversized requests. Information, not an error.
🔌 unsubscribed — the server ended the stream. Anything displayed is now stale.

🏗️ Section 4: Building the Swap Transaction

Once a user has a quote in front of them and wants to proceed, you build the actual transaction. Branch on the settlement type first — a quote can come back as either kind, and calling the wrong builder fails.

import {
  useTonBuildSwap,
  type ChainAddress,
  type QuoteOfType,
} from "@ston-fi/omniston-sdk-react";

export function useBuildSwapTx(
  quote: QuoteOfType<"swap">,
  traderAddress: ChainAddress,
) {
  return useTonBuildSwap({
    quoteId: quote.quoteId,
    transferSrcAddress: traderAddress,
    refundSrcAddress: traderAddress,
    gasExcessAddress: traderAddress,
    traderDstAddress: traderAddress,
  });
}

Those four address parameters look redundant — in the common case they're all the same connected wallet — but each has a distinct role, and understanding them matters when something goes wrong:

📤 transferSrcAddress — where input tokens are pulled from
↩️ refundSrcAddress — where funds return if the swap fails partway
⛽ gasExcessAddress — where unused gas is returned
📥 traderDstAddress — where output tokens land

Keeping them as separate parameters means the same API supports more advanced flows later (swapping on behalf of a smart-contract wallet, sending output to a different address than the input came from) without a breaking change.

For branching, the SDK ships type guards — isSwapQuote, isOrderQuote, isHtlcOrderQuote, and matchQuoteByType. Use them rather than reaching into quote.settlementData?.$case manually; they narrow the TypeScript type correctly, so your editor tells you which fields actually exist on each variant:

import { isSwapQuote, isOrderQuote, type Quote } from "@ston-fi/omniston-sdk-react";

function SettlementRouter({ quote }: { quote: Quote }) {
  if (isSwapQuote(quote)) return <SwapFlow quote={quote} />;
  if (isOrderQuote(quote)) return <OrderFlow quote={quote} />;
  return <p>Unsupported settlement type.</p>;
}

✍️ Section 5: Signing and Sending with TON Connect

This is the seam. useTonBuildSwap() returns unsigned messages — it does not sign or broadcast anything. That's intentional: signing is wallet territory, and Omniston stays wallet-agnostic. Your job is to hand those messages to TON Connect.

import { useTonConnectUI, useTonAddress } from "@tonconnect/ui-react";
import { useBuildSwapTx } from "./useBuildSwapTx";
import type { QuoteOfType } from "@ston-fi/omniston-sdk-react";

export function SwapButton({ quote }: { quote: QuoteOfType<"swap"> }) {
  const [tonConnectUI] = useTonConnectUI();
  const rawAddress = useTonAddress();

  const traderAddress = {
    chain: { $case: "ton" as const, value: rawAddress },
  };

  const { data: swapTx } = useBuildSwapTx(quote, traderAddress);

  async function handleSwap() {
    if (!swapTx?.messages) return;

    try {
      const result = await tonConnectUI.sendTransaction({
        validUntil: Math.floor(Date.now() / 1000) + 300, // 5 minutes
        messages: swapTx.messages.map((message) => ({
          address: message.address,
          amount: message.amount,
          payload: message.payload,
        })),
      });

      // result.boc contains the signed message — needed for tracking
      console.log("Submitted:", result.boc);
    } catch (err) {
      if (isUserRejection(err)) {
        // Not an error — the user changed their mind
        return;
      }
      console.error("Swap failed:", err);
    }
  }

  return (
    <button onClick={handleSwap} disabled={!swapTx || !rawAddress}>
      {rawAddress ? "Confirm Swap" : "Connect wallet first"}
    </button>
  );
}

Three things in there deserve more than a passing glance.

⏱️ validUntil matters more than it looks. Set it too far in the future and a stale transaction can sit in the wallet's queue, then execute against a quote that's no longer accurate — potentially at a materially worse price than the user agreed to. Five minutes is a reasonable default: long enough that a slow mobile wallet doesn't time out, short enough that market movement doesn't invalidate the trade.

🙅 User rejection is not an error. People open the confirmation dialog and close it. That's normal behavior. If rejections land in the same error bucket as genuine on-chain failures, your monitoring will show a "problem" that's really just users changing their minds — and you'll chase phantom bugs. Handle it as a distinct, quiet path.

📦 Keep the boc. The response contains the signed message as a bag of cells. You need an identifier derived from it for the tracking step, so don't discard it.

📍 Section 6: Tracking the Swap to Completion

Sending isn't the end of the user's experience. They want to know whether it actually worked. swapTrack() gives you a live status stream.

import { useEffect, useState } from "react";
import {
  useOmniston,
  type ChainAddress,
  type Quote,
} from "@ston-fi/omniston-sdk-react";

export function useSwapTracking({
  quote,
  traderAddress,
  outgoingTxQuery,
}: {
  quote: Quote;
  traderAddress: ChainAddress;
  outgoingTxQuery: string;
}) {
  const omniston = useOmniston();
  const [status, setStatus] = useState("Submitting…");

  useEffect(() => {
    let unsubscribe = () => {};

    void omniston
      .swapTrack({
        quoteId: quote.quoteId,
        traderAddress,
        outgoingTxQuery,
      })
      .then((stream) => {
        const subscription = stream.subscribe({
          next(event) {
            switch (event?.$case) {
              case "awaitingTransfer":
                setStatus("Waiting for your transfer to confirm…");
                break;
              case "progress":
                setStatus(`Swap status: ${event.value.status}`);
                break;
              case "unsubscribed":
                setStatus("Tracking ended");
                break;
            }
          },
        });

        unsubscribe = () => subscription.unsubscribe();
      });

    return () => unsubscribe();
  }, [omniston, quote.quoteId, traderAddress, outgoingTxQuery]);

  return status;
}

The cleanup function returned from useEffect is not optional here. Without it, every re-render with changed dependencies leaves an orphaned subscription running, and in a component users interact with repeatedly, those accumulate until something noticeably degrades.

outgoingTxQuery can be a transaction hash, a message hash, or the outgoing message body — whichever identifier your setup surfaces most reliably. You derive it from the boc returned by sendTransaction(). The exact decode helper depends on your TON Connect version and which TON library you're using, so check the current TON Connect docs rather than assuming the API surface hasn't shifted.

⚠️ Section 7: Mistakes That Cost Real Debugging Time

Consolidated, in rough order of how often they bite people:

🔁 Creating new Omniston() inside a component. Constant reconnection, vanishing quotes. Instantiate at module scope.
📉 Using a stale quote. useRfq() emits repeatedly. Always build the transaction from the latest quoteUpdated, not a cached one from when the user first looked.
🔢 Hardcoding token decimals. Many TON jettons use 9, but USDT uses 6. Read decimals from asset metadata — hardcoding is a silent 1000× error.
📏 Misreading pips. 10_000 = 1%.
🎯 Assuming every quote is a swap quote. Code that only calls useTonBuildSwap() breaks the moment an order-settled quote arrives. Branch with the type guards.
🚨 Logging user rejections as errors. Pollutes monitoring and manufactures phantom bugs.
🌐 A manifest on localhost. Wallets can't reach it. Tunnel for local dev.
🧹 Skipping useEffect cleanup on tracking subscriptions.
📌 Trusting a caret version range. The SDK is pre-1.0, meaning breaking changes can land in minor releases under semver. Pin it:

"dependencies": {
  "@ston-fi/omniston-sdk-react": "0.8.0"
}

🚀 Section 8: From Working to Production-Ready

The flow above is complete but minimal. Before real users touch it:

🪙 Replace hardcoded token addresses with a proper picker backed by @ston-fi/api, so users can swap any supported pair rather than the two you chose for testing.
🎚️ Expose slippage as a user setting rather than a constant. Traders on volatile pairs legitimately want to widen or tighten it themselves.
🕳️ Design the noQuote state properly. A blank panel reads as "broken app." Explain that no route was found and suggest a smaller amount.
🛡️ Add an error boundary around the signing step, since wallet interactions fail in ways that shouldn't take down your whole interface.
🧪 Test against sandbox first — the endpoint exists precisely so your first end-to-end run isn't also your first real trade.
🔍 Inspect the quote object yourself. Field names carrying output amounts have shifted between SDK versions. Rather than trusting any written guide, including this one, log it once and read what you actually receive:

case "quoteUpdated":
  console.dir(event.value, { depth: null });
  break;

That takes thirty seconds and is strictly more reliable than secondhand documentation against a pre-1.0 package.

🏁 Wrapping Up

What you've built is the complete loop every TON swap feature needs: wallet connection, a live quote subscription, settlement-aware transaction building, wallet signing, and status tracking to completion. The pieces Omniston handles for you — multi-source routing across STON.fi's pools, other TON DEXs, and RFQ resolvers; quote refreshing; settlement-type branching — are precisely the parts that are tedious and error-prone to write against raw contracts.

The architectural insight worth carrying forward is the separation this whole integration is built around. Omniston produces unsigned messages and has no idea who you are. TON Connect signs messages and has no idea what a swap is. Your code is the seam between them, and keeping that boundary clean is what makes the rest — adding a token picker, supporting order settlement, handling cross-chain flows — incremental work rather than a rewrite.

🔗 Sources & Further Reading

STON.fi Developer Docs — Omniston React SDK (v1beta8): https://docs.ston.fi/developer-section/omniston/sdk/react
STON.fi Developer Docs — Omniston Node.js SDK: https://docs.ston.fi/developer-section/omniston/sdk/nodejs
STON.fi — Omniston Quickstart Guide (React): https://docs.ston.fi/developer-section/quickstart/omniston
Omniston SDK — React v0.7 → v0.8 migration guide: https://docs.ston.fi/developer-section/omniston/sdk/migration-v0.7-to-v0.8
Omniston SDK — GitHub source and example React app: https://github.com/ston-fi/omniston-sdk/tree/main/examples/react-app
@ston-fi/omniston-sdk-react on npm: https://www.npmjs.com/package/@ston-fi/omniston-sdk-react
TON Connect UI React documentation: https://docs.tonconnect.io/docs/quick-start/react

This walkthrough reflects the STON.fi Omniston React SDK documentation as of mid-2026 (v1beta8 API surface). The SDK is pre-1.0 and under active development — hook signatures, event shapes, and quote field names can change between minor releases. Verify against the current docs at docs.ston.fi and the SDK CHANGELOG before shipping, and always run an end-to-end test against the sandbox endpoint before pointing a signing flow at production.

💱 Build a STON.fi Swap Quote Viewer with TypeScript

Web3KD — Sat, 19 Sep 2026 13:00:05 +0000

💱 Build a STON.fi Swap Quote Viewer with TypeScript

Most swap tutorials rush you toward a signed transaction. This one deliberately stops short of it.

A quote viewer — a tool that requests live pricing from STON.fi's Omniston aggregation layer and displays it, without ever touching a wallet — is genuinely the best first thing to build on this stack. It has no signing, no private keys, no irreversible actions, and no way to lose money while you're still learning the API surface. It's also the component you'll end up reusing in every larger project: a swap UI, a price monitor, an arbitrage scanner, a Telegram bot, a spreadsheet feed.

By the end of this walkthrough you'll have a working TypeScript application that fetches real token metadata from STON.fi, opens a live quote stream through Omniston, handles every event the stream can emit, formats raw blockchain units into numbers a human can read, and prints a continuously-updating quote to your terminal.

"Build the read-only version first. You can't accidentally spend anything while you're still learning the shape of the API."

🧰 What You'll Need

Node.js 18+ — the SDK targets modern Node
TypeScript familiarity at a basic level (types, async/await, interfaces)
No wallet, no funds, no testnet setup — this entire project is read-only

No prior TON or blockchain development experience is required. If you've called a REST API and subscribed to an event stream in JavaScript before, you already have the mental model you need.

Two packages do the heavy lifting:

📦 @ston-fi/omniston-sdk — the quote engine. Talks to Omniston over a WebSocket and returns competing quotes sourced from STON.fi's own pools, other TON DEXs, and off-chain RFQ resolvers.
📦 @ston-fi/api — the metadata layer. A typed client for STON.fi's public REST API, which is where you get token symbols, decimals, and images without decoding jetton cells yourself.

The split matters conceptually: Omniston knows prices, the REST API knows tokens. You need both, and confusing their responsibilities is a common early mistake.

📁 Section 1: Project Setup

Start with a clean directory and the minimal dependency set.

mkdir stonfi-quote-viewer && cd stonfi-quote-viewer
npm init -y
npm install @ston-fi/omniston-sdk @ston-fi/api
npm install -D typescript tsx @types/node
npx tsc --init

tsx lets you run TypeScript directly without a separate build step, which keeps the feedback loop tight while you're iterating.

Open tsconfig.json and make sure these are set — the SDK ships ESM and modern types, and mismatched module settings are the single most common setup failure people hit here:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  }
}

Add "type": "module" to your package.json, plus a run script:

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts"
  }
}

If you skip the "type": "module" line, you'll hit a Cannot use import statement outside a module error the first time you run anything. It's a two-second fix that costs people twenty minutes when they don't know to look for it.

🔌 Section 2: Connecting to Omniston

Create src/omniston.ts. This file does one job: produce a configured client instance.

import { Omniston } from "@ston-fi/omniston-sdk";

const PRODUCTION_URL = "wss://omni-ws.ston.fi";
const SANDBOX_URL = "wss://omni-ws-sandbox.ston.fi";

export const omniston = new Omniston({
  apiUrl: process.env.OMNISTON_URL ?? SANDBOX_URL,
});

Two deliberate choices here that are worth explaining rather than glossing over.

First, the endpoint is environment-driven, not hardcoded. Omniston exposes a sandbox WebSocket that mirrors the production API surface exactly, so you can develop against real API shapes without competing for real liquidity.

Second, the default is sandbox, not production. This is the safer direction to fail in. A misconfigured deploy that falls back to sandbox shows you wrong-looking numbers and you investigate. A misconfigured deploy that falls back to production silently starts doing real things against real liquidity. For a read-only quote viewer the stakes are low, but it's the right habit to build now, before you add a signing step to a later project.

For a quote viewer specifically you'll probably want production data, since sandbox liquidity isn't representative of real market prices:

OMNISTON_URL=wss://omni-ws.ston.fi npm run dev

🏷️ Section 3: Fetching Token Metadata

Before requesting a quote you need to know which tokens you're quoting — and, critically, how many decimals each one uses.

This is where new TON developers most reliably trip. Every amount in the Omniston API is expressed in base units, the smallest indivisible unit of the token. Many TON jettons use 9 decimals, but plenty don't: USDT on TON uses 6. That means "1 USDT" is "1000000", while "1 TON" is "1000000000". Hardcode 9 decimals everywhere and your USDT amounts will be off by a factor of 1,000 — which, in a quote viewer, looks like a wildly mispriced market rather than an obvious bug.

The metadata API solves this. Create src/assets.ts:

import { StonApiClient, AssetTag, type AssetInfoV2 } from "@ston-fi/api";

const client = new StonApiClient();

export async function loadAssets(): Promise<Map<string, AssetInfoV2>> {
  const assets = await client.queryAssets({
    condition: [AssetTag.LiquidityVeryHigh, AssetTag.LiquidityHigh].join(" | "),
  });

  const byAddress = new Map<string, AssetInfoV2>();
  for (const asset of assets) {
    byAddress.set(asset.contractAddress, asset);
  }
  return byAddress;
}

export function requireAsset(
  assets: Map<string, AssetInfoV2>,
  address: string,
): AssetInfoV2 {
  const asset = assets.get(address);
  if (!asset) {
    throw new Error(`Asset not found in STON.fi metadata: ${address}`);
  }
  return asset;
}

Filtering by liquidity tags keeps the result set to tokens with meaningful depth, which is what you want for a quote viewer — quoting a token with near-zero liquidity mostly returns noise or no quote at all.

The requireAsset helper exists because the failure mode of a missing asset is subtle. Without it, an undefined decimals value propagates silently into your formatting math and produces a number that looks plausible but is wrong. Failing loudly at lookup time is far easier to debug than tracing a bad number backwards through three functions.

🔢 Section 4: Handling Amounts Without Breaking Them

Here's a rule that will save you real pain: never use JavaScript's Number type for token amounts.

Number is a 64-bit float with 53 bits of integer precision. Token amounts routinely exceed that. A large balance in base units can silently lose its least-significant digits the moment it passes through a float, and the resulting value will look completely reasonable while being quietly wrong. Use BigInt for arithmetic and strings for transport.

Create src/units.ts:

/** Convert a human-readable amount ("1.5") into base units ("1500000"). */
export function toBaseUnits(amount: string, decimals: number): string {
  const [whole = "0", fraction = ""] = amount.trim().split(".");

  if (fraction.length > decimals) {
    throw new Error(
      `Amount "${amount}" has more precision than this token supports (${decimals} decimals)`,
    );
  }

  const paddedFraction = fraction.padEnd(decimals, "0");
  const combined = `${whole}${paddedFraction}`.replace(/^0+(?=\d)/, "");

  return combined === "" ? "0" : combined;
}

/** Convert base units ("1500000") into a human-readable amount ("1.5"). */
export function fromBaseUnits(raw: string, decimals: number): string {
  const value = BigInt(raw);
  const base = 10n ** BigInt(decimals);

  const whole = value / base;
  const fraction = value % base;

  if (fraction === 0n) return whole.toString();

  const fractionString = fraction
    .toString()
    .padStart(decimals, "0")
    .replace(/0+$/, "");

  return `${whole}.${fractionString}`;
}

Note the explicit throw in toBaseUnits when a user supplies more decimal places than the token supports. The alternative — silently truncating — produces a quote for an amount the user didn't actually request. For a viewer that's merely confusing; in a tool that eventually signs transactions, it's the kind of quiet mismatch that generates support tickets nobody can reproduce.

📡 Section 5: Requesting a Quote

Now the core of the project. Create src/quote.ts.

First, settlement parameters. These tell Omniston which execution paths you're willing to accept:

import type {
  SettlementParams,
  SwapSettlementParams,
} from "@ston-fi/omniston-sdk";

export const settlementParams: SettlementParams[] = [
  {
    params: {
      $case: "swap",
      value: {
        maxPriceSlippagePips: 10_000, // 1%
        flexibleIntegratorFee: true,
      } satisfies SwapSettlementParams,
    },
  },
  {
    params: {
      $case: "order",
      value: {},
    },
  },
];

maxPriceSlippagePips is measured in pips — hundredths of a basis point. So 10_000 means 1%, not 100%, and not 1 basis point. This unit is genuinely easy to get wrong by an order of magnitude, and since a too-loose value doesn't throw an error, it just silently removes your protection. Write the percentage in a comment next to it every single time.

Including both swap and order settlement types is the right default for a viewer. It tells Omniston "quote me the best of either execution path," and the response tells you which one actually won. Swap settlement routes through on-chain AMM pools; order settlement routes through resolvers using signed orders or HTLC escrow, which is often the only path that returns a quote on thin pairs or exotic routes. Restricting to swap-only means you'll see noQuote in situations where a quote genuinely existed.

Now the asset identifiers and the request itself:

import type { AssetId, QuoteRequest } from "@ston-fi/omniston-sdk";

export function tonJetton(address: string): AssetId {
  return {
    chain: {
      $case: "ton",
      value: {
        kind: {
          $case: "jetton",
          value: address,
        },
      },
    },
  };
}

export function buildQuoteRequest(params: {
  inputAddress: string;
  outputAddress: string;
  inputBaseUnits: string;
}): QuoteRequest {
  return {
    inputAsset: tonJetton(params.inputAddress),
    outputAsset: tonJetton(params.outputAddress),
    amount: {
      $case: "inputUnits",
      value: params.inputBaseUnits,
    },
    settlementParams,
  };
}

The nested AssetId structure looks verbose for a single-chain app, and it is — but it's the reason the same API shape works for TON jettons, EVM tokens, and whatever gets added later without a breaking change. Wrapping it in a tonJetton() helper keeps that verbosity in exactly one place.

🔄 Section 6: Subscribing to the Live Quote Stream

This is the concept that most distinguishes Omniston from a typical REST price API, and getting it wrong is the most common integration bug.

requestForQuote() is not a one-shot request. It's a subscription.

You don't get a quote and finish. You open a stream that stays alive and pushes updated quotes as market conditions change. Treat it like a WebSocket feed, not like a fetch() call.

Create src/index.ts:

import { omniston } from "./omniston.js";
import { loadAssets, requireAsset } from "./assets.js";
import { buildQuoteRequest } from "./quote.js";
import { toBaseUnits, fromBaseUnits } from "./units.js";

const USDT = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
const STON = "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO";

async function main() {
  const assets = await loadAssets();
  const inputAsset = requireAsset(assets, USDT);
  const outputAsset = requireAsset(assets, STON);

  const humanAmount = process.argv[2] ?? "10";
  const inputBaseUnits = toBaseUnits(humanAmount, inputAsset.meta.decimals);

  console.log(
    `Requesting quotes for ${humanAmount} ${inputAsset.meta.symbol} → ${outputAsset.meta.symbol}\n`,
  );

  const request = buildQuoteRequest({
    inputAddress: USDT,
    outputAddress: STON,
    inputBaseUnits,
  });

  omniston.requestForQuote(request).subscribe({
    next(event) {
      switch (event?.$case) {
        case "ack":
          console.log(`📡 RFQ opened — id: ${event.value.rfqId}`);
          break;

        case "quoteUpdated":
          renderQuote(event.value, inputAsset, outputAsset, humanAmount);
          break;

        case "noQuote":
          console.log(`❌ No route available (RFQ ${event.rfqId})`);
          break;

        case "unsubscribed":
          console.log("🔌 Stream closed by the server");
          break;
      }
    },
    error(err) {
      console.error("RFQ stream failed:", err);
    },
  });
}

main().catch(console.error);

Walk through what each event actually means, because handling only quoteUpdated — which is what most first attempts do — leaves your app silent in three situations where it should be telling the user something:

📡 ack — Omniston received your request and assigned it an rfqId. This confirms the connection works and gives you an identifier to correlate every later event in this stream. Useful for logging, essential for debugging a stream that produces nothing afterward.
✅ quoteUpdated — a quote arrived. This fires repeatedly. It is not a completion signal. Each emission is a fresh price reflecting current market conditions, and later ones supersede earlier ones.
❌ noQuote — no connected source could fill this request. Common on illiquid pairs or when the requested size exceeds what any resolver will quote. This is a normal outcome, not an error — handle it as information, not as a failure state.
🔌 unsubscribed — the server ended the stream. Anything you were displaying is now stale.

Never treat the first quoteUpdated as final. If you cache it and later use it for anything real, you're operating on a price that may be many seconds out of date. Always hold the most recent event in state.

🖨️ Section 7: Rendering the Quote

Finally, turn a quote object into something legible. Add renderQuote to src/index.ts:

import { isSwapQuote, isOrderQuote, type Quote } from "@ston-fi/omniston-sdk";
import type { AssetInfoV2 } from "@ston-fi/api";

function renderQuote(
  quote: Quote,
  inputAsset: AssetInfoV2,
  outputAsset: AssetInfoV2,
  humanInput: string,
) {
  const settlementKind = quote.settlementData?.$case ?? "unknown";

  const label = isSwapQuote(quote)
    ? "AMM swap"
    : isOrderQuote(quote)
      ? "Resolver order"
      : settlementKind;

  console.log("─".repeat(52));
  console.log(`Quote ID     : ${quote.quoteId}`);
  console.log(`Settlement   : ${label}`);
  console.log(`You send     : ${humanInput} ${inputAsset.meta.symbol}`);
  console.log(`Updated at   : ${new Date().toLocaleTimeString()}`);
  console.log("─".repeat(52));
}

The SDK ships type-guard helpers — isSwapQuote, isOrderQuote, isHtlcOrderQuote, and matchQuoteByType — specifically so you don't hand-roll this branching. Use them. They narrow the type correctly in TypeScript, which means your editor will tell you which fields are actually available on each quote variant instead of letting you access something that's undefined at runtime.

One honest caveat about output amounts. The exact field names carrying the output quantity differ between SDK versions — older releases used offerUnits/askUnits, and the v1beta8 surface reorganized parts of the quote structure. Rather than copying a field name from a blog post (including this one) and hoping, log the object once and look:

case "quoteUpdated":
  console.dir(event.value, { depth: null });
  break;

Run it, read the actual shape you're receiving, then write your formatter against that — using fromBaseUnits(rawValue, outputAsset.meta.decimals) to turn the raw string into something readable. This takes thirty seconds and is strictly more reliable than trusting any secondhand documentation, including current docs, against a pre-1.0 SDK.

That pre-1.0 status is worth taking seriously in general. @ston-fi/omniston-sdk is under active development at a major version of zero, which under semver means breaking changes can legitimately land in minor releases. Pin your version explicitly in package.json rather than trusting a caret range:

"dependencies": {
  "@ston-fi/omniston-sdk": "0.8.0"
}

⚠️ Section 8: Mistakes Worth Avoiding

A consolidated list of the traps this project can fall into, most of which fail silently rather than throwing:

🔢 Hardcoding 9 decimals. USDT on TON uses 6. Always read decimals from asset metadata.
💥 Using Number for base units. Precision loss past 2^53 produces plausible-looking wrong values. BigInt and strings only.
📏 Misreading pips. 10_000 is 1%. A wrong value here doesn't error — it just removes protection.
🔁 Treating the stream as one-shot. Always render from the latest quoteUpdated, never a cached first one.
🙈 Handling only quoteUpdated. Your app goes silent on noQuote and unsubscribed, and users conclude it's broken.
🎯 Restricting to swap-only settlement without reason, then seeing noQuote on pairs where an order-settled quote existed.
📌 Trusting a caret version range on a pre-1.0 SDK.
🔗 Forgetting to unsubscribe. In a long-running app, abandoned subscriptions leak. Keep the subscription handle and call .unsubscribe() when inputs change or the component unmounts.

That last one deserves a line of code, since it's the one that only bites you later:

const subscription = omniston.requestForQuote(request).subscribe({ /* ... */ });

process.on("SIGINT", () => {
  subscription.unsubscribe();
  process.exit(0);
});

🚀 Where to Take This Next

You now have a working, read-only foundation. Natural extensions, roughly in order of effort:

A token picker — you already load the full asset list; wire it to CLI arguments or a prompt instead of two hardcoded constants.
Rate comparison over time — log each quoteUpdated with a timestamp and watch how a pair's pricing actually moves. This is genuinely informative about a market's volatility in a way a static screenshot isn't.
A price alert — trigger a notification when a quote crosses a threshold. Still no wallet required.
A web UI — swap @ston-fi/omniston-sdk for @ston-fi/omniston-sdk-react and the same logic becomes the useRfq() hook, with loading and error states handled for you.
Actual swapping — the step you deliberately skipped. Branch on quote.settlementData?.$case, call tonBuildSwap() for swap quotes, sign the returned messages with TonConnect, and track the result with swapTrack().

The reason to arrive at that last step after building this one is that by then you already understand the quote lifecycle, the units, and the event model. Signing becomes the only genuinely new thing you're learning — rather than one unfamiliar piece among five, at the exact moment real funds enter the picture.

🔗 Sources & Further Reading

STON.fi Developer Docs — Omniston Node.js SDK (v1beta8): https://docs.ston.fi/developer-section/omniston/sdk/nodejs
STON.fi Developer Docs — Omniston React SDK: https://docs.ston.fi/developer-section/omniston/sdk/react
STON.fi Developer Docs — Omniston overview: https://docs.ston.fi/developer-section/omniston
Omniston Quickstart Guide (React): https://docs.ston.fi/developer-section/quickstart/omniston
@ston-fi/omniston-sdk on npm: https://www.npmjs.com/package/@ston-fi/omniston-sdk
Omniston SDK — GitHub source, CHANGELOG, and example app: https://github.com/ston-fi/omniston-sdk
STON.fi DEX API Reference: https://docs.ston.fi/developer-section/dex/api/reference

This walkthrough reflects the STON.fi and Omniston SDK documentation as of mid-2026 (v1beta8 API surface). The SDK is pre-1.0 and under active development — method signatures, event shapes, and quote field names can change between minor releases. Verify against the current docs at docs.ston.fi and the SDK's CHANGELOG before building anything production-facing, and inspect the live quote object rather than assuming field names from any written guide.

How Do Referral Fees Affect an Omniston Widget Quote?

Web3KD — Tue, 15 Sep 2026 08:56:37 +0000

How Do Referral Fees Affect an Omniston Widget Quote?

STON.fi / Omniston integration guide • Updated September 14, 2026

Referral fees in the STON.fi Omniston Widget are more than a payout setting for the integrator. Once a referral fee is configured, it becomes part of the request for quote itself — which means the quote shown to the user is calculated with that fee already included in the trade economics.

That distinction matters more than it might first appear. The fee is not simply added after Omniston finds a price, and it is not a hidden surcharge applied once the user accepts a quote. Omniston receives the referral parameters together with the RFQ, resolvers compete under those conditions, and the resulting quote describes what the trader pays and receives after the relevant fees have already been incorporated into the calculation.

For anyone embedding the Widget, the practical consequence is direct: changing the referral fee can change the displayed rate, the amount received, the amount required for an exact-output trade, and — in some cases — even which liquidity routes remain competitive or available at all.

💭 The mental model that causes the most confusion here is treating a referral fee like a service charge stapled onto an invoice after the total is calculated. It isn't. It's closer to a constraint handed to the pricing engine before it starts searching — which is why the effect isn't always a clean subtraction.

⚙️ How the Widget Passes a Referral Fee Into Omniston

The public Widget configuration exposes two referral-related fields:

referrerAddress — the TON wallet address that receives the integrator fee.
referrerFeeBps — the requested fee in basis points, where 1 basis point equals 0.01%.

The documented programmatic range is 1 to 100 bps, or 0.01% to 1%. A value of 50 therefore means a 0.5% referral fee.

In practice, configuring this looks like:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://your-app.example/tonconnect-manifest.json',
    },
  },
  widget: {
    referrerAddress: 'EQB_yourReferralWallet...',
    referrerFeeBps: 50, // 0.5%
  },
});

At the Omniston protocol level, the same idea surfaces in quote requests as referrer_address and referrer_fee_bps. Because these values are submitted as part of the RFQ, the resolver is never quoting a fee-free trade and then attaching an integrator charge afterward. It is quoting the trade under the requested fee conditions from the very start of the pricing process.

Key idea: a referral fee is part of the RFQ itself. The quote the user sees is therefore already calculated under that fee configuration, rather than receiving an extra referral deduction after pricing.

🔍 The Quote the User Sees Is Already Fee-Aware

Omniston's swap documentation defines these two fields precisely:

Field	Definition
`bid_units`	The amount of the bid asset the trader must pay, including all fees
`ask_units`	The amount of the ask asset the trader receives, after all fees

The quote also contains dedicated referral-fee fields, including the referral fee amount and the fee asset it's denominated in.

This is the single most important concept for understanding the Widget's numbers. If a referral fee is active, the displayed exchange outcome should be treated as a net quote — not as a raw market price still awaiting an additional referral deduction.

In practice, that means the user should evaluate the quote exactly as displayed: how much is being spent, how much is being received, and what route is being offered. The integrator fee is already baked into the conditions that produced those numbers, which is precisely why there's no "hidden charge" moment later in the flow.

↔️ What Changes for Exact-Input and Exact-Output Trades

Omniston can quote with either the input side or the output side fixed. Referral fees affect these two directions differently from the user's perspective, and the difference is worth understanding separately rather than assuming symmetry.

Exact input: the user fixes how much to spend

If the user wants to swap a fixed amount of the bid asset, that bid amount represents the total amount paid, including fees. Omniston then competes to maximize the ask amount the user receives under those conditions.

With a higher referral fee, the resulting output may become less favorable compared with an otherwise identical fee-free request. However — and this is the part that surprises integrators — the difference is not guaranteed to equal the referral percentage exactly. A new RFQ can surface a different resolver, a different pool, a different split route, or a different effective market price altogether.

Exact output: the user fixes how much to receive

If the user requests a fixed ask amount, that target represents what the trader wants to receive after fees. The quote therefore has to work backward to determine how much input is required to satisfy that net output.

In this direction, increasing the referral fee tends to show up as a higher required bid amount rather than a lower displayed ask amount. Again, the result is route-dependent: the fee changes the economic constraints of the quote, and Omniston searches for the best available deal under those revised constraints.

📐 Why a 0.5% Fee Doesn't Always Make a Quote Exactly 0.5% Worse

It's tempting to assume a 50 bps referral fee should mechanically make every quote 0.5% worse. That is not how an aggregator behaves.

The referral rate is one component of the RFQ, but the final quote also depends on liquidity depth, pool fees, price impact, resolver competition, route composition, and which protocols can actually support the requested referral configuration. When the referral fee changes, Omniston can effectively be solving a different routing problem — not the same problem with a percentage shaved off the end.

Consider two requests with the same token pair and trade size:

Request	Referral fee	What Omniston evaluates
A	0 bps	Best available quote without integrator referral revenue
B	50 bps	Best available quote that can satisfy a 0.5% referral fee

The second quote may use the same route with slightly different net economics, or it may select an entirely different route. Therefore, the cleanest way to measure the real user cost of a referral setting is to compare live quotes using the same pair, direction, amount, and market conditions — rather than subtracting the fee percentage from a theoretical spot price and calling it the answer.

🚧 Referral Fees Can Affect Route Eligibility

The effect becomes especially visible when comparing STON.fi DEX versions. According to the current Omniston referral-fee documentation:

DEX v1 has a fixed maximum referral fee of 0.1% (10 bps)
DEX v2, DeDust, Tonco, CoffeeSwap, and Escrow can support configurable referral fees from 0.01% to 1%

Suppose an integrator requests a 30 bps fee. A DEX v1 pool simply cannot satisfy that fee as requested. At the protocol level, a strict 30 bps request can therefore prevent a v1 route from being used at all — even if that pool would otherwise offer the strongest underlying price for the trade.

Omniston provides a lower-level flexible_referrer_fee settlement option for exactly this situation. When enabled, the protocol may reduce the effective referral fee when doing so unlocks a better route for the trader. The documentation gives the concrete example of reducing a 30 bps request down to the 10 bps maximum supported by DEX v1, if that produces a better overall swap rate.

One important detail for Widget integrators: the current public Widget configuration table documents referrerAddress and referrerFeeBps, but it does not list flexible_referrer_fee as a Widget configuration field. Developers who need explicit control over that settlement behavior should consult the lower-level Omniston SDK or API documentation rather than assuming the Widget exposes the same parameter.

🏦 The Payout Mechanism Doesn't Change What the Quote Means

Where the integrator eventually receives the fee depends on the route — but this settlement detail should not be confused with quote calculation itself.

Route	How the referral fee is paid
STON.fi DEX v1	Paid on-chain within the same swap transaction
STON.fi DEX v2	Accumulates in a dedicated vault, claimed later
DeDust, Tonco, CoffeeSwap	Separate fee-vault mechanism for jetton-denominated fees; TON-denominated fees credited directly during the swap
Escrow	Uses its own fee-vault contracts

These differences matter operationally for the integrator — they affect cash-flow timing and claiming workflows. But the user's quote remains fee-aware regardless. A fee being stored in a vault rather than transferred immediately does not mean it sits outside the quoted trade economics.

📊 What an Integrator Should Monitor

Referral revenue is attractive because it lets a product monetize swap flow without building its own execution layer. But the fee level is also a product decision — it changes the economic conditions presented to your users.

A practical monitoring framework tracks several things together:

Net ask amount for exact-input trades. Compare what users actually receive at different referral settings.
Required bid amount for exact-output trades. Measure how much additional input is needed to preserve the same target output.
Route and protocol mix. Watch whether higher fees quietly reduce the use of routes that would otherwise be competitive.
Quote competitiveness. Compare your Widget's net quote against a zero-fee or lower-fee control under similar market conditions.
Conversion behavior. A higher fee can increase revenue per completed swap while potentially reducing completion rate if users notice worse pricing.

The optimal fee is therefore not automatically the maximum 100 bps. The best setting depends on the balance between monetization and execution quality for the specific audience using your Widget.

🧪 A Simple Way to Test Impact Before Choosing a Fee

Before publishing a referral setting, run repeated quote comparisons across the token pairs and trade sizes that actually matter to your users.

For each test case, request or observe the same trade at several fee levels — for example 0, 10, 30, and 50 bps — and record the final bid and ask amounts. Repeat the comparison over time, because routing and liquidity conditions change independently of your configuration.

Do not judge the result only by the referral percentage. What matters is the net difference in the actual quote. A 30 bps fee that leaves route quality almost unchanged may be far less noticeable to users than a smaller fee that happens to exclude a particularly efficient route for a specific pair.

If you're working with the lower-level Omniston SDK or API, also test the flexible-referrer-fee behavior whenever your requested rate exceeds 10 bps. That can reveal whether accepting a smaller fee on some trades improves execution enough to increase swap completion — and, counterintuitively, total referral revenue.

🎯 Final Takeaway

Referral fees in the Omniston Widget are part of quote formation, not an afterthought added after pricing. The configured referrerFeeBps becomes part of the RFQ, and Omniston returns a fee-aware result in which the trader's input is defined including fees and the expected output is defined after fees.

For an exact-input trade, a referral fee can reduce the net amount received. For an exact-output trade, it can increase the amount the trader needs to spend. More importantly, the fee can change routing itself — so the difference between two quotes is rarely a simple percentage calculation.

That is why referral-fee optimization should be treated as an execution-quality problem as much as a monetization problem. The right question isn't only, "How much can the integrator earn per swap?" It's also, "What net quote does the user actually receive once Omniston has re-optimized the trade under that fee?"

❓ Frequently Asked Questions

Does the user see the referral fee as a separate line item?
Not as an additional deduction applied after pricing. The quote's bid_units already includes all fees and ask_units already reflects the amount received after fees — though the quote does contain dedicated referral-fee fields describing the fee amount and asset.

Why did raising my fee by 20 bps change the output by more (or less) than 20 bps?
Because the referral fee is a constraint inside the RFQ, not a post-pricing subtraction. A different fee can lead Omniston to select a different resolver, pool, or split route entirely — so the net difference reflects a re-optimized trade, not just the arithmetic.

Can a referral fee make a route unavailable?
Yes. DEX v1 supports a maximum of 10 bps, so a strict request above that can exclude v1 routes even when they'd otherwise offer the best underlying price. The lower-level flexible_referrer_fee option exists to let the protocol reduce the fee when doing so unlocks a better route.

Is the maximum 100 bps fee the best choice for revenue?
Not necessarily. Higher fees increase revenue per completed swap but can worsen displayed pricing and reduce completion rate. Testing across realistic pairs and trade sizes is the only reliable way to find the balance for your specific audience.

📚 Sources and References

STON.fi — Full Guide & Reference for the Omniston Widget: https://docs.ston.fi/developer-section/widget/widget
STON.fi — Omniston Referral Fees: https://docs.ston.fi/developer-section/omniston/referral-fees
STON.fi — Omniston Swap Overview / Quote Fields: https://docs.ston.fi/developer-section/omniston/swap/overview
STON.fi — Omniston Widget GitHub Repository: https://github.com/ston-fi/omniston-widget

Tags: STON.fi, Omniston, Referral Fees, Widget Integration, RFQ, Quote Formation, TON Blockchain, DeFi Development

SDK Integration Walkthrough: Building Your First STONfi Swap Feature

Web3KD — Sat, 05 Sep 2026 12:53:41 +0000

SDK Integration Walkthrough: Building Your First STONfi Swap Feature

Most SDK documentation shows you the happy path in five clean lines and leaves the actual engineering — the part where quotes expire, wallets reject signatures, and networks hiccup mid-transaction — as an exercise for whoever ships it to production. This is the walkthrough I wish I'd had before my first integration.

I've watched a lot of developers get a STONfi swap working in an afternoon, feel great about it, and then spend the following week discovering everything the happy-path demo quietly skipped. That's not a criticism of the SDK — it's just what happens when documentation optimizes for "does this work" instead of "does this survive contact with real users, real network conditions, and real wallets that sometimes reject things." This walkthrough goes through the same ground a typical quickstart covers, but stays a little longer at each step than a quickstart usually does, specifically at the points where I've seen integrations quietly break in production.

My take: The gap between "my demo works" and "my integration is production-ready" isn't more features. It's almost entirely error handling for cases the demo never triggers, because demos are, by construction, always the happy path.

🧩 Setting Up and Requesting Your First Quote

Before building anything, you need a client instance connected to STONfi's infrastructure. The basic setup is intentionally minimal:

import { StonApiClient } from '@ston-fi/api';

const client = new StonApiClient();

async function getQuote(offerToken, askToken, amount) {
  const quote = await client.simulateSwap({
    offerAddress: offerToken,
    askAddress: askToken,
    offerUnits: amount,
    slippageTolerance: "0.01", // 1% — set explicitly, not left to a default
  });

  return quote;
}

That slippageTolerance line deserves more attention than it usually gets in a first pass. Leaving it to whatever the SDK defaults to means your app's behavior under volatile market conditions is whatever some library maintainer decided was reasonable in the abstract, for every possible use case, which is rarely what your specific product actually needs. A wallet app aggregating small casual swaps and a trading terminal handling larger, time-sensitive orders should almost certainly not share the same default — set it explicitly and treat the value as a product decision, not a technical formality you can skip past.

The quote object you get back contains more than just an expected output amount. It carries askUnits (the optimistic expected output), minAskUnits (the guaranteed floor, accounting for your slippage tolerance), a route, fee information, and an expiry timestamp. Every one of those fields matters for what comes next — none of them are safe to ignore just because the demo only ever prints askUnits to the console.

🔻 Building the Transaction Without the One Bug That Silently Breaks Slippage Protection

This is the step where I've seen the most integrations quietly ship a real bug that never shows up in testing, because testing rarely includes the specific market conditions that expose it.

async function buildSwapTransaction(quote, userWalletAddress) {
  // Reject stale quotes before doing anything else
  if (Date.now() > quote.expiresAt) {
    throw new Error('Quote expired — request a fresh one before building the transaction');
  }

  const transaction = await client.buildSwapTransaction({
    userWalletAddress,
    offerAddress: quote.offerAddress,
    askAddress: quote.askAddress,
    offerUnits: quote.offerUnits,
    minAskUnits: quote.minAskUnits, // NOT quote.askUnits
  });

  return transaction;
}

The comment on that last line is doing the most important work in this entire snippet. askUnits is the optimistic number — what you'd get if nothing moved between quote and execution. minAskUnits is the actual floor your slippage tolerance is supposed to guarantee. Pass the wrong one into transaction construction and your code compiles, your tests pass, your demo works perfectly in a quiet market — and your slippage protection silently does nothing the first time a real price movement happens, because you've told the transaction to accept the optimistic number as if it were the guarantee. Nobody notices until a user reports getting a worse fill than expected during a volatile hour, and by then it's a support ticket instead of a code review comment.

The expiry check at the top matters just as much, for a less dramatic but equally real reason: submitting a transaction built from a stale quote doesn't fail gracefully in every wallet and every network condition. Checking client-side, before you even attempt to build the transaction, gives you a clean error message to show the user instead of an opaque on-chain rejection they'll have no context for.

⚙️ Handling the Wallet Connection and Signature Flow

Getting a transaction object is only useful if you can actually get it signed. This is the step where TON Connect enters the picture, and where a surprising amount of production bugs live in how errors from this specific step get surfaced to the user.

import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://yourapp.com/tonconnect-manifest.json',
});

async function signAndSend(transaction) {
  try {
    const result = await tonConnectUI.sendTransaction({
      validUntil: Math.floor(Date.now() / 1000) + 300, // 5-minute signing window
      messages: [
        {
          address: transaction.to,
          amount: transaction.value,
          payload: transaction.payload,
        },
      ],
    });

    return { status: 'submitted', boc: result.boc };
  } catch (error) {
    if (error.message?.includes('Reject')) {
      return { status: 'rejected_by_user' };
    }
    return { status: 'failed', error };
  }
}

That catch block is doing more product work than it looks like at first glance. A user closing the wallet popup without signing and a genuine network or contract-level failure are fundamentally different events — one is a deliberate, informed decision, the other is a technical problem — and they deserve different messages in your UI. Collapsing both into a single generic "Transaction failed" toast is one of the most common ways a perfectly functional integration ends up feeling broken to users, because a user who intentionally declined to sign gets told something went wrong, when nothing actually did.

The validUntil field is worth setting deliberately rather than accepting whatever default the library ships with, for the same underlying reason the quote expiry mattered earlier: a signing window that's too long increases the odds a user comes back to a stale popup after getting distracted, and a window that's too short creates failures for users who take a normal amount of time to review what they're signing.

🔍 Simulating Before You Ever Touch Real Funds

Before shipping any of the above against mainnet, there's a step worth treating as non-negotiable rather than optional: running the full flow against a simulated or testnet environment, deliberately, against every failure case you can construct, not just the happy path.

async function testFailureCases() {
  const cases = [
    { name: 'expired quote', setup: async () => {
      const quote = await getQuote(TOKEN_A, TOKEN_B, 1000n);
      await new Promise(r => setTimeout(r, quote.expiresAt - Date.now() + 1000));
      return quote;
    }},
    { name: 'insufficient gas balance', setup: async () => {
      // wallet funded with the offer token but zero TON for fees
      return getQuote(TOKEN_A, TOKEN_B, 1000n);
    }},
    { name: 'slippage exceeded mid-execution', setup: async () => {
      // quote requested, then a large counter-trade simulated before signing
      return getQuote(VOLATILE_TOKEN, TOKEN_B, 1000n);
    }},
  ];

  for (const testCase of cases) {
    console.log(`Testing: ${testCase.name}`);
    const quote = await testCase.setup();
    const result = await buildSwapTransaction(quote, TEST_WALLET).catch(e => ({ error: e.message }));
    console.log(result);
  }
}

This isn't a complete test suite — it's a sketch of the mindset that matters more than any specific test framework. Each of these cases corresponds to a real failure a real user will eventually trigger, not a hypothetical edge case invented for thoroughness. If your integration's behavior for each of them is "generic error toast," that's a signal to go back to the error-handling step above before considering the integration done, not a acceptable place to stop.

🧭 What Changes When You Move This to Production

A few things stop being optional the moment real users and real funds are involved, beyond what a local test run naturally covers. Rate limiting on quote requests matters — a user rapidly adjusting a trade amount shouldn't fire a new quote request on every keystroke, both for your own API usage and for giving the user a stable number to actually read before it changes again. Idempotency on the submission step matters too — a double-tapped confirm button, common on mobile under lag, shouldn't be able to submit the same transaction twice, which is a UI-layer guard your SDK integration doesn't provide for you automatically.

My take: Almost none of the production hardening described here shows up in an SDK's own documentation, and that's not really a gap in the docs — it's inherent to the fact that an SDK can tell you how to call it correctly, but it can't tell you how your specific product should behave when a user does something the happy path never anticipated.

It's also worth logging enough context at each step — which quote was used, what the expiry was, what error category was hit — that when a support ticket comes in about a confusing failure, you're not reconstructing what happened from a raw transaction hash and a user's incomplete memory of what they clicked.

🧭 Conclusion

A working STONfi swap integration and a production-ready one are separated less by code volume than by how many of the cases above got deliberate attention instead of getting left as whatever the SDK happened to do by default. Reading minAskUnits instead of askUnits, checking quote expiry before building a transaction, distinguishing a user's rejection from an actual failure, and testing against constructed failure cases rather than only the happy path — none of this is exotic engineering. It's the unglamorous difference between a demo that works once, in a quiet market, on a good network day, and an integration that keeps behaving correctly on the day none of those three things are true.

❓ Frequently Asked Questions

Why does using askUnits instead of minAskUnits matter if the quote already accounted for slippage?
The quote calculates both values, but only minAskUnits is the enforced floor. Passing askUnits into the transaction means no real floor is being enforced at all, regardless of what slippage tolerance you originally requested.

Should slippage tolerance ever be left at an SDK's default value?
It's better treated as a product decision made deliberately for your specific use case — a casual small-swap app and a professional trading interface have different needs, and a shared default rarely fits both well.

Is checking quote expiry client-side actually necessary if the chain will reject a stale transaction anyway?
Yes — a clean client-side check lets you show the user a clear, immediate message and offer a fresh quote, instead of relying on an on-chain rejection that arrives later with no context for what to do next.

How much failure-case testing is actually enough before shipping?
At minimum, every case a user is likely to trigger in normal use — expired quotes, rejected signatures, insufficient gas, and slippage exceeded mid-execution — should have an explicit, deliberate behavior, not a generic fallback.

📚 Sources and Further Reading

Tags: STONfi, SDK, TON Connect, Developers, TON Blockchain, DeFi, Web3

Disclosure: Official STONfi Ambassador.

Quote Expiration: Why DeFi Prices Cannot Be Treated Like Static API Responses

Web3KD — Fri, 04 Sep 2026 14:38:03 +0000

Quote Expiration: Why DeFi Prices Cannot Be Treated Like Static API Responses

Cache a weather API response for thirty seconds and nothing bad happens. Cache a swap quote for thirty seconds and you can end up building a transaction against a price that's no longer true. The difference isn't a technicality — it changes how the entire integration has to be built.

Most developers coming into DeFi from traditional web development carry a mental model that quietly breaks the first time they build a swap feature: a price is data, and data can be fetched, stored, and reused for a little while before it needs refreshing. A product listing, a currency conversion rate, a weather forecast — all reasonably treated as short-lived but essentially static once returned. A DeFi quote looks like the same shape of object — a JSON payload with a number in it — and that resemblance is exactly what causes bugs. It isn't a cacheable fact. It's a live, competitive, time-boxed offer from a specific counterparty, and Omniston's own API is built around that distinction explicitly rather than leaving it implicit.

💭 The bug I've seen most often isn't exotic — it's a developer calling a quote endpoint once, storing the number in state, and building the transaction from that stored value minutes later. Nothing in a REST-shaped response warns you not to do that. The protocol has to make the time-boxed nature structural, not just documented.

✅ Key Takeaways

A DeFi quote is a live offer from a specific resolver or pool state, not a fetched fact — it degrades in accuracy the moment it's issued.
Omniston models this by returning quotes as a subscribable RFQ stream, not a single request/response call, so re-quoting is the default behavior, not an opt-in refresh.
Quotes carry explicit time-boxing fields — validity windows and trade-start deadlines — that a transaction must respect to guarantee the quoted price.
Treating quote expiration as a UI afterthought (a toast that says "price changed") produces worse UX than designing the interface around expiration as an expected, routine state from the start.
Building a transaction from a stale quote isn't just risky — it can fail outright, since expired quotes aren't meant to settle at all.

🌐 Why the REST Mental Model Breaks Here

A typical REST API response represents something that was true at request time and stays reasonably true for a while — a product's list price, a city's current temperature. The implicit contract is: fetch once, trust for some duration, refetch when you need fresher data. Nothing about that contract requires the client to actively track an expiration deadline as part of correctness — staleness is usually a UX nuisance, not a source of financial loss.

A swap quote breaks that contract in a specific, structural way: it represents a price a counterparty — a pool's current reserves, or a resolver's live inventory — is willing to honor right now, and that willingness has a real, finite shelf life measured in seconds, not minutes. Unlike a stale weather reading, a stale quote doesn't just become "a bit inaccurate" — building and submitting a transaction against it can fail outright, or in worse designs, execute at a materially different price than the user actually saw and approved.

🔄 How Omniston Encodes This Structurally: A Stream, Not a Call

Rather than exposing quotes as a single GET /quote request, Omniston's requestForQuote() returns an observable stream that a client subscribes to:

import { Omniston, Blockchain, SettlementMethod } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({ apiUrl: "wss://omni-ws.ston.fi" });

const quoteStream = omniston.requestForQuote({
  settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
  offerAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
  },
  askAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  },
  amount: { offerUnits: "1000000" }, // 1 USDT
  settlementParams: {
    maxPriceSlippageBps: 500, // 5% max slippage
    maxOutgoingMessages: 4,
  },
});

quoteStream.subscribe((quoteEvent) => {
  // A fresh quoteEvent can arrive multiple times over the stream's lifetime —
  // resolvers and pools re-quote as conditions change, not just once
});

This is a deliberate design choice, not an incidental one. A WebSocket-backed stream means the default behavior is continuous re-quoting as market conditions shift, rather than a client having to remember to poll again. An integration that subscribes and simply keeps the most recent event is automatically working with a reasonably fresh price, without needing to build its own refresh-timer logic on top of a request/response API.

⏱ The Fields That Make Expiration Explicit, Not Implicit

Underneath the SDK's convenience layer, Omniston's protocol-level messages carry explicit timing fields that turn "this quote is time-limited" from a documentation note into something a client can programmatically check:

message QuoteRequestedEvent {
  string rfq_id = 1;                  // Quote request ID
  sint64 request_timestamp = 4;       // When the request was made
  sint64 quote_validity_timeout = 5;  // How long the quote should remain valid
  sint64 resolve_timeout = 7;         // Max time allowed to complete the trade
}

message UpdateQuoteRequest {
  string rfq_id = 1;
  uint64 trade_start_deadline = 4;    // Quote expiration timestamp
}

quote_validity_timeout and trade_start_deadline aren't cosmetic metadata — they're the actual contract a resolver is offering: this price, if and only if execution starts before this deadline. A transaction built and submitted after that deadline isn't just "risking a worse price" the way slippage tolerance handles ordinary market movement — it's outside the terms of the quote entirely, and settlement logic is built to reject or fail it rather than silently execute at a different rate.

🧩 What This Looks Like When Actually Building the Transaction

Because the quote is time-boxed, building a transaction from it means carrying that deadline forward into the transaction itself — not just displaying a price and hoping the user confirms quickly:

// Conceptual shape — building a transaction needs to reference
// both the specific quote and the window it's valid within
const tx = await omniston.buildTransfer({
  quote,                 // the exact quote object from the stream above
  sourceAddress,
  destinationAddress,
  // The settlement layer enforces the quote's own deadline —
  // a transaction submitted after trade_start_deadline is expected to fail
  // rather than silently settling at a different price
});

The important design principle here: the deadline isn't something the client application invents on its own (like an arbitrary "5 minute cache" rule borrowed from REST habits) — it's a value the resolver itself set when it made the offer, carried through the quote object, and enforced at settlement. A client can't extend it by simply waiting longer or retrying with the same stale data.

🎨 The UX Problem This Actually Creates

Handling expiration correctly at the protocol level solves half the problem. The other half is interface design, and it's where a lot of otherwise well-built integrations still fall short:

Treating expiration as an edge case, not a routine state. If a user takes 15 seconds to review a quote before confirming, hitting an expired quote shouldn't feel like an error state — it should feel like a normal, expected part of using the app, handled by quietly re-quoting rather than surfacing a raw failure.
Not showing any indication that a quote is time-limited at all. A price displayed with no visual cue that it's a live, decaying offer trains users to treat it like a static number — the same misconception that causes the caching bug in the first place, just moved from the developer to the end user.
Blocking confirmation entirely without a graceful re-quote path. The better pattern is subscribing to the stream continuously in the background so the displayed price updates itself, and confirmation simply uses whatever the most recent valid quote happens to be at the moment of the click.

💭 The best version of this UX is almost invisible: the number on screen just quietly stays current, and the user never consciously notices that "quote expiration" was ever a problem being solved underneath. The worst version throws an error message after the user already clicked confirm.

🛡 Why This Matters More for Cross-Chain and RFQ-Sourced Quotes

Expiration windows aren't uniform across every kind of quote. A quote priced against a deep, stable AMM pool tends to have more forgiving timing, since the underlying reserves move relatively slowly. A quote sourced from an RFQ resolver — especially for a cross-chain trade settling through paired HTLCs — is a live commitment from a specific market maker, often with a tighter validity window, since the resolver is exposing its own capital to price risk for the duration of that offer. Cross-chain flows add a further wrinkle: resolve_timeout governs not just how long the quote is valid to start, but how long the overall trade has to complete across both chains before the settlement window closes — a distinctly different timing concern from same-chain execution.

An integration that treats every quote as having the same generous shelf life, regardless of settlement method, is likely to either annoy users with unnecessarily aggressive re-quoting on stable pairs, or — worse — attempt to execute stale RFQ-sourced quotes that were never going to be honored past their deadline.

🧭 Conclusion

Quote expiration isn't a quirky edge case bolted onto DeFi APIs — it's a direct consequence of what a quote actually represents: a live, time-boxed commitment from a specific counterparty, not a cacheable fact about the world. Omniston's design reflects that at the protocol level, with a subscribable RFQ stream in place of a single request/response call, and explicit validity and deadline fields carried through to settlement rather than left to client-side assumption. The remaining responsibility sits with whoever builds the interface on top: designing around expiration as a routine, invisible background process, not an error state the user discovers after the fact.

❓ Frequently Asked Questions

Can a client just increase how long it waits before treating a quote as stale?
No — the validity window and trade-start deadline are set by the resolver or protocol issuing the quote, not by the client. A client can request a fresh quote at any time, but it can't extend the validity of an existing one past what was actually offered.

Does every quote on Omniston expire at the same rate?
No. Quotes sourced from a deep, stable AMM pool tend to tolerate slightly more delay than RFQ-sourced quotes from an individual resolver, since the resolver is exposing its own capital to price risk for as long as the quote remains valid.

What happens if a transaction is submitted after a quote's deadline has passed?
It's expected to fail at settlement rather than silently execute at a different price — the deadline is enforced as part of the quote's terms, not treated as a soft suggestion.

Is subscribing to a quote stream instead of polling actually necessary, or just a nice-to-have?
It's closer to necessary for correctness. Polling on a fixed interval risks either showing stale prices between polls or hammering the API with unnecessary requests; a subscription model delivers updates exactly when the underlying price actually changes.

📚 Sources and Further Reading

Omniston Node.js SDK — requestForQuote as an observable RFQ stream: https://docs.ston.fi/developer-section/omniston/omniston-nodejs
How to Become a Resolver — Protocol-level fields including quote_validity_timeout and trade_start_deadline: https://docs.ston.fi/developer-section/omniston/resolvers/guide
Omniston Protocol Overview — Settlement methods and quote lifecycle: https://docs.ston.fi/developer-section/omniston
Omniston React SDK — useTrackTrade and quote-to-trade flow: https://docs.ston.fi/developer-section/omniston/omniston-react

Tags: STON.fi, Omniston, DeFi UX, Quote Expiration, RFQ, TON Blockchain, Developer Tools, Slippage

Cross-Chain Routing: Comparing DEX Liquidity and RFQ Liquidity

Web3KD — Wed, 26 Aug 2026 09:23:34 +0000

Cross-Chain Routing: Comparing DEX Liquidity and RFQ Liquidity

Two completely different sourcing models sit behind the same "swap" button — one prices against on-chain reserves, the other prices against a competing network of market makers. Cross-chain routing is where the difference between them stops being academic and starts being the whole system.

Same-chain routing gets away with a simplification that cross-chain routing can't: on one chain, "check the pools" and "get a price" are almost the same operation. The moment a route crosses from TON to an EVM chain or vice versa, that simplification breaks. There's no single shared pool spanning both chains — there can't be, since two independent blockchains have no native way to verify each other's state. Something else has to source the liquidity and guarantee settlement, and that's where the split between DEX-pool liquidity and RFQ-sourced liquidity stops being a footnote and becomes the core design decision.

This piece walks through both models concretely — what each one actually is, how Omniston's SDK exposes them as distinct settlement branches in code, and why cross-chain routing in particular tends to lean on RFQ far more than same-chain routing does.

💭 My honest take: people often describe RFQ liquidity as "the cross-chain version of an AMM pool," as if it's just a variant of the same idea. It isn't. A pool is a formula anyone can query. RFQ is a live negotiation with a counterparty who has to actually show up and deliver. Cross-chain routing depends on that distinction more than any other part of the stack.

✅ Key Takeaways

DEX pool liquidity is fully on-chain and formula-priced; it works well within a single chain but has no native way to span two independent chains.
RFQ liquidity is sourced from resolvers — market makers with real capital who quote and then have to deliver — making it viable across chains where no shared pool can exist.
Cross-chain settlement in Omniston is handled through paired HTLCs, not through a pool's reserves being adjusted on both sides.
Omniston's settlementParams API lets an integration explicitly choose swap-only, order-only, or both — a direct, code-level expression of the DEX-vs-RFQ choice.
The trade-off is consistent: DEX liquidity is trustless but chain-bound; RFQ liquidity crosses chains but depends on active, capitalized resolvers actually being available.

🏊 DEX Liquidity: What It Is and Where It Stops Working

A DEX pool prices a trade against its own on-chain reserves using a formula — commonly a constant-product model, x·y = k. Anyone can query the current reserves, anyone can predict the resulting price, and settlement is a single atomic transaction on one chain. This works because both sides of the trade live in the same execution environment, with the same finality guarantees, updated by the same state.

That last part is exactly what breaks across chains. TON's state and, say, an EVM chain's state aren't mutually visible or verifiable to each other in real time. There's no shared pool that could sit "between" them, because a pool needs a single source of truth for its reserves, and two independent blockchains don't share one. A DEX pool model, taken as-is, simply has no native answer to the question "how do I settle half of this trade on a chain the pool doesn't live on?"

🤝 RFQ Liquidity: Solving the Problem a Pool Can't

RFQ — Request for Quote — liquidity works differently from the ground up. Instead of pricing against a formula anyone can query, a swap request is broadcast to a network of resolvers: market makers who hold their own capital, often on multiple chains simultaneously, and respond with a live, competitive quote. The resolver isn't reading a shared pool — it's offering to fulfill the trade from its own inventory, wherever that inventory happens to sit.

This is precisely the piece that makes cross-chain routing possible at all. A resolver with capital on both TON and an EVM chain can quote a trade that starts on one and settles on the other, because it isn't constrained by needing a single, mutually-visible pool. The trade-off is equally direct: RFQ liquidity requires an actual, willing, sufficiently capitalized resolver to exist for that specific pair and route. No resolver, no quote — where a DEX pool at least always returns some price, however poor, an empty RFQ market returns nothing at all.

⚙️ How Settlement Actually Differs Underneath

Same-Chain: One Formula, One Transaction

On a single chain, whether the quote came from a pool or a resolver, settlement can complete as one atomic transaction — the trade either fully executes or fully reverts, and both sides are visible to the same chain's consensus at the same moment.

Cross-Chain: Paired HTLCs, Not a Shared Pool

Cross-chain settlement in Omniston works through Hashed Timelock Contracts (HTLCs) — paired, not shared:

The trader's asset locks into an HTLC on the source chain, tied to a cryptographic secret.
The winning resolver locks the corresponding destination asset into a mirrored HTLC on the destination chain, tied to the same secret.
Once the secret is revealed, both HTLCs unlock together — the trader receives the destination asset, the resolver receives the source asset.
If the secret is never revealed before the timelock expires, both sides are refunded instead — no scenario exists where one side pays and the other doesn't.

This is the mechanical reason cross-chain routing leans on RFQ so heavily: a resolver is the counterparty that actually locks real destination-chain assets into that second HTLC. A pool's formula has no equivalent action it can take on a chain it doesn't live on.

💻 Choosing Between Them in Code

Omniston's v1beta8 API makes this choice explicit rather than implicit — an integration decides upfront which settlement branches it wants to allow, via settlementParams.

Swap-Only: Classic Pool-Style Settlement

import {
  type SettlementParams,
  type SwapSettlementParams,
} from "@ston-fi/omniston-sdk";

const swapOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "swap",
      value: {
        maxPriceSlippagePips: 10_000, // 1%
        flexibleIntegratorFee: true,
      } satisfies SwapSettlementParams,
    },
  },
];

This branch is what you'd reach for on a simple, same-chain TON flow — a single atomic transaction settled directly, the closest analog to a traditional pool-based swap.

Order-Only: RFQ-Backed, HTLC-Settled

import {
  type SettlementParams,
  type OrderSettlementParams,
} from "@ston-fi/omniston-sdk";

const orderOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "order",
      value: {} satisfies OrderSettlementParams,
    },
  },
];

This branch is for applications built specifically around signed orders or HTLC flows — exactly the shape cross-chain routing needs, since it's resolver-fulfilled rather than pool-settled.

Letting Omniston Decide: Requesting Both

const swapAndOrderSettlementParams: SettlementParams[] = [
  ...swapOnlySettlementParams,
  ...orderOnlySettlementParams,
];

const quoteStream = omniston.requestForQuote({
  settlementParams: swapAndOrderSettlementParams,
  bidAssetAddress: { blockchain: sourceChain, address: offerAssetAddress },
  askAssetAddress: { blockchain: destinationChain, address: askAssetAddress },
  amount: { bidUnits: offerAmount },
});

quoteStream.subscribe((quoteEvent) => {
  // quoteEvent.settlementData?.$case tells you which branch actually won —
  // "swap" (pool-style) or "order" (resolver/HTLC-based cross-chain)
});

Requesting both settlement methods and branching on quote.settlementData?.$case is the practical, code-level version of "compare DEX liquidity and RFQ liquidity, then use whichever actually won" — the decision isn't made by the integrator ahead of time; it's made per-request, based on what's actually available.

Disclosing the HTLC Secret for a Cross-Chain Order

For order-flow settlement where the application manages the secret itself, that secret needs to be disclosed once execution is ready to complete:

const disclosure = await omniston.discloseHtlcSecret({
  quoteId: quote.quoteId,
  secret: htlcSecret,
});
// Disclosing the secret is what allows both paired HTLCs — source and
// destination — to unlock together, completing the atomic settlement

This step has no equivalent at all in pool-based swap settlement — it only exists because cross-chain settlement is built on the shared-secret mechanics of paired HTLCs, not on adjusting a single pool's reserves.

⚖️ Side-by-Side: What Actually Differs

	DEX Pool Liquidity	RFQ Liquidity
Price source	On-chain formula (e.g., x·y=k)	Live quote from competing resolvers
Works natively cross-chain	No — bound to a single chain's state	Yes — resolvers can hold capital across chains
Settlement mechanism	Single atomic on-chain transaction	Paired HTLCs, unlocked by a shared secret
Availability	Always returns a price if reserves exist	Depends on active, willing resolvers
Trust model	Formula and code, fully on-chain	Resolver must actually deliver, enforced by HTLC refund logic
Omniston API branch	`settlementParams: swap`	`settlementParams: order`

🧩 Why Cross-Chain Routing Leans Toward RFQ by Default

None of this means DEX-pool liquidity is obsolete — for same-chain trades, it remains simple, fully transparent, and doesn't depend on a third party choosing to participate. But cross-chain routing specifically needs a counterparty capable of acting on the destination chain, and a pool's formula has no way to do that on a chain it doesn't exist on. RFQ liquidity isn't cross-chain routing's "alternative" option — it's closer to the only mechanism that structurally can work once two independent chains are involved, which is exactly why Omniston's cross-chain flows route through the order/HTLC branch rather than the swap branch.

🛠 Practical Considerations for Developers Building on Top of This

Choosing between (or combining) these two liquidity sources isn't purely theoretical once you're actually integrating against Omniston. A few things matter in practice:

Latency expectations differ structurally. A pool-based swap settles in one transaction with one chain's finality time. An HTLC-based cross-chain order inherently involves two separate on-chain confirmations — source-chain lock, then destination-chain lock — plus secret disclosure, so it's reasonable to design UI and status handling around a longer, multi-step timeline rather than assuming cross-chain settlement feels as instant as a same-chain swap.
requestForQuote() is a live stream, not a one-shot call. Because it can emit multiple quoteUpdated events over time as resolvers and pools update their pricing, an integration needs to treat it as an ongoing subscription — grabbing the first event and discarding the stream throws away exactly the competitive re-quoting that makes RFQ liquidity useful in the first place.
Order state needs to be restorable, not just streamed. For cross-chain orders specifically, Omniston exposes orderGetActive() as a regular request-response call so an application can restore or display existing order state — useful if a user closes a tab mid-settlement and needs to see where a paired-HTLC order actually stands when they come back.
Gas and fee handling differs by branch. A swap-only flow can lean on flexibleIntegratorFee and slippage settings tuned for a single-chain transaction. An order flow tied to HTLC settlement introduces separate considerations on both the source and destination chain, since each leg is its own on-chain action with its own gas cost.

None of this changes the core architectural point — it just means the DEX-vs-RFQ choice shows up in concrete engineering decisions, not only in how a trade gets priced.

🧭 Conclusion

DEX liquidity and RFQ liquidity aren't two flavors of the same thing — they're different answers to different questions. A pool answers "what's the price, given these reserves, on this chain, right now?" A resolver answers "will someone actually deliver the other side of this trade, including on a chain the pool can't reach?" Same-chain routing can often get away with only the first question. Cross-chain routing cannot, and Omniston's split between swap and order settlement in its own API is a direct, honest reflection of that fact — not a stylistic API choice, but a structural one.

❓ Frequently Asked Questions

Can a standard AMM pool ever settle a cross-chain trade on its own?
No. A pool's price and settlement both depend on a single chain's shared, mutually-visible state. Since two independent blockchains don't share that state, a pool has no native mechanism to lock or release assets on a chain it doesn't live on.

Is RFQ liquidity less trustworthy than a pool since it depends on a resolver showing up?
It's a different trust model, not a strictly weaker one. The resolver doesn't need to be trusted directly — HTLC-based settlement enforces that either both sides complete or both sides refund, so a resolver failing to deliver results in your funds returning, not being lost.

Why does Omniston let an integration request both swap and order settlement at once?
Because the best available option can vary per request — a same-chain trade might have excellent pool liquidity, while a cross-chain trade structurally requires the order/HTLC branch. Requesting both and branching on the returned $case lets the protocol pick the right mechanism per trade instead of the integrator guessing upfront.

What happens if no resolver is willing to quote a specific cross-chain pair?
The RFQ simply returns no viable quote for that route at that time. Unlike a pool, which will always return some price if reserves exist (however poor), RFQ liquidity depends entirely on active resolver participation for that specific pair and direction.

📚 Sources and Further Reading

Omniston Protocol Overview — Cross-chain settlement architecture and the v1beta8 API model: https://docs.ston.fi/developer-section/omniston
Omniston Node.js SDK — settlementParams, swap vs. order flow, and HTLC secret disclosure in code: https://docs.ston.fi/developer-section/omniston/sdk/nodejs
Cross-chain portfolio rebalancing: how HTLC and RFQ swaps work for DeFi users — STON.fi Blog, on combining RFQ discovery with paired-HTLC settlement: https://blog.ston.fi/cross-chain-portfolio-rebalancing-how-htlc-and-rfq-swaps-work-for-defi-users/
TON to Base, BNB Chain, and Polygon: how cross-chain crypto swaps actually work — STON.fi Blog, on bridge vs. resolver-based HTLC routing: https://blog.ston.fi/ton-to-base-bnb-chain-and-polygon-how-cross-chain-crypto-swaps-actually-work/

The DeFi API for AI Agents: What Would It Need to Look Like?

Web3KD — Mon, 24 Aug 2026 19:48:00 +0000

The DeFi API for AI Agents: What Would It Need to Look Like?

Humans read a quote, glance at slippage, and click confirm. An AI agent can't glance at anything — it needs the entire decision made of structured data it can parse, verify, and act on without a screen in between. STON.fi's Omniston protocol already looks a lot like a first draft of that answer.

Every DeFi interface built so far has one implicit assumption baked into it: a human is looking at the screen. The price is formatted for eyes. The slippage warning is a sentence, not a machine-checkable field. The "confirm" button assumes a person weighing a decision, not a program executing a policy. That assumption breaks the moment you try to hand a wallet to an autonomous agent instead of a person — and 2026 is the year that stopped being theoretical for a lot of builders on TON.

So what would a DeFi API actually need to look like if the primary caller was an AI agent instead of a human? Not "AI-themed marketing copy on a swap button" — an actual protocol-level answer. It turns out Omniston, STON.fi's liquidity aggregation and cross-chain execution layer, already satisfies more of that answer than most people give it credit for, largely because it was built API-first rather than UI-first from day one.

💭 My honest take: most "AI + DeFi" content skips straight to autonomous trading bots without asking the more boring, more important question first — what does the interface itself need to guarantee before any agent can safely act on it at all? That's the question this piece is actually about.

✅ Key Takeaways

Agents don't need prettier UIs — they need structured, parseable data at every step: quotes, execution status, errors, and refund conditions.
A quote an agent can act on needs a stable identifier, an expiration, and machine-readable terms — not just a displayed number.
Execution status needs to be observable programmatically, not inferred from a wallet notification a human would read.
Omniston's SDK already exposes most of this surface — requestForQuote, buildTransfer, and swapTrack map almost directly onto what an agent loop needs.
The gap that remains isn't the API surface — it's standardized, cross-protocol schemas and scoped signing permissions that don't hand an agent your entire wallet.

🧩 Why "Just Use the Existing API" Isn't Quite Enough

A REST or WebSocket API that returns JSON already looks "machine-readable" on the surface. But an interface built for humans-via-frontend and one built for agents-via-API diverge in a few specific ways that matter a lot once nobody's eyes are actually on the screen:

Quotes need to be addressable, not just displayable. A human reads "≈ 4.82 USDT" and moves on. An agent needs a stable quoteId it can reference in a follow-up call, check for expiry, and use to build the exact transaction that quote described — not a re-derived approximation.
State needs to be pollable or streamable, not inferred. A human notices their wallet app changed. An agent needs to explicitly subscribe to or query execution status and get back a typed result: pending, settled, refundable, failed — not guess from a UI element that doesn't exist for it.
Errors need to be classifiable, not just readable. "Transaction failed" is fine for a person to read and shrug at. An agent needs to know why — insufficient gas, stale quote, slippage exceeded — so it can decide whether to retry, adjust parameters, or halt entirely.
Settlement guarantees need to be provable, not assumed. An agent moving funds autonomously needs the underlying execution model to guarantee — cryptographically, not just contractually — that a failed trade doesn't silently strand funds.

🔌 Omniston as a Working Example, Not a Hypothetical

This is where it stops being theoretical. Omniston's Node.js SDK is built around exactly this shape: request a quote, get a typed, addressable object back, build a transaction from it, and track settlement as an observable stream — all without a UI in the loop at any point.

Step 1 — Requesting a Quote

import { Omniston } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({
  apiUrl: "wss://omni-ws.ston.fi",
});

const quoteStream = omniston.requestForQuote({
  settlementParams: [{ /* which settlement methods to allow */ }],
  offerAsset: /* asset the agent is offering */,
  askAsset: /* asset the agent wants */,
  amount: /* offer amount */,
});

quoteStream.subscribe((quoteEvent) => {
  // quoteEvent carries a stable quoteId, expiry, and settlement terms —
  // an agent can log, validate, or discard this without ever rendering it
});

Notice what's already true here that a UI-first API wouldn't guarantee: the quote arrives as a typed event on a stream, not a string formatted for display. An agent can apply its own policy — "only accept quotes with price impact under X%" — entirely in code, before anything ever gets signed.

Step 2 — Building a Transaction From That Exact Quote

const tx = await omniston.buildTransfer({
  quote, // the exact quote object received above — not a re-derived price
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: agentWalletAddress,
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: agentWalletAddress,
  },
  gasExcessAddress: {
    blockchain: Blockchain.TON,
    address: agentWalletAddress,
  },
});

const messages = tx.ton?.messages ?? [];
// messages is ready to sign and send — no re-interpretation needed

This is the addressability property from earlier, made concrete: the transaction is built from the exact quote object, not a fresh price lookup that could have drifted. For a human, that drift shows up as slippage tolerance. For an agent, it needs to be closer to a contract: this quote, or nothing.

Step 3 — Tracking Settlement as a Stream, Not a Guess

const swapTrackStream = await omniston.swapTrack({
  quoteId: quote.quoteId,
  traderAddress,
  outgoingTxQuery, // tx hash, message hash, or outgoing message body
});

swapTrackStream.subscribe({
  next(event) {
    switch (event?.$case) {
      case "pending":
        // agent can log and wait
        break;
      case "settled":
        // agent can safely mark the position as complete
        break;
      case "refunded":
        // agent knows funds returned — no manual investigation needed
        break;
    }
  },
});

This is arguably the most important piece for agent-native design: settlement status is a subscribable stream with typed cases, not a wallet push notification meant for a person to read. An agent loop can await a terminal state and branch its own logic on exactly what happened — no screen-scraping, no polling a UI, no assuming success because nothing obviously broke.

🧠 Mapping This Back to the Four Requirements

Requirement	What a human-first API gives you	What Omniston's SDK actually gives an agent
Addressable quotes	A displayed rate	A `quoteId`-bound, typed quote object
Observable state	A UI notification	A subscribable `swapTrack` stream with typed cases
Classifiable errors	A toast message	Typed event cases an agent can branch logic on
Provable settlement	"Trust the app"	HTLC-based atomic settlement — refund or settle, never stranded

The last row matters more for agents than for humans, arguably. A person who gets a confusing error can pause, screenshot it, ask someone. An agent executing autonomously needs the underlying settlement model itself to guarantee it can't end up in a state with no defined outcome — which is exactly what atomic, HTLC-based settlement is built to provide regardless of who or what initiated the trade.

🚧 What's Still Genuinely Missing

None of this means the problem is solved. A few gaps are real, and worth naming honestly rather than glossing over:

No standardized cross-protocol quote schema yet. Omniston's typed quote object works beautifully within Omniston. An agent comparing quotes across multiple unrelated DeFi protocols still has to normalize different shapes by hand — there's no shared "agent quote format" the way there's an emerging shared format for, say, tool-calling schemas in LLM APIs.
Signing permissions are still mostly all-or-nothing. Handing an agent a wallet today generally means handing it broad signing capability, not a scoped permission like "up to $200, only this pair, only this week." Session-scoped, policy-bound signing is the piece that would let people actually trust autonomous agents with real capital, and it's not solved at the wallet layer yet.
Resolver selection isn't yet exposed as agent-tunable criteria. An agent might reasonably want to weight resolver reputation or historical fill reliability into its own decision-making, not just accept whichever quote wins on price. That's a reasonable next layer on top of what already exists.

🛠 A Minimal Sketch of an Agent-Friendly Wrapper

Putting the pieces above together, here's a conceptual sketch — illustrative pseudocode, not a drop-in production snippet — of what an agent's decision loop could look like sitting on top of the primitives above:

async function agentSwapDecision(policy: AgentPolicy) {
  const quote = await getBestQuote(policy.offerAsset, policy.askAsset, policy.amount);

  if (quote.priceImpact > policy.maxPriceImpact) {
    return { action: "reject", reason: "price_impact_exceeded" };
  }

  if (quote.expiresInMs < policy.minQuoteLifetimeMs) {
    return { action: "reject", reason: "quote_too_stale" };
  }

  const tx = await buildTransferFromQuote(quote);
  const settlement = await executeAndTrack(tx, quote.quoteId);

  return settlement.$case === "settled"
    ? { action: "complete", quoteId: quote.quoteId }
    : { action: "escalate", state: settlement.$case };
}

The point of this sketch isn't the code itself — it's that every branch is a policy decision made before signing, on typed data, with a defined fallback. That's the actual shape of "a DeFi API built for agents": not a smarter chatbot bolted onto a swap button, but a protocol where every step an agent needs to reason about is already a typed, addressable, observable object instead of something meant to be read off a screen.

🧭 Conclusion

The honest answer to "what would a DeFi API for AI agents need to look like" turns out to be less exotic than the framing suggests. It needs addressable quotes, observable execution, classifiable errors, and settlement guarantees that don't depend on anyone reading anything. Omniston's SDK already builds most of that surface for a reason that has nothing to do with AI hype — it was designed to be integration-first, so any program, human-facing or not, could reason about a swap the same way. The open work left isn't reinventing that foundation; it's standardizing it across protocols and giving agents narrower, safer permissions than "hold the whole wallet."

❓ Frequently Asked Questions

Can an AI agent already use Omniston to execute swaps autonomously today?
Technically, yes — the SDK exposes quote requests, transaction building, and settlement tracking as programmatic, typed calls that don't require a UI. Whether it's advisable depends entirely on the wallet permissions and safeguards wrapped around the agent, which is a separate, still-unsolved layer.

Does using a typed API like Omniston's remove the need for slippage protection?
No. Price impact and slippage are still real; a typed API just lets an agent check those values programmatically and reject a quote automatically instead of a human eyeballing a percentage before confirming.

What's the single biggest missing piece for safe agent-driven DeFi?
Scoped, policy-bound signing permissions. Most wallet integrations today still hand an agent broad signing capability rather than a narrow, revocable permission — that gap matters more than any missing API feature.

Why does atomic, HTLC-based settlement matter specifically for agents rather than humans?
Because an agent can't "notice something looks off" and pause the way a person might. The settlement model itself needs to guarantee a defined outcome — settled or refunded, never stranded — so an autonomous process never ends up in an undefined state it has to resolve manually.

📚 Sources and Further Reading

Omniston SDK — Node.js — Full flow for quote requests, transaction building, and settlement tracking: https://docs.ston.fi/developer-section/omniston/omniston-nodejs
Omniston Protocol Overview — Architecture and settlement modes, including cross-chain HTLC flows: https://docs.ston.fi/developer-section/omniston
Omniston SDK Reference — Package overview and installation for TypeScript/JavaScript integration: https://docs.ston.fi/developer-section/omniston/sdk
STON.fi Developer Introduction — Full index of SDKs, REST API, and integration guides: https://docs.ston.fi/

Indexing Blockchain Data: Why DeFi Apps Need More Than RPC Calls

Web3KD — Sun, 23 Aug 2026 13:14:38 +0000

Indexing Blockchain Data: Why DeFi Apps Need More Than RPC Calls

Ask a new blockchain developer how their app will "read the chain," and the answer is almost always the same: call the RPC. It's the obvious starting point, and for a narrow class of questions — what's this wallet's current balance, has this specific transaction confirmed — it's genuinely sufficient. The moment a DeFi app needs to answer a slightly more interesting question — every trade this pool has ever seen, every wallet that's ever farmed this token, how liquidity depth has shifted over the past month — RPC calls alone stop being a viable architecture, and most teams discover this the expensive way, in production, under load.

This isn't a niche concern reserved for large-scale analytics dashboards. Even a modest DeFi frontend showing a pool's recent trade history, a user's farming rewards over time, or a simple "top pools by volume" leaderboard is already asking the kind of question raw RPC access wasn't designed to answer efficiently. The gap between "my app connects to the blockchain" and "my app can actually show users the data they expect" is almost entirely made of this distinction, and it's worth understanding precisely rather than discovering by accident when an endpoint starts timing out under real traffic.

🗨️ "RPCs provide connectivity, indexers make data usable, oracles connect applications to the real world and other chains, Layer-2s make execution affordable, and storage keeps assets and history available." — Web3 Infrastructure Stack overview, 2026

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🗄️ What an RPC Node Is Actually Built to Answer

An RPC endpoint is a gateway to a single node's current or near-current state — it excels at point-in-time, single-entity questions:

What's this address's balance right now
Has this transaction confirmed
What does calling this contract method return, given current state

What it's structurally weak at is aggregation across time or across many entities at once — "every swap in this pool over the last 30 days" isn't a single state read, it's a query across a history the node wasn't built to summarize on demand. Asking an RPC node to answer that means either replaying enormous ranges of blocks per request, or accepting that the app simply can't answer that question efficiently at all.

This limitation isn't a bug in any particular provider's implementation — it's a direct consequence of what a node is actually built to do. A node maintains current state and validates new blocks; it was never meant to be a general-purpose historical database, and asking it to behave like one means fighting the grain of its own design. Industry infrastructure guides increasingly frame this plainly: request volume that would be trivial for a purpose-built index can be enough to "overwhelm shared-tier endpoints" when routed through raw RPC methods instead, and even dedicated, paid RPC tiers hit real limits once a query pattern crosses from "look up one thing" into "reconstruct history across many things."

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

Where This Breaks in Practice: TON's Own Architecture as the Clearest Example

TON is a genuinely useful case study here, because its own design makes the RPC-only limitation unusually visible rather than a subtle inefficiency.

🗨️ "The TON DeFi ecosystem — including DEXes like STON.fi, lending protocols, and Jetton issuance — requires both real-time method access (v2) for transaction submission and indexer access (v3) for token balance lookups, liquidity pool reads, and historical trade data. A provider that only surfaces v2 forces teams to run their own indexer or accept incomplete data coverage." — Chainstack, TON RPC Provider Guide, 2026

This is a direct, named acknowledgment that a DEX like STON.fi cannot function on RPC access alone. TON's asynchronous, sharded architecture — messages between contracts don't resolve in the same block the way a single-chain synchronous call does — makes naive "just poll the RPC repeatedly" patterns even less viable than on more traditional chains. Heavy read patterns specific to this ecosystem — enumerating jetton masters, tracing transactions by message, reconstructing a pool's trade history — are explicitly called out as workloads that "overwhelm shared-tier endpoints quickly." This isn't a hypothetical scaling concern; it's a documented, current-year operational reality for exactly the kind of app STON.fi is.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🔍 What an Indexer Actually Does Differently

An indexer isn't a faster RPC node — it's a fundamentally different data shape sitting behind the chain.

It watches the chain continuously and writes relevant events into a queryable database as they happen, rather than waiting to be asked
It pre-aggregates the kind of historical, cross-entity questions an RPC node can't answer efficiently — total volume by pool, every position a wallet has ever held, time-series depth over a date range
It exposes that data through a query interface — commonly GraphQL or SQL — built for exactly the aggregation patterns a raw JSON-RPC method was never designed to serve

The distinction matters architecturally: an RPC node answers "what is true right now, about this one thing." An indexer answers "what has been true, across everything, over time" — and a DeFi frontend genuinely needs both, for different parts of the same interface.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

⚡ Where STON.fi's Own Architecture Already Reflects This Split

This isn't just an abstract infrastructure argument — it shows up directly in how STON.fi structures its own developer-facing API. STON.fi's REST API exposes pool data, jetton information, protocol statistics, and fee data specifically so integrating developers never have to run their own indexing pipeline just to answer "what does this pool's history look like" — the aggregation work has already been done, once, centrally, rather than pushed onto every team building on top of the protocol.

// Without an indexing layer, "get this pool's 30-day volume" means:
// manually paginating through raw transaction history yourself
async function getVolumeTheHardWay(poolAddress: string) {
  let allTxs = [];
  let cursor = null;
  do {
    const batch = await rpcClient.getTransactions(poolAddress, { cursor, limit: 100 });
    allTxs = allTxs.concat(batch.transactions);
    cursor = batch.nextCursor;
  } while (cursor && allTxs.length < ENOUGH_TO_COVER_30_DAYS);
  return aggregateVolumeFromRawTxs(allTxs); // now do this correctly, yourself
}

// With STON.fi's own indexed API, the same question is one call
async function getVolumeTheRealWay(poolAddress: string) {
  const stats = await stonfiApi.getPoolStats(poolAddress, { period: '30d' });
  return stats.volume; // already aggregated server-side
}

The second function isn't just shorter code — it's the entire architectural point of this article expressed as two functions doing the same job at radically different costs, in both engineering time and runtime load on shared infrastructure.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

🛰️ The Broader Infrastructure Landscape Solving This Same Problem

STON.fi's own API is one answer to this problem, specific to its own protocol data. The wider ecosystem has converged on a few recognizable patterns for the general case:

Subgraph-style indexing. A widely adopted pattern across DeFi and NFT protocols generally: define what on-chain events matter, and a hosted indexing layer continuously ingests and exposes them through a standard query interface — the developer writes what to track, not how to scan the chain for it.

Streaming pipelines into owned infrastructure. Rather than querying a third party's hosted index at request time, some platforms stream relevant on-chain events directly into a team's own database in near real time — trading some setup complexity for full ownership of the resulting data.

High-throughput retrieval layers purpose-built for historical backfills. Distinct from live indexing, this category focuses specifically on event-heavy, high-volume historical queries — the kind of workload that would otherwise mean manually replaying enormous block ranges through standard RPC calls, compressed instead into a retrieval layer built for exactly that access pattern.

Each of these exists because the same underlying gap keeps appearing across every chain and every serious DeFi application: raw node access answers current-state questions well and historical, aggregate questions poorly, and that gap doesn't close by adding more RPC capacity — it closes by adding a genuinely different kind of infrastructure layer. Teams that try to close it by simply paying for a bigger or faster RPC plan tend to discover that the ceiling moves, but doesn't disappear — the query pattern was always the mismatch, not the provider's raw throughput.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

⚖️ Comparing on the Dimensions That Actually Matter

💧 Point-in-time reads vs. historical aggregation. An RPC call answers "what is the state right now." An index answers "what has the state been, summarized, over a range" — and a real DeFi frontend needs both simultaneously, often on the same screen.

🧭 Single-entity queries vs. cross-entity queries. Checking one wallet's balance is RPC-shaped. Ranking every liquidity provider in a pool by size is index-shaped. Trying to force the second pattern through the first tool is where naive architectures fail under real load.

⏱️ Request-time computation vs. pre-aggregated results. Computing 30-day volume by replaying transactions on every page load is request-time work that scales badly with traffic. An indexed API returning a pre-computed figure scales with how often the underlying data actually changes, not with how many users ask about it.

⚔️ Running your own indexing stack vs. relying on a protocol's own indexed API. Self-hosting an indexing pipeline offers full control but comes with real, ongoing operational cost. Using a protocol's own indexed endpoints — where they exist, as with STON.fi's own REST API — removes that operational burden entirely for exactly the queries that protocol already needed to answer for its own frontend.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

✅ What Genuinely Justifies Adding an Indexing Layer

Any question that spans time or many entities at once. Historical volume, wallet-level position history, and pool-ranking queries are the clearest signal that plain RPC access has been outgrown.
Request patterns that would otherwise mean repeated, expensive chain scans. If serving a single page requires replaying a meaningful range of transaction history on every load, that computation belongs in a pre-aggregated index, not in the request path.
Read patterns explicitly documented as overwhelming shared infrastructure. When a chain's own tooling ecosystem calls out specific query patterns as needing dedicated indexer access rather than standard RPC methods, that's a direct, reliable signal for architecture decisions, not a guess.

⚠️ What's Worth Understanding Correctly

An indexer is not a faster RPC node. It's a structurally different data layer, built for aggregation and history rather than point-in-time state.
Using a protocol's own indexed API isn't a shortcut — it's often the correct architecture. When STON.fi already exposes pool and fee data through its own API, rebuilding that aggregation independently duplicates work the protocol has already done well.
TON's async, sharded design makes this distinction more visible than on some other chains, not less relevant. The v2/v3 RPC split documented by TON infrastructure providers exists specifically because this chain's architecture makes naive polling patterns fail faster and more visibly than on a simpler synchronous chain.

🏁 Bottom Line

RPC calls answer the question DeFi apps ask least interestingly — "what's true right now, about this one thing" — and answer it well. The moment an app needs to answer anything that spans history or many entities at once, which is most of what a real trading interface actually shows a user, RPC access alone stops scaling, and the documented reality on TON specifically — where DEXes like STON.fi are explicitly named as needing indexer-grade access alongside standard RPC methods — makes that gap unusually concrete rather than theoretical. Building on top of a protocol's own indexed API where one exists, rather than reimplementing that aggregation independently, is usually the correct answer, not a compromise.

🔗 Sources & Further Reading

Chainstack — "Top 6 TON RPC Providers for Mini Apps and Production in 2026" (STON.fi-specific v2/v3 requirements) — https://chainstack.com/top-6-ton-rpc-providers-for-telegram-mini-apps-and-production-workloads-in-2026/
Blockchain Council — "Web3 Infrastructure Stack 2026: What You Need" — https://www.blockchain-council.org/web-3/web3-infrastructure-stack-2026-rpcs-indexers-oracles-layer-2s-storage/
Ormi Labs — "What Is Blockchain Indexing? Types, Limitations and Tools" — https://blog.ormilabs.com/what-is-blockchain-indexing-part1/
OnFinality — "The 2026 Guide to Blockchain Infrastructure Providers" — https://blog.onfinality.io/2026-guide-to-blockchain-infrastructure/
STON.fi — Developer Documentation Introduction — https://docs.ston.fi/

This article reflects independent research based on publicly available infrastructure documentation and STON.fi's public developer documentation as of mid-2026. Provider pricing, API coverage, and TON's own RPC architecture evolve over time — always verify current details directly on the relevant provider's documentation before making infrastructure decisions.