DEV Community: Web3KD

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.

Transaction Lifecycle: What Actually Happens After You Click Swap

Web3KD — Sun, 23 Aug 2026 12:26:15 +0000

Transaction Lifecycle: What Actually Happens After You Click Swap

A swap transaction isn't one event — it's a state machine, moving through distinct, named phases between the moment a user taps "confirm" and the moment funds actually settle. This piece traces that lifecycle stage by stage on STON.fi, with the actual code shape at each transition, because this is genuinely an engineering topic underneath the trading language, and it deserves to be read as one.

🗨️ "Simulate the swap to obtain routing metadata (expected amounts, vault info, and the full router object). Feed simulationResult.router directly into dexFactory() to build contracts dynamically." — STON.fi, SDK v2 Swap Documentation

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

🎞️ The Six States a Transaction Actually Passes Through

Before the code, the shape of the lifecycle itself:

→ Simulated — a live calculation against current reserves, no commitment yet
→ Parameterized — the simulation's output converted into concrete transaction fields
→ Handed off — passed to the wallet layer for review
→ Signed — the trader's actual commitment point
→ Broadcast — submitted to the network with a built-in expiration
→ Settled — atomically completed, or reverted, with no state in between

Every one of these is a distinct, inspectable moment. Treating "confirm swap" as one atomic user action hides that six separate things have to happen correctly, in order, for that action to actually succeed.

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

State One: Simulated

Nothing here is final, and that's the entire point of this stage existing separately from what follows.

const simulationResult = await api.simulateSwap({
  offerAddress: offerJetton,
  askAddress: askJetton,
  offerUnits: amount,
  slippageTolerance: '0.01',
});

// simulationResult now carries: expected output, fee breakdown, and
// simulationResult.router — the current router object, not a saved address

This step can run any number of times, freely, with zero cost — which is precisely why it's a poor idea to cache and reuse an old simulation result rather than re-running it right before the next stage.

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

⚙️ State Two: Parameterized

The simulation's output gets converted into the actual fields a transaction needs — this is where "approximately what you'll get" becomes "exactly what will be enforced on-chain."

const router = dexFactory(simulationResult.router); // never hardcoded

const txParams = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: userAddress,
  offerJettonAddress: offerJetton,
  askJettonAddress: askJetton,
  offerAmount: amount,
  minAskAmount: calculateMinAskAmount(simulationResult.askUnits, slippageBps),
  queryId: generateQueryId(),
});

The minAskAmount field is the crux of this state: it's the moment a slippage percentage typed into a UI becomes a specific integer that a smart contract will actually check against.

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

🖊️ State Three: Handed Off, Then Signed

These are technically two states, but they happen across a single user-facing moment — the wallet prompt — so it's worth treating them together.

const result = await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  messages: [
    {
      address: txParams.to.toString(),
      amount: txParams.value.toString(),
      payload: txParams.body.toBoc().toString('base64'),
    },
  ],
});

Everything before this call was recalculable and free. sendTransaction is where that stops being true — the user's wallet signature is the actual, irreversible commitment point in the entire lifecycle. Before it, the transaction is a proposal. After it, it's a request the network will actually act on.

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

📤 State Four: Broadcast

Once signed, the payload — a base64-encoded BOC, TON's native cell serialization format — actually leaves the client and enters the network. The validUntil field set in the previous state now becomes active protection:

// If the network hasn't processed this by validUntil, it's discarded —
// never executed against reserves that may no longer reflect this quote

This is also the point where, for a same-chain swap, TON's transaction model takes over: the transaction will either execute completely or fail completely. There's no documented partial-execution state at this layer — a multi-chunk route either lands as calculated, chunk by chunk, or the whole thing reverts.

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

🔁 State Five: Settlement — and Where Cross-Chain Genuinely Diverges

For a same-chain trade, settlement is close to instantaneous once the transaction is included in a block. For a cross-chain trade, this state gets meaningfully more complex, because TON's own atomicity guarantee doesn't extend to a second, separate blockchain automatically.

// Cross-chain settlement adds an HTLC layer on top of the same lifecycle:
// - funds lock behind a shared hash + time condition on both chains
// - completion reveals the secret and releases both sides
// - if either side fails to complete in time, the time lock
//   auto-refunds the locked side rather than leaving it stuck

This is why a cross-chain swap through STON.fi's Omniston takes measurably longer than a same-chain one — it's not inefficiency, it's a deliberate trade of speed for a correctness guarantee that two independent blockchains don't provide each other on their own.

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

🎞️ Watching the State Machine From the Outside

A well-built integration doesn't just fire a transaction and hope — it subscribes to the lifecycle's own status stream rather than polling a balance and guessing.

omniston.trackTrade({ rfqId }).subscribe((event) => {
  switch (event.state) {
    case 'filled':
      confirmSuccess(event);
      break;
    case 'partiallyFilled':
      // Reflects the quote-matching stage, not a broken on-chain transaction —
      // some connected liquidity didn't fully match before execution
      handlePartialFill(event);
      break;
    case 'aborted':
      showRetryOption(event);
      break;
  }
});

Treating partiallyFilled as equivalent to a crashed transaction is a common misread — it describes what happened during quote-matching among resolvers and pools, before final on-chain execution, not a submitted transaction that stopped halfway.

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

⚖️ Comparing on the Dimensions That Actually Matter

💧 Free states vs. committed states. Everything through "parameterized" costs nothing and binds nobody. Everything from "signed" onward is real. Conflating these two categories is the most common source of confusion about what a "failed" swap actually means at each point.

🧭 Same-chain settlement vs. cross-chain settlement. One relies on native blockchain atomicity and settles quickly. The other layers HTLC-based correctness on top, deliberately trading speed for a guarantee TON alone can't provide across a chain boundary.

⏱️ Polling vs. subscribing. Manually checking a wallet balance after broadcasting is a weak signal — the trade could be pending, reverted, or still routing. Subscribing to trackTrade gets an explicit state instead of an inference.

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

✅ What Genuinely Makes This Lifecycle Safe to Build On

Every state before signature is inspectable and repeatable. A developer — or a curious user — can trigger and re-trigger simulation and parameter-building without any real-world consequence.
The transaction's own fields, not external assumptions, enforce the guarantees. minAskAmount and validUntil are baked into the payload itself, not just displayed in a UI.
Status is streamed, not inferred. trackTrade reports real states instead of forcing an integration to guess from a balance check.

⚠️ What's Worth Understanding Correctly

"Broadcast" and "settled" are not the same state. A transaction can be genuinely on the network and still fail atomically at settlement if conditions shifted enough.
partiallyFilled belongs to quote-matching, not execution. Once a transaction actually broadcasts on TON, it's binary — complete or reverted — with this status reflecting an earlier stage.
Cross-chain lifecycle length is a designed tradeoff. The extra time isn't latency to optimize away; it's the HTLC window that prevents funds from ever being stuck between two chains.

🏁 Bottom Line

"What happens after you click swap" is really six distinct, inspectable states — simulated, parameterized, handed off, signed, broadcast, and settled — each with its own guarantees and its own failure mode. Building against this lifecycle explicitly, rather than treating a swap as one opaque action, is what separates an integration that degrades gracefully under real-world conditions from one that just breaks silently the first time a pool's reserves shift at the wrong moment.

🔗 Sources & Further Reading

STON.fi — SDK v2 Swap Documentation — https://docs.ston.fi/developer-section/dex/sdk/v2/swap
STON.fi — Transaction Sending via TON Connect — https://docs.ston.fi/developer-section/common/transaction-sending/tonconnect
STON.fi — Omniston gRPC Integration Guide (trackTrade, fill states) — https://docs.ston.fi/developer-section/omniston/swap/grpc
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/
STON.fi — Omniston Protocol Overview (HTLC cross-chain settlement) — https://docs.ston.fi/developer-section/omniston

This article reflects independent research based on STON.fi's public developer documentation as of mid-2026. Code examples are simplified for clarity and are not a verbatim copy of the official SDK. Transaction flow and protocol mechanics evolve as the system ships updates — always verify current functionality directly on docs.ston.fi before shipping a production integration.

The Last Mile: Taking a STON.fi Integration From Test Network to Real Users

Web3KD — Sat, 22 Aug 2026 11:31:54 +0000

The Last Mile: Taking a STON.fi Integration From Test Network to Real Users

Getting a swap working in a test environment is the easy 80% of shipping a STON.fi integration. The remaining 20% — the part that actually determines whether real users lose money to a preventable bug — is almost entirely about the gap between "works in sandbox" and "safe on mainnet." This piece walks through that gap concretely, with the specific patterns STON.fi's own documentation flags as production-critical.

🗨️ "The production-ready pattern is API-driven. Always let the STON.fi API dictate which router to use, and work against the mainnet endpoint. This keeps your integration compatible with future router upgrades and avoids hardcoding contract addresses." — STON.fi, SDK v2 Swap Documentation

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

🧳 Why "It Worked in Testing" Isn't the Bar

Test environments are deliberately forgiving in ways production isn't. Three gaps close the distance between the two:

🔲 Endpoints are genuinely separate, not a toggle. wss://omni-ws-sandbox.ston.fi and wss://omni-ws.ston.fi are different environments entirely — a misconfigured environment variable is the single most avoidable production incident.
🔳 Contract addresses differ, and mixing them is dangerous, not just broken. STON.fi's own DEX core repository lists distinct mainnet (EQB3ncy...) and testnet (EQBsGx9...) router addresses, and third-party integration docs explicitly warn against sending funds across that boundary in either direction.
▶️ Hardcoded values that "worked" in testing quietly rot in production. A fee constant or router address that was correct on day one silently becomes wrong the moment STON.fi ships a router upgrade — which is precisely the failure mode the API-driven pattern exists to prevent.

None of these are exotic mistakes. They're the ordinary, boring gaps that separate a demo from a system real money moves through.

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

The Single Highest-Leverage Rule: Let the API Decide, Don't Decide for It

If this article had to compress into one sentence, it would be this one, because STON.fi's own documentation states it as explicitly as production advice ever gets stated.

🗨️ "STON.fi's REST API (api.ston.fi) only serves mainnet data, so every production swap should follow this flow: simulate the swap to obtain routing metadata, feed simulationResult.router directly into dexFactory() to build contracts dynamically." — STON.fi, SDK v2 Swap Documentation

The instinct after testing successfully is to lock in what worked — save the router address you tested against, hardcode it, ship it. That instinct is exactly backwards for this ecosystem. STON.fi's router can be upgraded, and an integration that hardcodes a specific router address instead of asking the API which one to use will break silently the next time that happens — not with an error message, but with a transaction that's quietly built against a router that's no longer the current one.

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

🚧 The Shipping Checklist, One Gap at a Time

🔲 Confirm every environment variable before the first sandbox test, not the last. Both the WebSocket endpoint and the REST API base URL need to point at sandbox during testing and mainnet in production — a single missed variable in a deploy config is enough to send test transactions against real liquidity, or worse, production transactions against a test router.

🔳 Never hardcode a router or contract address, even one that's "definitely stable." Follow the documented pattern exactly: simulate first, then feed the simulation's own router object into dexFactory() to build contracts dynamically. This single pattern absorbs future router upgrades automatically, without a code change on your side.

// ❌ Hardcoded — breaks silently on the next router upgrade
const router = dexFactory('EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt');

// ✅ API-driven — always current, per STON.fi's own recommended pattern
const simulationResult = await api.simulateSwap(swapParams);
const router = dexFactory(simulationResult.router);

▶️ Calculate fees dynamically, never as a hardcoded constant. STON.fi's own SDK constants for fees exist mainly as fallbacks — the documented best practice is calculating fees from current config parameters rather than relying on values that were correct when the code was written but aren't guaranteed to stay that way.

◀️ Prefer the SDK and TonConnect over manual BOC compilation, unless you have a genuinely specialized need. STON.fi's own API reference is explicit that custom BOC compilation should be reserved for advanced use cases — the SDK handles edge cases and receives official support that a hand-rolled transaction builder won't.

🔲 Test both refund paths and the documented exit codes before launch, not after a user reports a problem. This means deliberately exercising the failure modes covered in STON.fi's own error handling — a zero minAskAmount, insufficient gas producing exit code 37, and both the default and explicitly-set refundAddress behaviors — as part of the pre-launch test suite, not as reactive debugging once something has already gone wrong for a real user.

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

🗝️ What Changes Once Real Referral Fees and Real Vaults Are Involved

If an integration routes through a referral program, there's a specific mechanic worth understanding before launch rather than after the first payout question comes in.

🗨️ "DEX v2 accumulates each swap's referral portion in a dedicated Vault contract (one per referrer × token pair). Fees can be configured in the 0.01%–1% range and must later be withdrawn by the referrer." — STON.fi, v2 Smart Contract Documentation

This means referral revenue doesn't arrive automatically in a wallet — it accrues in a per-referrer, per-pair Vault contract that requires an explicit withdrawal step. An integration's launch checklist should include verifying that this withdrawal flow actually works end to end in sandbox, not just that the referral fee is correctly attached to outgoing swap transactions. A referral fee that accrues correctly but can never actually be withdrawn is a production bug that looks like a success in every log line up until someone tries to claim it.

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

📶 Comparing on the Dimensions That Actually Matter

💧 Hardcoded stability vs. adaptive stability. A hardcoded router address feels more stable during development because it never changes on you unexpectedly. In production, that's exactly backwards — the API-driven pattern is the version that actually stays stable as STON.fi's own infrastructure evolves underneath it.

🧭 Sandbox correctness vs. production correctness. Sandbox testing proves your logic is right for the inputs you thought to test. Production correctness additionally requires that your environment configuration, fee calculation, and referral withdrawal flow are all verified against real, current mainnet state — a genuinely broader bar.

⏱️ Reactive debugging vs. pre-launch failure testing. Discovering an exit-code handling gap from a confused user's support ticket costs far more — in trust and in engineering time — than deliberately triggering that same exit code in a sandbox test the week before launch.

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

✅ What a Genuinely Production-Ready Integration Gets Right

Every router and contract address comes from a live simulation, never a saved constant. This single pattern absorbs STON.fi's own infrastructure changes automatically.
Environment separation is verified in CI, not assumed from a config file. Sandbox and mainnet endpoints get explicitly checked before any test suite runs, closing off the most common and most avoidable production incident.
Referral and fee mechanics are tested end to end, including withdrawal. Fees accruing correctly is only half the mechanism — confirming they can actually be claimed is the other half most teams skip.

⚠️ What's Worth Understanding Correctly

Sandbox and mainnet contract addresses are not interchangeable, and mixing them is an active risk, not just an error. Third-party integration guides explicitly warn against sending funds across that boundary in either direction.
A router upgrade on STON.fi's side is not your integration's emergency if you followed the API-driven pattern. It only becomes one if a router address was hardcoded somewhere it shouldn't have been.
Manual BOC compilation is a deliberate, advanced choice, not a shortcut. STON.fi's own documentation reserves it for specialized cases precisely because the SDK already handles the edge cases a hand-rolled path would need to reimplement.

🏁 Bottom Line

Shipping a STON.fi integration from sandbox to mainnet isn't about writing more code — it's about removing the specific hardcoded assumptions that work fine in a test environment and quietly fail in a production one: fixed router addresses instead of live simulation results, static fee constants instead of dynamic config reads, and untested refund or withdrawal paths that only get discovered once a real user is waiting on them. The gap between a working demo and a production-ready integration is almost entirely made of these small, documented, entirely avoidable decisions.

🔗 Sources & Further Reading

STON.fi — SDK v2 Swap Documentation (API-driven pattern, dexFactory) — https://docs.ston.fi/developer-section/dex/sdk/v2/swap
STON.fi — v2 Smart Contract Documentation (referral Vaults, fee configuration) — https://docs.ston.fi/developer-section/dex/smart-contracts/v2
STON.fi — Developer Documentation Introduction — https://docs.ston.fi/
GitHub — ston-fi/dex-core (mainnet/testnet addresses, bug bounty contact) — https://github.com/ston-fi/dex-core
Tact Documentation — STON.fi Integration Cookbook (testnet/mainnet fund-mixing warning) — https://docs.tact-lang.org/cookbook/dexes/stonfi/

This article reflects independent research based on STON.fi's public developer documentation and open-source repositories as of mid-2026. Contract addresses, fee ranges, and recommended patterns evolve as the protocol ships updates — always verify current details directly on docs.ston.fi before shipping a production integration.