DEV Community: Web3KD

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.

Liquidity Fragmentation Across Chains: A Technical Breakdown of How STON.fi Actually Routes Around It

Web3KD — Sat, 22 Aug 2026 11:16:28 +0000

Liquidity Fragmentation Across Chains: A Technical Breakdown of How STON.fi Actually Routes Around It

DeFi's total value locked tells a story of scale. It doesn't tell you where that value actually sits, how deep any single pool is, or what happens when a real-sized trade tries to move through it. In 2026, those two stories have diverged sharply — and TON, still a comparatively young liquidity environment, feels this gap more acutely than a chain with decades of accumulated depth. This piece breaks down the mechanics of fragmentation generally, and then looks specifically at how STON.fi's Omniston layer is architected to route around exactly this problem rather than pretend it doesn't exist.

🗨️ "A swap that would have minimal price impact in a single deep pool instead moves the market more when split across thin pools. As of 2026, aggregate slippage costs in DeFi exceed $2.7 billion annually." — Spark, DeFi glossary

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

🧊 Fragmentation Happens at Two Levels, and They Compound Each Other

The instinct is to think of fragmentation as a single problem — "liquidity is spread across chains." In practice it's two separate, stacking problems:

🔷 Within-chain fragmentation. Even on one blockchain, liquidity splits across competing protocols and pool configurations. Uniswap v3 alone introduced four fee tiers per pair; combined with v4's hook-enabled pools, SushiSwap, Curve, and Balancer, a single token pair can have 10 to 20 active pools on Ethereum mainnet alone, each operating independently with its own depth.
🔶 Cross-chain fragmentation. The more severe layer. DeFiLlama tracks nearly 400 blockchains, and L2Beat records over 70 active Ethereum rollups alone, holding more than $48 billion in combined TVL. A stablecoin like USDC is natively deployed on over 30 blockchains — the same dollar-denominated liquidity scattered across all of them, unable to net against itself.

These two levels stack multiplicatively, not additively. A token doesn't just get diluted once, across chains — it gets diluted again, within each chain, across every pool and fee tier competing for the same pair.

TON illustrates both levels clearly. Within TON alone, a given pair can have liquidity split across STON.fi's own v1 and v2 pools, plus entirely separate pools on DeDust and TonCo — the within-chain fragmentation problem, just at a smaller scale than Ethereum's twenty-pool extremes. Cross-chain, TON's DeFi liquidity is a fraction of Ethereum's, meaning any given asset bridged onto TON typically has meaningfully less depth locally than its home chain, even before accounting for how that TON-side liquidity is itself further split across STON.fi, DeDust, and TonCo.

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

The Metric That Actually Matters, and Why TVL Hides the Problem

This is the technical crux of the entire fragmentation conversation, and it's the point most surface-level coverage misses entirely.

🗨️ "When measuring effective depth at 1–2% slippage on each chain, execution quality deteriorated outside the primary venue. Capital had expanded in nominal terms, but usable liquidity had fragmented." — independent multi-chain liquidity analysis, Medium, 2026

Aggregate TVL is additive by construction — deploy the same protocol on twenty chains, and the headline number goes up regardless of whether any single chain's pool can actually absorb a meaningful trade. The metric that actually reflects tradeable liquidity is effective depth at a fixed slippage threshold — how much size can execute at, say, 1-2% price impact — and that number does not scale the way TVL does. A protocol can show $2 billion in aggregate pool capital and still lose on realized price to a source holding zero standing inventory at all, simply because that $2 billion was never concentrated enough anywhere to matter for the specific trade being priced.

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

🧮 Making "TVL Isn't Depth" Concrete: The Actual Math

The claim above is easy to state and easy to under-appreciate without seeing the arithmetic. On a constant-product pool (x * y = k), the effective depth at a given slippage tolerance is a direct function of reserves, not a fixed fraction of TVL:

def effective_depth_at_slippage(reserve_in: float, reserve_out: float, max_slippage: float) -> float:
    """
    Returns the max input size that keeps price impact under max_slippage
    on a constant-product pool. This is what 'depth' actually means —
    not the pool's total dollar value.
    """
    k = reserve_in * reserve_out
    target_price_ratio = 1 - max_slippage
    # Solve for new reserve_in such that new marginal price = target_price_ratio * spot price
    new_reserve_in = reserve_in / (target_price_ratio ** 0.5)
    return new_reserve_in - reserve_in

# Two pools, identical $1M TVL, wildly different tradeable depth
pool_a = effective_depth_at_slippage(reserve_in=500_000, reserve_out=500_000, max_slippage=0.01)
pool_b = effective_depth_at_slippage(reserve_in=50_000, reserve_out=950_000, max_slippage=0.01)

print(f"Pool A (balanced): ${pool_a:,.0f} tradeable at 1% slippage")
print(f"Pool B (imbalanced): ${pool_b:,.0f} tradeable at 1% slippage")
# Same $1M TVL headline. Meaningfully different real depth.

This is also exactly why splitting a large order across ten $1M pools performs worse than routing it through one $10M pool — each independent effective_depth_at_slippage call hits its own limit far sooner than a single, larger reserve pair would.

A solver-style router, by contrast, treats fragmentation as a given and queries every available source before committing to a route. This is, functionally, what Omniston does on every STON.fi swap:

async function findBestExecution(pair: TokenPair, amount: bigint) {
  // Omniston's actual pattern: query every connected paradigm at once
  const [stonfiPools, otherAmmPools, resolverQuotes] = await Promise.all([
    queryStonfiPools(pair, amount),      // STON.fi v1/v2 — deterministic, reserve-based
    queryOtherAmms(pair, amount),        // DeDust, TonCo — same TON liquidity graph
    queryResolverNetwork(pair, amount),  // escrow swaps — no standing inventory, live quotes
  ]);

  const allQuotes = [...stonfiPools, ...otherAmmPools, ...resolverQuotes];
  // Depth-weighted selection or a split route — never a forced single source
  return selectOptimalRoute(allQuotes, { amount, maxSlippage: 0.01 });
}

The structural point is the same one made above, just made executable: fragmentation isn't something either snippet "fixes." The first one measures it honestly instead of hiding behind TVL. The second one routes around it by refusing to commit to a single fragmented source in the first place.

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

🔬 The Mechanics, One Layer at a Time

🔴 Isolated pool math, restated. On a constant-product AMM, price impact scales with trade size relative to a specific pool's reserves — not relative to that asset's liquidity anywhere else. Ten pools each holding $1 million don't behave like one pool holding $10 million for a large trade; each one independently hits its own steep pricing region far sooner.

🟡 Bridges connect prices, not liquidity. Bridges let capital move between chains and let prices converge through arbitrage, but they don't fuse two pools into one deeper pool. Each chain remains what one analysis calls a semi-independent market — sharing a brand, not necessarily sharing resilience or depth.

🔵 Emissions-driven liquidity is mobile by design. Capital that arrived because of a token emissions program has no structural reason to stay once the program ends. Liquidity genuinely integrated into local DeFi primitives is slower to exit; liquidity chasing incentives is fast to exit — and multi-chain deployments disproportionately attract the fast-exiting kind, because that's exactly the capital most responsive to a new emissions campaign on a new chain.

🟢 Bridge concentration is itself a fragility, not just an inconvenience. Roughly $2.3 trillion in assets now sits locked across cross-chain bridges — meaning the infrastructure meant to solve fragmentation has become a concentrated point of failure in its own right. A major exploit on a widely-used bridge doesn't just affect that bridge's users; it can simultaneously impair liquidity and collateral rebalancing across every ecosystem that depends on it.

🟣 The composition of DeFi TVL itself has shifted toward this exact risk. Bridges now hold more aggregate TVL ($45.38 billion) than lending ($36.50 billion) or liquid staking ($31.77 billion) combined, per DeFiLlama — a reversal from the lending-dominant composition that held through 2024, and a direct reflection of how much value now depends on cross-chain connective infrastructure rather than sitting natively in one place.

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

🧭 Three Architectural Responses, and Where Each One Actually Breaks Down

AMM-native routing (Curve, Uniswap-style, bridged). Prices long-tail assets well because pool math is transparent and permissionless, but this approach fragments stablecoin depth across pools by design — every new chain deployment is a new, independent pool competing for the same underlying dollar-denominated liquidity rather than adding to a shared depth.

Bridge-fed unified pools (Stargate-style, LayerZero-messaging-based). These move a genuinely shared pool's liquidity across chains rather than deploying separate pools per chain, which solves the within-asset fragmentation problem directly — but they cap out on total depth and charge for the capital being moved, and they concentrate risk into the bridge's own security model, which is precisely the systemic exposure described above.

Solver-networked, intent-based settlement (RFQ-style architectures) — where STON.fi's Omniston fits. Rather than holding standing inventory in a fixed pool at all, this model matches a trade intent against whichever source — AMM, bridge, or private market maker — offers the best price at that specific moment, sourcing from multiple paradigms simultaneously instead of committing to one. Omniston is a concrete, working example of exactly this pattern on TON: it queries STON.fi's own pools, external AMMs like DeDust and TonCo, and independent RFQ resolvers all at once, then either selects the single best source or splits the trade across several. STON.fi's own measurements show this cross-DEX optimization delivering roughly 32% lower price impact compared to routing the same trade through a single source — a directly quantified instance of the industry-wide pattern described above, not just a theoretical claim. For pairs where public pools on any of the connected DEXs simply lack depth, Omniston's escrow swaps extend the same logic further, tapping private resolver liquidity that never shows up in any pool's TVL at all — the TON-specific answer to exactly the "public liquidity has a ceiling" problem this entire article is about.

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

⚖️ Comparing on the Dimensions That Actually Matter

💧 TVL vs. effective depth at fixed slippage. TVL answers "how much capital is deployed." Effective depth answers "how much of that capital can actually absorb my trade at an acceptable price" — and the gap between those two numbers is exactly where fragmentation hides.

🧭 Within-chain vs. cross-chain fragmentation. A trader who solves for cross-chain routing but ignores the ten-to-twenty competing pools for the same pair on a single chain has only solved half the problem — both layers degrade execution independently.

⏱️ Sticky liquidity vs. mercenary liquidity. Capital integrated into local DeFi primitives behaves differently under stress than capital parked purely for an emissions multiplier — the second kind is structurally the first to leave, and multi-chain expansions systematically attract more of it.

⚔️ Concentrated bridge risk vs. distributed solver risk. A bridge-fed unified pool centralizes risk into one piece of infrastructure; a solver network distributes it across many independent, competing quote-providers — a meaningfully different risk shape even when both solve the same surface-level liquidity problem.

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

✅ What Genuinely Reduces Fragmentation's Impact

Measuring and routing by effective depth, not TVL. Any system that prices its own execution quality by aggregate locked capital rather than tested depth at real trade sizes is measuring the wrong thing.
Sourcing across paradigms simultaneously, not committing to one. Solver-networked and RFQ-based approaches that check AMMs, bridges, and private market makers in parallel structurally outperform any single-paradigm approach on realized price.
Distinguishing sticky liquidity from mercenary liquidity when evaluating a chain's real resilience. Aggregate TVL growth driven primarily by emissions is a leading indicator of future fragility, not current strength.

⚠️ What's Worth Understanding Correctly

More chains does not mean more usable liquidity by default. Aggregate TVL can double while effective, tradeable depth on any single venue outside the primary one actually deteriorates.
Bridges solve price convergence, not liquidity depth. Arbitrage can keep prices aligned across fragmented pools without ever making any individual pool deeper.
Bridge-concentrated TVL is a systemic risk factor, not just an efficiency question. With more value now sitting in bridge infrastructure than in lending or liquid staking combined, a single major exploit has correspondingly wider blast radius.

🏁 Bottom Line

Liquidity fragmentation across chains isn't solved by adding more chains, and it isn't accurately measured by aggregate TVL — it's a structural consequence of isolated pool math compounding across both protocols within a chain and chains within an ecosystem, worsened by mercenary capital that arrives for incentives and leaves with them, and further complicated by the fact that the infrastructure built to connect fragmented liquidity has itself become one of DeFi's largest concentrated risk surfaces. STON.fi's Omniston layer is a working, measured example of the architecture actually making progress on this: not by consolidating TON's liquidity into one bigger pool, but by querying STON.fi's own pools, DeDust, TonCo, and private resolver liquidity simultaneously on every trade, and routing — or splitting — accordingly. Fragmentation didn't get solved by fewer chains or fewer pools. On TON specifically, it got routed around.

🔗 Sources & Further Reading

STON.fi Blog — "Cross-DEX Swaps via Omniston" (measured 32% lower price impact) — https://blog.ston.fi/cross-dex-swaps-via-ton/
STON.fi — Omniston Protocol Overview (multi-source RFQ architecture) — https://docs.ston.fi/developer-section/omniston
Spark — "Liquidity Fragmentation" Glossary Entry — https://www.spark.money/glossary/liquidity-fragmentation
Medium, Ice ❄️ — "Multi-Chain Liquidity: Expansion or Fragmentation? A Field Perspective" — https://ice0913.medium.com/multi-chain-liquidity-expansion-or-fragmentation-a-field-perspective-bcc7ae5ca3bb
CoinLaw — "DeFi Market Statistics 2026: TVL, Chains & DEXs" — https://coinlaw.io/decentralized-finance-market-statistics/
Eco — "Top Cross-Chain Liquidity Protocols for 2026" — https://eco.com/support/en/articles/11776421-top-cross-chain-liquidity-protocols-for-2026
Symbiosis — "How DeFi Works Now: 2026 Tech Stack Explained" — https://symbiosis.finance/blog/defi-in-2025-2026-what-changed-technically
CryptoDaily — "Stablecoin Liquidity Explained: Why Custom Tokens Fragment" — https://cryptodaily.co.uk/2026/07/stablecoin-liquidity-custom-tokens-fragment

This article reflects independent research based on publicly available industry data and analysis as of mid-2026. TVL, slippage, and depth figures shift constantly with market conditions — always verify current numbers directly on DeFiLlama or the relevant protocol before making decisions involving real funds.

Ecosystem Map: How STON.fi, Omniston, and xStocks Connect on TON

Web3KD — Fri, 21 Aug 2026 11:24:41 +0000

Ecosystem Map: How STON.fi, Omniston, and xStocks Connect on TON

Three names get mentioned together constantly in TON DeFi conversations, and it's easy to assume they're roughly interchangeable — different marketing terms for the same underlying thing. They're not. Each one is a genuinely distinct layer, and understanding where one ends and the next begins is the difference between a surface-level impression of "TON has DeFi and stocks now" and actually understanding the architecture connecting them.

🗨️ "STON.fi technically integrates the last step. It does not issue the product, does not hold the legacy instruments, and does not run the custody; it surfaces the on-chain jetton and routes swaps around it." — STON.fi Blog, "How xStocks Actually Work"

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

🌐 Three Layers, Three Different Jobs

🎫 STON.fi is the trading surface — the AMM, the app, the interface where swaps, liquidity provision, farming, and staking actually happen
🏷️ Omniston is the routing and liquidity-sourcing layer underneath STON.fi — it decides where a trade actually gets filled, whether that's a public pool, another DEX, or private resolver liquidity
🪧 xStocks is an asset category, not a protocol at all — tokenized real-world equities that happen to be tradeable through STON.fi, routed by Omniston, but issued and backed by an entirely separate, regulated entity

The relationship isn't three peers. It's a stack: an asset class (xStocks) flows through a routing engine (Omniston) that surfaces inside a trading interface (STON.fi). Each layer can be understood independently, but the interesting part is exactly where they connect.

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

Where xStocks Actually Come From Before They Ever Reach TON

It's tempting to think of an xStock as something STON.fi created. It didn't — and tracing the actual path clarifies what STON.fi's role really is.

🗨️ "Traditional asset → regulated product → bToken on an origin chain → wrapped representation on TON → xStock jetton you see in your wallet." — STON.fi Blog

xStocks are issued by Backed Finance, a regulated entity that holds the actual underlying equities — real shares of Apple, Tesla, Nvidia, and others — through licensed custodians. Backed mints a blockchain-native representation of that holding, originally on an EVM chain, which then gets wrapped into a TON-native jetton. By the time an xStock shows up as AAPLx or TSLAx in a TON wallet, it's already passed through several steps of regulated tokenization that have nothing to do with STON.fi at all. STON.fi's actual job starts at the very last step: making that jetton tradeable.

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

🧬 How Omniston Specifically Had to Adapt for xStocks

This is the part that actually reveals how these layers connect technically, not just conceptually.

🗨️ "The harder challenge was liquidity: unlike established crypto pairs, xStocks don't yet have deep AMM pools across pairs. Technically, AMM support is there. But we also introduced an additional execution path — escrow swaps — so users can access deeper liquidity. Today, most xStocks volume executes through escrow." — Fedorov, STON.fi team, via BeInCrypto

xStocks behave like any other TON jetton technically, but they don't yet have the deep, organic AMM liquidity that established crypto pairs have built up over time. Omniston's answer wasn't to force xStocks trades through thin public pools — it was to lean on escrow swaps, the same private-resolver liquidity mechanism built to solve liquidity gaps generally, now handling the majority of actual xStocks trading volume. This is a concrete example of one layer (Omniston) adapting specifically to support a new asset category (xStocks) surfacing through the trading layer (STON.fi) — the connection isn't abstract, it's a real routing decision happening on real trades.

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

🏦 The Full Map, Layer by Layer

🪙 Issuance and custody — outside the TON stack entirely Backed Finance holds the actual underlying equities through regulated custodians and mints the tokenized representation. Kraken provides institutional validation. Neither of these entities is part of STON.fi or Omniston — they're the foundation the whole thing rests on, sitting entirely outside TON's technical stack.

🧾 Token standard — where regulation meets on-chain mechanics xStocks follow the TON jetton standard for basic transfers and wallet compatibility, but specifically use Scaled UI Jettons (TEP-526) — a standard that lets a token's displayed balance reflect a scaling factor over time, used here to represent accumulated dividend value without STON.fi itself distributing any dividends directly.

🎫 STON.fi — the trading surface A dedicated page at ston.fi/xstocks lets eligible users swap TON or USDT directly for xStocks like AAPLx, TSLAx, NVDAx, GOOGLx, AMZNx, and broader index exposure. Once acquired, xStocks behave like any other jetton — they can be held, used in other TON DeFi applications, or provided as liquidity.

🏷️ Omniston — the routing decision underneath every xStocks trade Because AMM depth for xStocks pairs is still thin, Omniston evaluates both public pool liquidity and private resolver-priced liquidity for every xStocks trade, routing through whichever actually delivers a better realized price — which in practice means escrow swaps carry most of the real volume today.

🪧 Wallets and Telegram — the distribution layer on top of all of it Because xStocks comply with the jetton standard, they're automatically recognized by TON-native wallets — TON Wallet, Tonkeeper, MyTONWallet — including the wallet built directly into Telegram, meaning the full stack described above ultimately surfaces inside an app hundreds of millions of people already have open daily.

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

🧑‍💻 What the Connection Between These Layers Actually Looks Like in Code

Since the interesting part of this map is a real routing decision, not just a diagram, it's worth seeing what that decision looks like from a developer's side. The snippets below are illustrative, written in the style of STON.fi's documented SDK patterns.

Requesting a quote for an xStock behaves identically to any other jetton — the trading surface (STON.fi) doesn't need special-case code, because the asset category difference is invisible at this layer:

import { Omniston, blockchain, settlementMethod } from '@ston-fi/omniston-sdk';

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

const { rfqId } = await omniston.requestQuote({
  quoteRequest: {
    offerAsset: { blockchain: blockchain.Ton, address: 'EQC...usdt_jetton' },
    askAsset: { blockchain: blockchain.Ton, address: 'EQC...aaplx_jetton' }, // an xStock
    amount: { offerAmount: '500000000' },
    settlementMethods: [settlementMethod.Swap],
  },
});

Where the layers actually diverge is inside the quote response itself — this is the concrete, code-level evidence of Omniston's routing adaptation for thin-liquidity assets like xStocks:

omniston.trackQuote({ rfqId }).subscribe((event) => {
  if (event.type === 'quoteUpdated') {
    console.log('Settlement source:', event.quote.settlementSource);
    // For an established crypto pair, this is often 'amm_pool'
    // For most xStocks pairs today, this commonly resolves to 'escrow_resolver'
  }
});

Detecting the TEP-526 scaling factor on an xStock jetton, relevant if a wallet or app wants to display accumulated dividend value correctly rather than a raw balance:

async function getDisplayBalance(jettonWalletAddress: string) {
  const jettonData = await client.runMethod(jettonWalletAddress, 'get_wallet_data');
  const rawBalance = jettonData.balance;
  const scalingFactor = jettonData.scalingFactor ?? 1; // TEP-526, defaults to 1 for non-scaled jettons

  return rawBalance * scalingFactor; // what the user should actually see
}

Nothing in the first snippet knows or cares that it's trading an xStock — that's the point. The routing and scaling differences live entirely inside Omniston's decision logic and the token's own metadata, not in application-level branching a developer has to write themselves.

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

🌐 Comparing on the Dimensions That Actually Matter

💧 What STON.fi controls vs. what it doesn't. STON.fi controls the trading interface and the on-chain swap mechanics. It doesn't control issuance, custody, regulatory compliance, or the underlying equity itself — that entire layer belongs to Backed Finance, independently of anything happening on TON.

🧭 Crypto-native pairs vs. xStocks pairs, at the routing level. A deep, established crypto pair might resolve almost entirely through public AMM pools. An xStocks pair, at least currently, resolves mostly through escrow — a genuinely different routing outcome for a genuinely different liquidity situation, decided automatically by the same underlying Omniston logic.

⏱️ Traditional market hours vs. on-chain availability. Once tokenized, an xStock trades whenever TON itself is live — 24/7, independent of when the underlying equity's home exchange is actually open, which is a structural difference from the asset it represents, not just a convenience feature.

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

✅ What Genuinely Connects These Three Layers

A shared token standard, not shared ownership. xStocks work inside STON.fi because they follow TON's jetton standard, not because STON.fi issues or controls them in any way.
Omniston adapting its routing logic for a new asset category. The rise in escrow-swap usage for xStocks is a direct, measurable consequence of a new asset type surfacing through the existing routing engine.
Wallet-level recognition tying the whole stack to actual distribution. Because of jetton-standard compliance, the entire chain — from regulated custody to a TON swap — ends up one tap away inside apps people already use daily, including Telegram.

⚠️ What's Worth Understanding Correctly

STON.fi is not the issuer of xStocks, and doesn't hold the underlying equities. That responsibility sits entirely with Backed Finance and its regulated custodians.
Most xStocks liquidity today runs through escrow, not public AMM pools. This is a current state of a growing asset category, not a permanent architectural limitation.
xStocks are not available to all users. Eligibility restrictions apply, and prospective users should check current terms directly rather than assume universal access.

🏁 Bottom Line

STON.fi, Omniston, and xStocks aren't three versions of the same thing — they're three layers of one connected stack, each doing a genuinely different job. Backed Finance and its custodians handle issuance and regulatory backing, entirely outside TON. Omniston handles the routing decision for every trade, adapting its own liquidity strategy specifically because xStocks arrived with a different liquidity profile than crypto-native pairs. STON.fi surfaces all of it as an actual tradeable interface, one that jetton-standard compliance then makes visible inside wallets — including Telegram's — that people already have open. Understanding the map means understanding that "STON.fi has stocks now" is really shorthand for a much more layered, cross-entity system working together underneath one interface.

🔗 Sources & Further Reading

STON.fi Blog — "How xStocks Actually Work: From Real-World Asset to TON Jetton" — https://blog.ston.fi/how-xstocks-actually-work-from-real-world-asset-to-ton-jetton/
STON.fi Blog — "xStocks: Explore Tokenized Market" — https://blog.ston.fi/xstocks-explore-tokenized-market/
STON.fi — xStocks Trading Page — https://ston.fi/xstocks
TON Blog — "xStocks Are Live on TON: Real-World Stocks, Now On-Chain" — https://blog.ton.org/x-stocks-are-live-on-ton-real-world-stocks-now-on-chain
BeInCrypto — "How STON.fi's Omniston Scaled DeFi on TON" (escrow model for xStocks, direct team quotes) — https://beincrypto.com/stonfi-omniston-scaling-lessons/

This article reflects independent research based on STON.fi's and TON's public documentation and announcements as of mid-2026. Asset availability, eligibility requirements, and routing behavior evolve as the ecosystem grows — always verify current details directly on ston.fi and docs.ston.fi before making decisions involving real funds.

Testing for Failed Transactions: A Builder's Checklist for STON.fi Integrations

Web3KD — Fri, 21 Aug 2026 10:29:26 +0000

Testing for Failed Transactions: A Builder's Checklist for STON.fi Integrations

Most integration bugs don't show up in code review. They show up in production, as a transaction that "just failed," with an exit code the team has to look up and a user asking why their swap didn't go through. This checklist exists to catch those failures before they ship — with the actual exit codes, the actual sandbox environment, and real failure patterns pulled from genuine integration issues developers have hit building on STON.fi.

🗨️ "For most integrations, we recommend using our Node.js SDK or React SDK. The SDKs handle WebSocket connections, quote streaming, transaction building, and error handling automatically." — STON.fi, Omniston Swap Overview documentation

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

🧯 Start With the Environment You're Actually Testing Against

Before writing a single test case, confirm which endpoint your code is hitting. This sounds obvious and is still the source of a surprising number of "why did this work yesterday" bugs.

1️⃣ Production: wss://omni-ws.ston.fi — real liquidity, real funds, real consequences for a bad transaction
2️⃣ Sandbox: wss://omni-ws-sandbox.ston.fi — explicitly documented as for development and testing only

Running integration tests against production because the sandbox URL wasn't configured is a completely avoidable failure mode, and it's worth a dedicated environment-variable check in CI specifically to catch it before any test suite runs.

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

The Exit Codes Worth Knowing Before You Debug Blind

When a transaction fails on TON, it returns a numeric exit code — and knowing what a handful of the common ones actually mean turns a mystery failure into a five-minute fix.

🗨️ "If all funds of the inbound message have already been consumed and there are not enough funds to pay for the failed action... an error with exit code 37 is thrown: Not enough GRAMs." — TON Docs, TVM Exit Codes reference

Exit Code	Meaning	Typical Cause
32	Invalid action list	A malformed or exotic cell in the action list
37	Not enough GRAMs	Insufficient TON to cover the action's cost
38	Not enough extra currencies	Insufficient balance of a non-TON currency the action needs
39	Outbound message doesn't fit into a cell	The message payload exceeds TON's cell size limits

These aren't hypothetical — real developers integrating STON.fi's SDK have hit specific exit codes like 11 and 709 in production issues, tracing back to jetton wallet address resolution and reverse-swap parameter mistakes respectively. Logging the raw exit code, not just "transaction failed," is the single highest-leverage change most integrations can make to their error handling.

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

🩹 The Checklist: Failure Modes to Actually Test For

3️⃣ Test with minAskAmount set to zero, deliberately, once. This is a real mistake pulled directly from a public integration issue — a developer building a swap left minAskAmount: 0, which means no slippage protection exists at all. Test this scenario specifically to confirm your own code never ships with this default, since a zero minimum will "succeed" a transaction that delivers almost nothing back.

// ❌ Never ship this — no slippage protection at all
const txParams = await router.buildSwapJettonTxParams({
  minAskAmount: '0', // any price gets accepted
  // ...
});

// ✅ Always derive a real minimum from your slippage tolerance
const minAskAmount = calculateMinAskAmount(quote.askAmount, slippageBps);

4️⃣ Test insufficient gas explicitly. A swap transaction needs enough TON reserved to cover network fees on top of the trade itself. Write a test that intentionally underfunds the gas amount and confirms your app surfaces exit code 37 clearly, rather than a generic failure message.

async function testInsufficientGas() {
  const result = await sendSwap({ ...validParams, gasAmount: '10000' }); // too low
  expect(result.exitCode).toBe(37);
  expect(result.userMessage).toMatch(/insufficient.*gas/i);
}

5️⃣ Test reverse-swap parameter direction. A real, documented issue came from treating a reverse swap (jetton-to-TON) as identical to a regular swap with askJettonAddress simply swapped to a proxy TON address — this produced exit code 709 for at least one developer. If your integration supports both directions, test each direction as a genuinely separate code path, not a parameter flip on the same function.

6️⃣ Test a stale or expired quote. Simulate a delay between requesting a quote and submitting the transaction, long enough that the quote should reasonably be considered outdated. Confirm your integration re-requests rather than blindly submitting stale terms.

async function testStaleQuote() {
  const { quote, rfqId } = await getQuote(amount);
  await sleep(60_000); // simulate user hesitation
  const result = await executeSwap(quote, rfqId);
  // Expect either a fresh re-quote or a clean, explicit failure —
  // never a silent execution against 60-second-old terms
  expect(['refreshed', 'expired']).toContain(result.status);
}

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

🔎 Verifying the Failure Path, Not Just the Success Path

A transaction that fails cleanly and refunds correctly is a successful outcome from a testing standpoint — it's the failures that fail silently or incorrectly that actually cause damage.

🗨️ "(Optional) The address where funds should be returned if the transaction fails. If not specified, funds are returned to the sender's wallet." — STON.fi, Omniston Swap Overview documentation

Test both branches of this explicitly:

describe('refund handling', () => {
  it('returns funds to sender when refundAddress is omitted', async () => {
    const result = await simulateFailedSwap({ refundAddress: undefined });
    expect(result.refundedTo).toBe(senderWallet.address);
  });

  it('returns funds to the specified refundAddress when set', async () => {
    const result = await simulateFailedSwap({ refundAddress: customAddress });
    expect(result.refundedTo).toBe(customAddress);
  });
});

Skipping this test specifically is how teams discover, in production, that an edge case in their refund logic sent funds somewhere unexpected — exactly the kind of bug that's cheap to catch in sandbox and expensive to discover after a real user reports missing funds.

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

🛡️ Comparing on the Dimensions That Actually Matter

💧 SDK-handled errors vs. low-level protocol errors. STON.fi's own documentation is explicit that the Node.js and React SDKs handle error handling automatically for most integrations — testing at the low-level WebSocket protocol layer is only necessary if you've deliberately opted out of that abstraction.

🧭 Sandbox coverage vs. production monitoring. Sandbox testing catches logic errors before deployment; it doesn't replace production monitoring for exit codes appearing at real volume, since some failure conditions — like transient network congestion — are difficult to reproduce reliably in a test environment.

⏱️ Synchronous failures vs. timing-dependent failures. A malformed parameter fails immediately and predictably. A stale quote or a race between simulation and execution only fails under specific timing conditions, which is exactly why deliberate delay-based tests matter more than they might seem to.

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

✅ What a Genuinely Solid Test Suite Covers

Every documented exit code your integration is likely to hit, logged with enough context to debug without re-running the transaction.
Both refund paths — default sender refund and an explicitly specified refundAddress — verified independently.
At least one deliberately broken test per parameter that guards user funds, especially minAskAmount, since a silent zero-default is a real, documented failure mode.

⚠️ What's Worth Understanding Correctly

A generic "transaction failed" message is a testing gap, not a UI limitation. The exit code is available; surfacing it (or a translation of it) is a choice, not a constraint.
Sandbox and production are genuinely separate environments, not a toggle on the same endpoint. Confirm which one every test run is actually targeting.
Real GitHub issues are a legitimate test-case source. Public integration problems other developers have hit are, functionally, a pre-written regression test suite for exactly the mistakes worth guarding against.

🏁 Bottom Line

Testing for failed transactions on STON.fi isn't about imagining hypothetical edge cases — it's about deliberately reproducing the specific, documented failure modes that real integrations have already hit: zero-slippage-protection defaults, insufficient gas, reverse-swap parameter mix-ups, stale quotes, and untested refund paths. A checklist built from real exit codes and real reported issues catches these before a user does, which is the entire point of testing a payment-adjacent integration in the first place.

🔗 Sources & Further Reading

TON Docs — TVM Exit Codes Reference — https://docs.ton.org/v3/documentation/tvm/exit-codes
STON.fi — Omniston Swap Overview (sandbox/production endpoints, refundAddress) — https://docs.ston.fi/developer-section/omniston/swap/overview
STON.fi SDK — GitHub Issues (real reported integration failures) — https://github.com/ston-fi/sdk/issues
STON.fi — React Swap Quickstart Guide — https://docs.ston.fi/developer-section/quickstart/swap
STON.fi — SDK v2 Swap Documentation — https://docs.ston.fi/developer-section/dex/sdk/v2/swap

This article reflects independent research based on STON.fi's public developer documentation, TON's official exit code reference, and publicly reported integration issues as of mid-2026. Exit codes, SDK behavior, and endpoints evolve as the protocol ships updates — always verify current details directly on docs.ston.fi before shipping a production integration.

How the Best Price Actually Gets Found: A Technical Breakdown of Omniston's Quote-Sourcing Engine

Web3KD — Thu, 20 Aug 2026 12:48:49 +0000

How the Best Price Actually Gets Found: A Technical Breakdown of Omniston's Quote-Sourcing Engine

Ask "what's the best price for this swap?" and most DEXs answer by reading one number off one pool. Omniston, STON.fi's routing layer, answers that question by running an entire sourcing architecture underneath a single request — querying multiple, structurally different kinds of liquidity at once and comparing what comes back. This piece breaks down that architecture: not the marketing pitch, but the actual layers and data flow behind "best price."

🗨️ "Omniston is STON.fi's aggregation layer that finds best rates by combining on-chain liquidity sources and RFQ resolvers." — STON.fi developer documentation

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

🧱 The Two Fundamentally Different Kinds of Liquidity Being Queried

The architecture isn't querying one type of source multiple times — it's querying two genuinely different kinds of liquidity, each with its own logic, and comparing across them:

🧿 On-chain AMM pools. STON.fi's own pools, plus external TON AMMs like DeDust and TonCo, priced by their own constant-product or stableswap curves, readable directly from on-chain reserves.
🔱 RFQ resolvers. Independent market makers who don't have a fixed public pool at all — they respond to a specific request with a price they're personally willing to honor, decided fresh each time.

These aren't competing implementations of the same idea. An AMM pool's price is a deterministic function of its current reserves — anyone can calculate it. A resolver's quote is a decision, informed by inventory and risk appetite, that doesn't exist until it's actually asked for. Sourcing "the best quote" means comparing a calculation against a decision, in real time, and that's a meaningfully harder problem than just checking which of several static numbers is bigger.

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

Why a Single Integration Point Matters More Than It Sounds

It would be easy to assume "aggregation" just means "check several places and pick the best." The harder engineering problem is that these sources don't share a common interface on their own — a DEX pool and an independent resolver don't naturally speak the same protocol.

🗨️ "Omniston connects to multiple DEXs and RFQ resolvers, allowing users to access a wide range of liquidity sources through a single integration point." — independent Omniston protocol breakdown, 2025

That single integration point is doing real translation work: normalizing an on-chain pool read and an off-chain-adjacent resolver's signed quote into one comparable format, so a developer building on top of STON.fi never has to write separate logic for "if it's a pool" versus "if it's a resolver." That abstraction is a meaningful part of what "RFQ architecture" actually refers to — not just the request-for-quote handshake itself, but the whole normalization layer sitting behind it.

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

🔭 The Architecture, Layer by Layer

🧰 The client-facing layer A trader or an integrated app sends one swap request through the SDK or API — one call, regardless of how many sources ultimately get queried underneath it. This layer's whole job is hiding the complexity of everything below it.

🛎️ The RFQ core This is the coordination layer: it receives the request, assigns it a unique rfq_id, and fans it out to every connected source simultaneously — both triggering fresh reads from AMM pools and broadcasting the request to resolvers over their open gRPC streams.

🪝 The resolver network A distributed set of independent market makers, each running their own service, each deciding independently what to offer for that specific request. Nothing here is centrally controlled — the RFQ core is a coordinator, not a price-setter.

⚜️ On-chain pool readers In parallel with the resolver broadcast, the same request triggers a read against connected AMM pools' current reserves — STON.fi's own v1 and v2 pools, plus external pools like DeDust and TonCo — calculating what each would offer for that exact trade size right now.

🎗️ The comparison and selection engine Once responses come back from both categories of source, this layer evaluates them together — price, but also depth and reliability — and either selects a single winning source or constructs a split route across several, depending on what actually produces the best outcome for that specific trade.

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

🧑‍💻 What the Sourcing Layer Actually Looks Like in Code

Since this is genuinely an engineering architecture underneath the trading language, it's worth seeing the real shape of it. The snippets below are illustrative — written in the style of STON.fi's documented SDK patterns, simplified for clarity rather than copied verbatim from the official docs.

One request, fanned out to two source types in parallel:

import { Omniston, blockchain, settlementMethod } from '@ston-fi/omniston-sdk';

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

// A single call — the fan-out to pools and resolvers happens underneath this
const { rfqId } = await omniston.requestQuote({
  quoteRequest: {
    offerAsset: { blockchain: blockchain.Ton, address: 'EQC...offer_jetton' },
    askAsset: { blockchain: blockchain.Ton, address: 'EQC...ask_jetton' },
    amount: { offerAmount: '1000000000' },
    settlementMethods: [settlementMethod.Swap],
  },
});

Inside the RFQ core, roughly what's happening on receipt of that request:

async function handleQuoteRequest(request: QuoteRequest): Promise<RfqId> {
  const rfqId = generateRfqId();

  // Two structurally different source types, queried in parallel
  const [poolQuotes, resolverQuotes] = await Promise.all([
    readAmmPoolReserves(request), // deterministic — calculated from on-chain state
    broadcastToResolvers(request, rfqId), // decision-based — awaits live responses
  ]);

  const candidates = normalizeQuotes([...poolQuotes, ...resolverQuotes]);
  const route = selectBestRoute(candidates); // single winner, or a split across several

  return rfqId;
}

Normalizing two genuinely different quote shapes into one comparable format:

function normalizeQuotes(raw: (PoolReserveRead | ResolverResponse)[]): Quote[] {
  return raw.map((source) =>
    'reserves' in source
      ? { type: 'pool', askAmount: calcConstantProductOutput(source), depth: source.reserves }
      : { type: 'resolver', askAmount: source.quotedAmount, depth: source.maxFillSize }
  );
}

That normalization step is the actual engineering core of "RFQ architecture" — a pool read and a resolver's signed response start out as two incompatible shapes, and everything downstream (comparison, routing, splitting) depends on collapsing them into one interface first.

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

🧰 Cross-Chain Adds a Third Dimension Entirely

Same-chain sourcing is already a two-source comparison problem. Cross-chain sourcing adds settlement architecture into the same decision.

🗨️ "Omniston uses the same RFQ flow for both TON and cross-chain swaps... cross-chain settlement is handled through HTLC-based atomic swaps." — STON.fi, Omniston Protocol documentation

For a cross-chain request, the sourcing engine isn't just asking "who has the best price" — it's asking that question and factoring in which resolvers can actually settle safely across two separate blockchains. A resolver quoting a cross-chain leg has to be able to lock destination-side assets in an HTLC, paired against the trader's source-side lock, sharing the same cryptographic condition. The "best quote" for a cross-chain trade is filtered, from the start, to resolvers capable of that settlement guarantee — not just whoever happens to quote the tightest number.

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

🔭 Comparing on the Dimensions That Actually Matter

💧 Deterministic sources vs. decision-based sources. An AMM pool's price can be calculated by anyone with reserve data; a resolver's quote is a live decision that only exists once requested. The architecture has to treat these as genuinely different categories of input, not variations on the same thing.

🧭 Single-source lookup vs. normalized multi-source comparison. Without a shared integration layer, comparing a pool's calculated price against a resolver's signed quote would require bespoke logic for every source added. The RFQ core exists specifically to remove that burden from anyone building on top of it.

⏱️ Same-chain sourcing vs. cross-chain sourcing. Same-chain sourcing is purely a pricing comparison. Cross-chain sourcing is a pricing comparison filtered by settlement capability — a resolver can't win a cross-chain quote it can't actually settle safely.

⚖️ Single winner vs. split route. The sourcing engine doesn't default to picking one winner — if splitting a trade across several sources genuinely produces a better blended outcome, that becomes the selected route instead.

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

✅ What Genuinely Makes This Sourcing Architecture Work

Two structurally different source types, compared on equal footing. Deterministic pool math and live resolver decisions get normalized into one comparable format rather than handled as separate systems.
A single coordination layer removes integration burden. Anyone building on top of STON.fi queries one interface, not a growing list of bespoke connections to individual pools and market makers.
Cross-chain quotes are pre-filtered by settlement capability. A resolver can't win a cross-chain trade it can't actually settle atomically, which protects the trader before price even enters the comparison.

⚠️ What's Worth Understanding Correctly

"Best quote" isn't always a single winner. The architecture is equally capable of returning a split route when that genuinely beats any single source.
Resolver quotes are decisions, not standing offers. A quote reflects that resolver's willingness at that specific moment — it isn't a permanent price sitting on a shelf.
Cross-chain sourcing carries a narrower pool of eligible resolvers by design. That's a safety filter, not a limitation — capability to settle safely comes before price in that specific comparison.

🏁 Bottom Line

Sourcing the best quote isn't a single lookup — it's an architecture running two structurally different comparison problems in parallel: deterministic pool math on one side, live resolver decisions on the other, normalized through a shared coordination layer and, for cross-chain trades, filtered by settlement capability before price ever enters the picture. Understanding that architecture is the difference between assuming "best price" means "checked a few extra pools" and seeing it for what it actually is — a real-time comparison engine built specifically because those source types were never going to be comparable on their own.

🔗 Sources & Further Reading

STON.fi — Omniston Protocol Overview — https://docs.ston.fi/developer-section/omniston
STON.fi — How to Become a Resolver (RFQ flow, gRPC API) — https://docs.ston.fi/developer-section/omniston/resolvers/guide
STON.fi Blog — "Cross-Chain Portfolio Rebalancing: How HTLC and RFQ Swaps Work" — https://blog.ston.fi/cross-chain-portfolio-rebalancing-how-htlc-and-rfq-swaps-work-for-defi-users/
STON.fi Docs — Introduction (AMM and Omniston overview) — https://docs.ston.fi/
Medium, Web3King — "Omniston by STON.fi: Revolutionizing Liquidity Aggregation, pt. 2" — https://medium.com/@web3king/omniston-by-ston-fi-revolutionizing-liquidity-aggregation-on-the-ton-blockchain-pt2-748db5057f6c

This article reflects independent research based on STON.fi's public developer documentation as of mid-2026. Architecture details and supported protocols evolve as the system ships updates — always verify current functionality directly on docs.ston.fi before making decisions involving real funds.

The Hidden Auction Behind Every Quote: How Resolver Competition Actually Sets Your Price

Web3KD — Thu, 20 Aug 2026 12:07:20 +0000

The Hidden Auction Behind Every Quote: How Resolver Competition Actually Sets Your Price

Every time someone requests a quote on STON.fi through Omniston, something closer to a live auction happens than a lookup. A group of independent market makers — resolvers — get notified simultaneously, and they compete, in real time, for the right to fill that specific order. Most traders never see this happen. This piece looks at the actual mechanics of that competition, not the marketing shorthand of "best price guaranteed."

🗨️ "A resolver is a service that provides token exchange rates and executes trades... when a trader sends a quote request, they will first receive a QuoteRequestAck containing the rfq_id that uniquely identifies their request." — STON.fi, "How to Become a Resolver" documentation

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

🎪 Why This Is Genuinely an Auction, Not a Price Feed

The distinction matters more than it sounds. A price feed is passive — one number, updated periodically, the same for everyone who checks it. What Omniston runs instead is active and request-specific:

⬢ A trader's quote request gets broadcast to every connected resolver simultaneously, not looked up from a shared table
⬡ Each resolver independently decides what price it's willing to offer for that specific size, at that specific moment
⬟ The system compares every response and selects the winner — the resolver offering the best terms takes the trade

Two people requesting the same nominal trade seconds apart aren't reading the same number off a board. They're each triggering their own independent round of competitive bidding among resolvers deciding, in real time, what they're willing to offer.

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

What's Actually Happening on the Wire

This isn't a vague "competition happens somewhere" claim — it's a defined, technical protocol with named stages, and understanding those stages is what makes the pricing mechanism legible rather than a black box.

🗨️ "The resolver API uses a bidirectional gRPC stream." — STON.fi resolver integration documentation

Resolvers connect to Omniston over a persistent, two-way gRPC stream — not a one-off API call per quote, but an ongoing connection kept open specifically so resolvers can react to requests the moment they arrive. When a trade request comes in, connected resolvers receive a QuoteRequestedEvent. Each resolver's own pricing logic decides, in that moment, what rate it's able to offer for that specific size and pair — informed by its own inventory, its own risk appetite, and its own read of where the broader market is trading. That response becomes a QuoteAcceptedEvent if it clears validation, carrying a quote_id that ties it back to the original request.

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

🕰️ The Sequence, Step by Step

🔓 Step one: the request gets a fingerprint The moment a trader submits a swap request, they receive a QuoteRequestAck containing an rfq_id — a unique identifier tying every subsequent quote, acceptance, and execution back to that exact request. Nothing about this trade's pricing exists independently of this specific, timestamped ask.

🛰️ Step two: every connected resolver hears it at once Rather than the trader polling sources one at a time, the request goes out to every resolver in the connected network simultaneously via the open gRPC stream, as a QuoteRequestedEvent. Whichever resolvers are online and willing to price that pair all see the same request at effectively the same moment.

🧨 Step three: independent, competing pricing decisions Each resolver decides on its own terms what it's willing to offer — this isn't coordinated or shared between resolvers. A resolver holding more inventory of the requested output token, or with a more aggressive risk model that day, might quote tighter than one that's cautious or thin on that specific asset. This genuine independence is what makes it competition rather than a cartel reading from the same sheet.

⬠ Step four: validation and selection Quotes that clear come back as QuoteAcceptedEvents, each carrying its own quote_id. Omniston compares what's actually come back and selects the winning terms — not necessarily just the single best headline number in isolation, but weighed against depth and reliability, consistent with how the broader routing engine treats any liquidity source.

⬣ Step five: execution against the winning quote Once a quote is selected, execution proceeds against those specific terms — for same-chain trades, through standard TON settlement; for cross-chain trades, through resolver-funded HTLCs on the destination side paired against the trader's locked funds on the source side, so the resolver's win doesn't create counterparty risk for the trader even after being selected.

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

🧑‍💻 What This Actually Looks Like in Code

Since this is genuinely an engineering topic underneath the trading language, it's worth seeing the real shape of it — both sides of the wire, illustrated in the style of STON.fi's documented SDK and resolver API patterns (simplified for clarity, not copied verbatim from the official docs).

On the trader side, requesting a quote through the Omniston SDK looks something like this:

import { Omniston, blockchain, settlementMethod } from '@ston-fi/omniston-sdk';

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

// Every request gets its own tracked identity, per rfq_id
const { rfqId } = await omniston.requestQuote({
  quoteRequest: {
    offerAsset: {
      blockchain: blockchain.Ton,
      address: 'EQC...offer_jetton',
    },
    askAsset: {
      blockchain: blockchain.Ton,
      address: 'EQC...ask_jetton',
    },
    amount: { offerAmount: '1000000000' }, // 1 unit, 9 decimals
    settlementMethods: [settlementMethod.Swap],
  },
});

// Stream quotes as resolvers respond — the "auction" arriving in real time
omniston.trackQuote({ rfqId }).subscribe((event) => {
  if (event.type === 'quoteUpdated') {
    console.log('New competing quote:', event.quote.askAmount);
  }
});

On the resolver side, the market maker's own service is listening on that open gRPC stream for exactly this kind of request, and answers independently:

resolverStream.on('data', (event) => {
  if (event.type === 'QuoteRequestedEvent') {
    const { rfqId, offerAsset, askAsset, offerAmount } = event.quoteRequest;

    // This resolver's own pricing logic — inventory, risk, market read
    const myAskAmount = computeCompetitivePrice(offerAsset, askAsset, offerAmount);

    resolverStream.write({
      type: 'QuoteResponse',
      rfqId,
      askAmount: myAskAmount,
      signature: signWithEd25519(rfqId, myAskAmount), // resolver's own key
    });
  }
});

Nothing coordinates these two snippets except the shared rfqId. The trader's client is just listening for whatever comes back; the resolver's service is independently deciding what to offer. That gap — no shared logic, only a shared identifier — is the actual mechanical definition of "competition" in this system, not a figure of speech.

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

🔓 Why This Genuinely Helps Even Thin, Unusual Pairs

Resolver competition isn't just a marginal improvement on liquid pairs — it's specifically valuable for the trades a pure AMM pool struggles with most.

🗨️ "RFQ functionality, where 'resolvers' (smart quote engines) compete to offer the best rates, ensures competitive pricing even for low-liquidity tokens." — independent Omniston SDK writeup, Medium, 2025

A public AMM pool for an obscure pair might simply not have meaningful depth — no amount of routing sophistication fixes liquidity that was never deposited. Resolvers don't have that same constraint, because they're not limited to whatever's sitting in a public pool. A resolver can price a trade based on inventory it's holding off-chain-adjacent, or its own hedging capability elsewhere, offering competitive terms for a pair that would otherwise slip badly through thin public liquidity alone.

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

✅ What Genuinely Makes This Competitive Pricing Work

Every quote request is independently broadcast, not looked up. There's no shared, stale price table — each rfq_id triggers its own fresh round of bidding.
Resolvers price independently, not in coordination. Genuine competition, not a shared formula, is what creates pressure toward tighter pricing.
The protocol, not the trader, verifies and selects. Validation and selection happen inside Omniston's own logic, removing the burden of manually comparing raw resolver responses.

⚠️ What's Worth Understanding Correctly

A resolver's quote isn't guaranteed forever. Quotes carry their own validity window; conditions that shift between quoting and execution can change what's actually available.
More resolvers online doesn't guarantee a better price on every single request. It raises the odds of competitive pricing, but any individual resolver can choose not to quote tightly on a given trade for its own inventory reasons.
Cross-chain resolver settlement still relies on HTLC-based atomicity for safety. Winning a quote auction and completing settlement safely are two different guarantees, and the second one is what actually protects a trader's funds.

🏁 Bottom Line

The price shown on a STON.fi swap isn't pulled from a static table — it's the outcome of a live, per-request auction among independent resolvers, run over a persistent connection and tracked end to end by a unique request ID from the first ping to final execution. That structure is exactly why resolver-based pricing tends to hold up even on pairs a public AMM pool alone would struggle to price well, and why two seemingly identical requests can genuinely produce two different, equally legitimate outcomes.

🔗 Sources & Further Reading

STON.fi — How to Become a Resolver (gRPC API, RFQ flow, quote lifecycle) — https://docs.ston.fi/developer-section/omniston/resolvers/guide
STON.fi — Omniston Protocol Overview — https://docs.ston.fi/developer-section/omniston
STON.fi Blog — "Cross-Chain Portfolio Rebalancing: How HTLC and RFQ Swaps Work" — https://blog.ston.fi/cross-chain-portfolio-rebalancing-how-htlc-and-rfq-swaps-work-for-defi-users/
Medium, Motivator Peter — "Omniston SDK: Powering Seamless DeFi on TON with STON.fi" — https://medium.com/@peterifreke/omniston-sdk-powering-seamless-defi-on-ton-with-ston-fi-380f03aa3d0c
Medium, Web3King — "Omniston by STON.fi: Revolutionizing Liquidity Aggregation, pt. 2" — https://medium.com/@web3king/omniston-by-ston-fi-revolutionizing-liquidity-aggregation-on-the-ton-blockchain-pt2-748db5057f6c

This article reflects independent research based on STON.fi's public resolver and protocol documentation as of mid-2026. Resolver participation and protocol mechanics evolve as the network grows — always verify current functionality directly on docs.ston.fi before making decisions involving real funds.

Ecosystem Map: How STON.fi, Omniston, and xStocks Connect on TON

Web3KD — Sat, 15 Aug 2026 17:38:05 +0000

Ecosystem Map: How STON.fi, Omniston, and xStocks Connect on TON

It's easy to see "STON.fi," "Omniston," and "xStocks" mentioned in the same sentence and assume they're three interchangeable names for the same product. They're not — they're three distinct layers of a stack, each solving a different problem, and understanding where one ends and the next begins is the difference between building an integration that actually works and one that quietly breaks the moment a trade routes somewhere you didn't expect. STON.fi is the AMM and the app people actually open. Omniston is the aggregation and execution layer underneath it, connecting multiple liquidity sources — including ones STON.fi doesn't own — through a single interface. xStocks is a real-world-asset product that plugs into that stack without STON.fi ever touching the underlying liquidity itself. This piece maps out how those three pieces actually connect, with the specific technical seams a developer needs to know about.

The Three Layers, in One Sentence Each

STON.fi is the AMM protocol and app: liquidity pools, LP positions, farming, and the interface most users interact with directly.
Omniston is the aggregation and execution layer: it takes a swap request, shops it across STON.fi's own pools, other TON DEXs, and off-chain RFQ resolvers, and returns whichever route quotes best — through either standard on-chain settlement or resolver-driven escrow settlement.
xStocks is a real-world-asset product — tokenized equities and ETFs issued by Backed Finance — that's accessible through STON.fi's interface and Omniston's routing, but doesn't live in a STON.fi-owned liquidity pool at all.

That last point is the one most write-ups gloss over, and it's worth sitting with, because it's the clearest illustration of how these three pieces actually divide responsibility.

Layer One: STON.fi — the AMM and the Front Door

STON.fi is TON's largest native DEX by volume, running a classic AMM model (v1 and v2 contracts, audited by Trail of Bits, with ongoing bug bounty coverage through Certik and HackenProof) where liquidity providers deposit paired assets into pools and earn trading fees plus farming rewards. This is the layer most people mean when they say "I swapped on STON.fi" — the app, the pool pages, the farming dashboard, the LP deposit and withdrawal flows.

Critically, STON.fi's own pools are just one of the liquidity sources available once Omniston is in the picture — not the only one, and, for certain products like xStocks, not involved at all. STON.fi is where you go to provide liquidity and farm; it's not necessarily where your swap's liquidity actually comes from once you hit the swap button.

Layer Two: Omniston — the Routing and Execution Brain

Omniston is a liquidity aggregation protocol purpose-built for TON. Conceptually, it does the same job a DEX aggregator does on Ethereum — shop a trade across multiple sources and route to the best price — but its execution model has grown a second, distinct mode beyond standard on-chain swapping.

Standard aggregated swaps. A user (or an app, via the SDK) sends a swap request to Omniston. Omniston fans that request out as a Request-for-Quote (RFQ) to connected sources — STON.fi's own pools, other TON DEXs, and independent RFQ resolvers — collects competing quotes, and executes against whichever wins. This is the flow covered by useRfq() and useTonBuildSwap() in the Omniston SDK, using a swap-type settlement.

Escrow-based resolver swaps. Later in Omniston's development, a second execution class was introduced: resolver-driven, escrow-based settlement. Instead of routing through an on-chain pool, a professional market maker ("resolver") commits to a specific price, and the trade settles through a hashed-timelock-contract (HTLC) escrow — the trade either completes exactly at the quoted price or the funds return automatically to their original owner. This is the order-type settlement path in the SDK, and it's what lets Omniston access private OTC-style liquidity that no public AMM pool holds at all. It's also the mechanism behind Omniston's native cross-chain swaps: no wrapped tokens, no bridge custody — an HTLC guarantees both sides of a cross-chain trade complete together or not at all.

// Requesting a quote — Omniston decides which settlement type fits
import { useRfq, type QuoteRequest, type SettlementParams } from "@ston-fi/omniston-sdk-react";

const settlementParams: SettlementParams[] = [
  {
    // Standard on-chain AMM routing
    params: { $case: "swap", value: { maxPriceSlippagePips: 10_000 } },
  },
  {
    // Resolver-driven escrow settlement (HTLC-backed)
    params: { $case: "order", value: { flexibleIntegratorFee: true } },
  },
];

const quoteRequest: QuoteRequest = {
  inputAsset: usdtAssetId,
  outputAsset: targetAssetId,
  amount: { $case: "inputUnits", value: amountInBaseUnits },
  settlementParams, // Omniston picks whichever route quotes best across both types
};

Passing both settlement types in the same request is the important detail here: it doesn't commit you to one execution model up front — it tells Omniston "quote me the best of either," and the response tells you which one actually won. For a plain jetton-to-jetton swap on deep, liquid pairs, swap settlement usually wins. For thinner pairs or asset classes with no public pool at all — which is exactly xStocks' situation — order/escrow settlement is often the only route that returns a quote at all.

Layer Three: xStocks — Real-World Assets Riding on Top

xStocks are tokenized U.S. equities and ETFs — AAPLx, TSLAx, NVDAx, GOOGLx, AMZNx, and others — issued by Backed Finance, a regulated third-party entity that holds the underlying real shares and mints a 1:1-backed jetton representing them on TON. Because they follow the standard TON jetton format, any wallet or app that already understands jettons recognizes xStocks automatically, with no custom integration work required just to hold one.

Here's the detail that makes this a genuinely interesting case study rather than "STON.fi added some new tokens": STON.fi's own documentation is explicit that STON.fi does not list xStocks trading pairs and does not operate liquidity pools for xStocks. There is no AAPLx/USDT pool sitting in STON.fi's AMM contracts the way there is for, say, TON/USDT. Users can open the STON.fi app, select an xStock, and swap into it — but that swap is served through Omniston's escrow/resolver settlement path, sourcing price from RFQ resolvers who quote against the real, off-chain equity price, not from an on-chain STON.fi pool at all.

That's the whole architecture in miniature: STON.fi provides the interface a user recognizes, Omniston provides the execution and quote-sourcing plumbing, and xStocks exists as an asset class that only works because Omniston's escrow layer exists — a plain AMM pool model has no good way to price something like a stock that needs to track a live off-chain market and settle atomically against a regulated issuer's commitments.

Tracing One Swap Through All Three Layers

Walking through a concrete example makes the division of labor clearer than describing it abstractly. Say a user opens the STON.fi app and swaps USDT for TSLAx.

STON.fi (interface layer): The user picks USDT and TSLAx in the STON.fi app's swap screen — same UI pattern as any other swap.
Omniston (routing layer): The app sends the swap request to Omniston. Omniston checks its connected sources for a route. Because there's no STON.fi pool or standard DEX pool for TSLAx, standard swap settlement returns no usable quote — so Omniston falls back to querying RFQ resolvers under order/escrow settlement instead.
Resolver quote (execution layer): A resolver — a market maker with access to Backed Finance's issuance/redemption flow and real Tesla-share pricing — returns a firm quote: this much USDT for this much TSLAx, valid for a short window.
HTLC escrow settlement: The user accepts. Funds lock into an HTLC-based escrow. Either the resolver delivers TSLAx at the committed price and the USDT releases to them, or the whole thing reverts and the user's USDT returns automatically — no partial fills, no counterparty risk beyond the smart contract itself.
Wallet delivery: TSLAx lands in the user's wallet as a standard jetton, immediately transferable, usable as collateral elsewhere in TON DeFi, and tradable 24/7 — independent of NYSE trading hours, since it's a resolver-priced synthetic exposure rather than a direct order routed to a traditional exchange.

At no point in that flow does STON.fi's own AMM liquidity get touched — which is exactly why STON.fi's docs are careful to say they don't operate xStocks pools, even though the STON.fi app is where most users will actually encounter and swap xStocks.

Why This Layered Design Actually Matters for Builders

Composability without re-implementation. Because Omniston sits underneath STON.fi rather than being bolted onto it, any third-party app — a wallet, a trading dashboard, a Telegram bot — can integrate the Omniston SDK directly and get access to the same aggregated liquidity, including escrow-settled products like xStocks, without building their own routing logic or negotiating separate resolver relationships.

New asset classes don't require new AMM math. A traditional AMM pool assumes both sides of a pair are freely tradable on-chain assets with organic price discovery through the pool itself. xStocks breaks that assumption — its "correct" price lives off-chain, tied to a real, regulated, KYC'd issuer. Trying to force that into a constant-product pool would either require enormous, unrealistic liquidity or produce constant, exploitable mispricing. Routing it through resolver-quoted escrow settlement sidesteps the problem entirely: the resolver, not a bonding curve, is responsible for pricing accuracy.

Cross-chain and RWA products share the same underlying mechanism. It's not a coincidence that Omniston's HTLC/escrow settlement powers both cross-chain swaps and xStocks — both cases involve one side of a trade that a standard on-chain AMM pool structurally can't represent well: a different chain's native asset in one case, an off-chain regulated security in the other. The same trust-minimized settlement primitive solves both problems.

Honest Limitations Worth Knowing

Resolver dependency is a real, if different, kind of counterparty exposure. HTLC settlement removes bridge-style custodial risk, but a resolver quote is still only as good as that resolver's willingness and ability to fill it — thin resolver participation on an illiquid pair can mean wide effective spreads or outright noQuote responses, the same way thin AMM liquidity produces bad slippage elsewhere.

xStocks carry issuer and regulatory risk that's separate from TON or STON.fi entirely. Because xStocks are backed and issued by Backed Finance under its own prospectus-style documentation, their risk profile includes issuer solvency, custodial arrangements for the underlying shares, and regulatory eligibility restrictions — xStocks are explicitly unavailable to users in the US, EU/EEA, UK, Canada, Australia, and Belgium, which is a meaningfully different constraint than anything native to TON's own token standards.

The escrow/order settlement path is newer and less battle-tested than plain AMM swapping. Standard swap settlement through STON.fi's audited AMM contracts has years of production history behind it; escrow-based resolver settlement is a comparatively recent addition to Omniston's execution model, and integrators should treat it with the same "verify before relying on it heavily" caution they'd apply to any newer piece of financial infrastructure.

Wrapping Up

STON.fi, Omniston, and xStocks aren't three brands for one product — they're a genuine three-layer stack, and the seams between them are exactly where the interesting engineering lives. STON.fi gives users a front door and gives liquidity providers a place to actually earn yield. Omniston is the part doing the real work underneath every swap button, quietly deciding whether a trade should route through an on-chain pool or a resolver-quoted escrow. And xStocks is proof that the escrow layer isn't just a cross-chain trick — it's a general-purpose way to bring assets onto TON that no AMM pool could reasonably price on its own. For a developer building on top of this stack, the practical takeaway is simple: integrate against Omniston if you want access to everything — pools, other DEXs, and resolver-priced assets like xStocks — in one consistent API, rather than assuming STON.fi's own pools are the whole liquidity picture.

🔗 Sources & Further Reading

STON.fi Developer Docs — Introduction: https://docs.ston.fi/
Omniston Protocol Overview: https://docs.ston.fi/developer-section/omniston
Omniston — product site: https://ston.fi/omniston
xStocks on STON.fi — official page and risk disclosures: https://ston.fi/xstocks
STON.fi Blog — "xStocks: Explore Tokenized Market": https://blog.ston.fi/xstocks-explore-tokenized-market/
TON Blog — "xStocks Are Live on TON: Real-World Stocks, Now On-Chain": https://blog.ton.org/x-stocks-are-live-on-ton-real-world-stocks-now-on-chain
DL News — "xStocks arrive on STON.fi, allowing users to access equities the DeFi way": https://www.dlnews.com/external/xstocks-arrive-on-stonfi-allowing-users-to-access-equities-the-defi-way/
top.co Insights — "Omniston and the Next Phase of Liquidity Infrastructure": https://top.co/insights/Omniston-Next-Phase-Liquidity-Infrastructure
Omniston SDK — Node.js Quickstart: https://docs.ston.fi/developer-section/omniston/sdk/nodejs
Omniston SDK — React Quickstart: https://docs.ston.fi/developer-section/omniston/sdk/react
DefiLlama — STON.fi protocol metrics: https://defillama.com/protocol/ston.fi

This article is based on STON.fi, Omniston, and xStocks documentation and public announcements as of mid-2026. Product architecture, supported settlement types, and asset availability by jurisdiction can change — verify current specifics against docs.ston.fi and ston.fi/xstocks before relying on them for a production integration or an investment decision. xStocks are not available to residents of certain jurisdictions and carry issuer, custodial, and regulatory risk separate from TON-native assets.

Testing for Failed Transactions: A Builder's Checklist for STON.fi Integrations

Web3KD — Sat, 15 Aug 2026 16:52:50 +0000

Testing for Failed Transactions: A Builder's Checklist for STON.fi Integrations

Most swap tutorials end at the happy path — quote comes back, user confirms, transaction lands, balance updates. Ship that alone and you've tested maybe 60% of what your integration will actually encounter in production. TON's transaction model is asynchronous and message-based in a way Ethereum developers in particular tend to underestimate: a "failed" swap on TON isn't a single clean revert, it's a cascade of messages that can partially succeed, bounce, get refunded as the wrong token, or silently eat gas without telling anyone why. This checklist is built around the specific ways STON.fi and Omniston integrations actually fail — not hypothetical edge cases, but the documented, reproducible ones — so you can write tests against them before your users find them for you.

"The failure you didn't write a test for isn't rare — it's just the one you haven't hit in staging yet." — a note from the trenches

Why TON Failures Don't Look Like EVM Failures

If your testing instincts come from Solidity, recalibrate them here. On Ethereum, a reverted transaction rolls back cleanly — state changes, gas spent, done. On TON, a "transaction" is really a chain of asynchronous messages between contracts, and each one goes through its own sequence of phases: storage (fees for the space a contract occupies), credit (crediting the incoming message value), compute (running the actual contract logic), action (executing whatever the compute phase decided to do — sending messages, updating state), and bounce (firing only if compute failed and the inbound message had the bounce flag set).

That last phase is the one that trips people up. A bounce isn't a revert — it's a new message sent back to the original sender, and it only happens automatically if the message was sent in bounceable mode with enough remaining balance to cover the bounce itself. If your integration's logic assumes "the transaction either fully succeeds or the user gets their money back exactly as before," you'll eventually hit a case where that's false — because a bounced message can't itself be bounced again, and a bounce triggered by a genuine out-of-gas condition may never get delivered at all.

There's a second wrinkle specific to jetton transfers: if your contract receives a TransferNotification for incoming jettons and that handler throws, bouncing the message is often the worst outcome — the standard jetton wallet contract has no defined behavior for un-bouncing tokens that already moved, meaning a naive bounce-on-error pattern can leave jettons stuck permanently. The fix is a try/catch around notification handling rather than letting an exception propagate into an automatic bounce — a detail that's easy to miss if you copy a generic "throw on invalid input" pattern from EVM-style contract code.

The Failure Taxonomy: What Actually Breaks

1. Slippage-Triggered Refunds

This is the most common "failure" your users will hit, and it's not really a bug — it's the protection working as intended. If the pool's price moves past the max_price_slippage_bps you set before the swap settles, the router refunds the input rather than executing at a worse price than agreed. STON.fi's own Omniston API defaults slippage to a value expressed in basis points — 100 means 1% — and it's worth testing both ends of this deliberately: too tight, and normal volatility triggers refunds constantly; too loose, and you've quietly removed the protection slippage exists for in the first place.

// Test both extremes explicitly, don't just pick one "reasonable" value
const tightSlippage = 10;    // 0.1% — expect frequent refunds on volatile pairs
const looseSlippage = 500;   // 5% — expect rare refunds, worse realized prices

2. Multi-Hop and Cross-Router Swaps Don't Refund Cleanly

If there's no direct pool for your pair, STON.fi routes through an intermediary token — sometimes across multiple routers. Here's the detail worth testing specifically: because multi-contract transactions on TON aren't atomic, a cross-swap that fails partway through can't be fully refunded in the original input token. Per STON.fi's own documentation, if the trade fails after the first hop has already executed, the user receives the intermediate token from that hop, not their original asset back. A test suite that only checks "did the user get token B or token A back" will miss this — you need a third assertion for "did the user get stuck holding the intermediate token instead."

3. Gas Miscalculation and Exit Code 11

Real-world example, pulled from a documented STON.fi SDK issue: a developer's swap transaction was accepted and broadcast successfully, but failed on-chain with exit_code: 11 — a generic compute-phase failure — traced back to a gas/parameter mismatch in how the swap transaction was constructed for a jetton-to-jetton pair specifically (as opposed to the TON-to-jetton path, which worked fine in the same codebase). The lesson generalizes: "the SDK call didn't throw" is not the same as "the swap will succeed." Any integration test suite needs a step that checks the actual on-chain exit code after submission, not just that sendTransaction() resolved without an error.

"I've lost more debugging hours to a transaction that broadcasts cleanly and fails silently on-chain than to any error the SDK actually threw at me." — a note from the trenches

4. TonConnect-Level Rejections (Before the Chain Ever Sees It)

A meaningful share of "failed transactions" never reach a block at all — they fail at the wallet layer. TonConnect's documented failure surface includes a specific, testable set of cases:

An address sent in raw format (0:abc…) where the wallet expected the friendly, bounceable-flag-encoded format
A payload that includes both messages and items in the same request — the spec requires exactly one, never both
valid_until already in the past by the time the wallet receives the request
A network mismatch between what the dApp requested and what the wallet has selected
The user simply rejecting the transaction — which TonConnect's own guidance says should be treated as a "changed their mind" path, shown as a soft message, and explicitly not logged as a system error

That last point matters for your monitoring, not just your tests: if user rejections and genuine on-chain failures land in the same error bucket in your dashboards, you'll chase phantom bugs that are really just people closing the confirmation dialog.

async function handleSwap() {
  try {
    await tonConnectUI.sendTransaction(txRequest);
  } catch (err) {
    if (isUserRejection(err)) {
      setStatus("Transaction cancelled"); // not an error — don't alert on this
      return;
    }
    reportFailure(err); // genuine failure — this one goes to monitoring
  }
}

5. Stale Quotes on the Omniston Side

Because useRfq() is a live subscription, a quote your UI displayed ten seconds ago may no longer be the one Omniston actually settles against if you don't rebuild the transaction from the latest event. Test this by deliberately introducing latency between "user sees a quote" and "user confirms" in your test harness — a few seconds is enough on a volatile pair to demonstrate the gap between a stale UI value and what actually executes.

A Reference Table Worth Keeping Nearby

Exit Code	Meaning	What to Test For
`2`	Stack underflow	Malformed or truncated payload construction
`3`	Stack overflow	Deeply nested or malformed cell structures
`5`	Integer out of expected range	Exit codes or values outside 16-bit bounds
`11`	Generic compute failure (varies by contract)	Gas/parameter mismatches — verify per-path, not just per-SDK-method
`50`	Account state size exceeded	Rare, but test for it if your integration writes custom state
`65535` (`0xffff`)	Unknown opcode	A message the receiving contract wasn't built to handle at all

TON reserves exit codes 0–127 for protocol-level meanings; codes 256–65535 are open for contract-specific errors, which means the same exit code can mean something different depending on which contract threw it — always confirm the meaning against the specific contract's own documentation rather than assuming a code means the same thing everywhere.

Building an Actual Test Matrix

Rather than testing "does a swap work," structure your suite around the failure taxonomy above. A reasonable matrix for a swap feature looks like this:

Happy path — quote, build, sign, settle, balance updates correctly
Slippage refund (tight) — deliberately set slippage low enough on a live-ish sandbox environment to force a refund, confirm the user gets their original input back
Slippage refund (edge) — set slippage to the exact boundary and confirm consistent behavior, not flakiness
Multi-hop partial-fill scenario — simulate a cross-swap failing after the first hop, confirm your UI correctly represents "you received the intermediate token" rather than showing a generic failure
Wallet rejection — simulate the user declining in the wallet UI, confirm it's tracked as a cancellation, not an error
Expired valid_until — construct a transaction with a validity window already in the past, confirm your UI handles the resulting wallet-level rejection gracefully
Stale quote — inject artificial delay between quote display and confirm, verify you're building against the latest quote event, not a cached one
Malformed address format — feed a raw-format address into a sendTransaction call intentionally, confirm your address-formatting layer catches it before it reaches the wallet

// Sandbox-based unit test skeleton for the slippage-refund case
import { Blockchain } from "@ton/sandbox";

describe("swap slippage protection", () => {
  it("refunds input when price moves past max_price_slippage_bps", async () => {
    const blockchain = await Blockchain.create();
    const trader = await blockchain.treasury("trader");

    // Simulate a pool state that has moved since quote issuance
    // ...set up router/pool contracts with adjusted reserves...

    const result = await sendSwap(blockchain, trader, {
      maxPriceSlippageBps: 10, // intentionally tight
    });

    expect(result.refunded).toBe(true);
    expect(result.refundedAsset).toEqual(inputAsset); // not the intermediate token
  });
});

Monitoring After You Ship

Tests catch what you thought to test for. Production catches everything else. A few numbers worth tracking on an ongoing basis once real traffic hits your integration:

Refund rate as a percentage of attempted swaps, segmented by pair — a sudden spike on one specific pair usually means either a liquidity change or your default slippage setting is now too tight for that pair's current volatility
Wallet-rejection rate vs. genuine on-chain failure rate, tracked as separate metrics — conflating them, as noted above, wastes debugging time on a "problem" that's actually users changing their minds
Exit code distribution for any failures that do reach the chain — a new exit code appearing that wasn't in your test matrix is a signal to go add it, not just a data point to log and forget

"A test suite that never grows after launch is testing yesterday's failure modes, not today's." — a note from the trenches

The Checklist, Compressed

[ ] Test slippage refunds at tight, loose, and boundary values — not just one "reasonable" default
[ ] Explicitly test the multi-hop partial-refund case — assert on the intermediate-token outcome, not just success/failure
[ ] Verify on-chain exit codes post-submission, not just that the SDK call resolved
[ ] Handle jetton TransferNotification failures with try/catch, not bounce-on-error
[ ] Separate wallet-rejection tracking from genuine on-chain failure tracking, in both tests and production monitoring
[ ] Test with an intentionally expired valid_until to confirm graceful handling
[ ] Test address-format validation before a request ever reaches TonConnect
[ ] Rebuild transactions from the latest quote event, and test for the stale-quote case directly
[ ] Track refund rate, rejection rate, and exit-code distribution after launch — not just uptime

Wrapping Up

None of the failure modes above are exotic — they're documented, reproducible, and, in at least one case, sitting in a public GitHub issue with the exact exit code attached. What makes them worth a dedicated checklist is that TON's asynchronous, message-based execution model produces failure shapes that don't map cleanly onto EVM-trained intuition: partial fills that land you in the wrong token, bounces that can't be un-bounced, wallet-level rejections that never touch a block at all. Test for the specific way STON.fi and Omniston fail, not just the generic way swaps fail, and the gap between your staging environment and your first angry support ticket gets a lot smaller.

🔗 Sources & Further Reading

TON Docs — Execution Phases: https://docs.ton.org/foundations/phases
TON Docs — Exit Codes: https://docs.ton.org/blockchain-basics/tvm/exit-codes
TON Docs — Accept Message Effects: https://docs.ton.org/v3/documentation/smart-contracts/transaction-fees/accept-message-effects
TON Docs — Internal Messages (bounce mechanics): https://docs.ton.org/blockchain-basics/primitives/messages/internal
TON Docs — TON Connect Troubleshooting: https://docs.ton.org/applications/ton-connect/troubleshooting
CertiK — "Secure Smart Contract Programming in Tact: Popular Mistakes in the TON Ecosystem": https://www.certik.com/blog/secure-smart-contract-programming-in-tact-popular-mistakes-in-the-ton
STON.fi — Swap Examples (v2, cross-swap and refund behavior): https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/swap
STON.fi — Omniston Swap Overview (settlement params, slippage): https://docs.ston.fi/developer-section/omniston/swap/overview
@ston-fi/sdk GitHub Issues (real documented exit-code failures): https://github.com/ston-fi/sdk/issues
@ton/sandbox package: https://www.npmjs.com/package/@ton/sandbox

This checklist is based on TON and STON.fi/Omniston documentation, plus publicly documented integration issues, as of mid-2026. Exit code meanings can vary by contract, and API parameter names/formats evolve — verify specifics against current docs.ton.org and docs.ston.fi before relying on them in a production test suite.

SDK Integration Walkthrough: Building Your First STON.fi Swap Feature

Web3KD — Fri, 14 Aug 2026 13:27:09 +0000

Adding a token swap to a dApp sounds simple until you actually sit down to do it: you need live pricing, a way to route through the best available liquidity, transaction building that matches the target chain's quirks, wallet signing, and a way to track whether the trade actually went through. On TON, STON.fi's SDKs handle most of that heavy lifting for you - specifically the Omniston layer, which aggregates quotes across on-chain pools and off-chain RFQ resolvers and hands you back a ready-to-sign transaction. This walkthrough builds a working swap feature from a blank React project to a working "Swap" button, using the official @ston-fi/omniston-sdk-react package, TonConnect for wallet signing, and the actual API surface exposed by the SDK as of its v1beta8 protocol version.

By the end, you'll have a component that lets a user pick two tokens, see a live quote update as market conditions shift, sign a transaction with their wallet, and watch the swap's status change from pending to confirmed - all without writing a single line of raw smart contract code.

What You'll Need Before Starting

Node.js 18+ and a package manager (npm, yarn, or pnpm)
A React project (Vite or Next.js both work fine - this walkthrough uses a generic React setup so it's easy to adapt)
A TON wallet for testing - Tonkeeper or MyTonWallet both support TonConnect
Basic familiarity with React hooks and async/await - no prior TON or blockchain development experience is required

STON.fi actually ships two related but distinct SDK families: the classic

@ston-fi/sdk,
which talks directly to STON.fi's own Router and Pool contracts, and

@ston-fi/omniston-sdk
(plus its React binding), which talks to Omniston - STON.fi's aggregation layer that shops a trade across multiple liquidity sources, not just STON.fi's own pools, and returns whichever route quotes best. For a new swap feature in 2026, Omniston is the more future-proof choice: it gets you STON.fi's own liquidity and other connected sources through one consistent API, so that's what this walkthrough uses.

Step 1: Install the Dependencies

Start by scaffolding a React project if you don't already have one, then add the Omniston React SDK alongside TonConnect for wallet interaction.

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

@ston-fi/omniston-sdk-react
is a TypeScript-first package built on top of RxJS observables and TanStack Query, so you get loading states, retries, and stream handling out of the box instead of writing that plumbing yourself.

@tonconnect/ui-react
gives you a drop-in wallet connect button and a signer you'll use later to actually authorize the swap transaction.

Step 2: Wire Up Wallet Connection

Before a user can swap anything, they need a connected wallet. TonConnect handles the connection modal, deep-linking into wallet apps, and session persistence for you.

// src/providers/WalletProvider.tsx import { TonConnectUIProvider } from "@tonconnect/ui-react";

const manifestUrl = "https://your-app-domain.com/tonconnect-manifest.json"; export function WalletProvider({ children }: React.PropsWithChildren) { return ( <TonConnectUIProvider manifestUrl={manifestUrl}> {children} </TonConnectUIProvider> ); }

The tonconnect-manifest.json file needs to be hosted at a publicly reachable URL and describes your app's name, icon, and domain to the wallet the user connects with - this is a TonConnect requirement, not a STON.fi-specific one, and most starter templates include a sample manifest you can adapt.
With the provider in place, dropping a connect button anywhere in your UI is a one-liner:

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

function Header() { return ( <header> <TonConnectButton /> </header> ); }

Step 3: Set Up the Omniston Provider

Next, create an Omniston instance and wrap your app (or just the swap feature's subtree) in OmnistonProvider. This gives every component under it access to Omniston's hooks without prop-drilling a client instance around.

// src/providers/OmnistonProvider.tsx import { Omniston, OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const omniston = new Omniston({ apiUrl: "wss://omni-ws.ston.fi", }); export function AppOmnistonProvider({ children }: React.PropsWithChildren) { return <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>; }

While you're building and testing, point at the sandbox endpoint instead so test trades don't touch real liquidity:

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

If your app already has a TanStack Query client set up elsewhere, pass it in so Omniston reuses it instead of spinning up a second one:

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

Nest this provider inside your TonConnectUIProvider from Step 2 - the order doesn't matter functionally, but keeping wallet context outermost tends to make the component tree easier to reason about as the app grows.

Step 4: Define What You're Swapping

Omniston identifies tokens with an AssetId structure rather than a raw contract address string, which keeps the API consistent across chains (TON, EVM chains, and whatever gets added later). For a TON-native jetton swap - say, USDT to STON - that looks like this:

// src/features/swap/assets.ts import type { AssetId } from "@ston-fi/omniston-sdk-react";

export const USDT: AssetId = { chain: { $case: "ton", value: { kind: { $case: "jetton", value: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", }, }, }, }; export const STON: AssetId = { chain: { $case: "ton", value: { kind: { $case: "jetton", value: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", }, }, }, };

In a real app you'd source this list from a token registry or search API rather than hardcoding it, but hardcoding two tokens is the fastest way to get a working prototype before you build out a token picker UI.

Step 5: Request a Live Quote

This is where Omniston's aggregation actually happens. useRfq() opens a subscription - not a one-shot HTTP request - because prices move and Omniston keeps pushing updated quotes as long as you're subscribed. You also need to decide up front which settlement methods you're willing to accept: swap for classic on-chain execution, order for signed-order/HTLC flows (useful for cross-chain trades), or both if you want Omniston to pick whichever is best.

// src/features/swap/useSwapQuote.ts import { useRfq, type QuoteRequest, type SettlementParams, } from "@ston-fi/omniston-sdk-react"; import { USDT, STON } from "./assets";

const settlementParams: SettlementParams[] = [ { params: { $case: "swap", value: { maxPriceSlippagePips: 10_000, // 1% max slippage flexibleIntegratorFee: true, }, }, }, ]; export function useSwapQuote(amountInBaseUnits: string) { const quoteRequest: QuoteRequest = { inputAsset: USDT, outputAsset: STON, amount: { $case: "inputUnits", value: amountInBaseUnits, }, settlementParams, }; return useRfq(quoteRequest); }

And the component that consumes it:

// src/features/swap/QuotePreview.tsx import { useSwapQuote } from "./useSwapQuote";

export function QuotePreview({ amount }: { amount: string }) { const { data: event, error } = useSwapQuote(amount); if (error) { return <p className="error">Couldn't fetch a quote right now.</p>; } switch (event?.$case) { case "ack": return <p>Looking for the best rate…</p>; case "quoteUpdated": return <p>Quote ready - id: {event.value.quoteId}</p>; case "noQuote": return <p>No route available for this pair right now.</p>; case "unsubscribed": return <p>Quote stream closed.</p>; default: return <p>Waiting for quote…</p>; } }

A few things worth flagging here for anyone integrating this for the first time: the maxPriceSlippagePips value is in "pips" (hundredths of a basis point), so 10_000 means 1% - it's easy to be off by an order of magnitude here if you're used to plain percentage inputs, so double-check this value against your UI's slippage setting before shipping. Second, quoteUpdated can fire more than once for the same RFQ - that's the aggregator refreshing the price as the request stays open, not a bug - so store the latest quote in state rather than assuming the first one you see is final.

Step 6: Build the Swap Transaction

Once you have a quote and the user has confirmed they want to proceed, branch on quote.settlementData?.$case to figure out whether you're in a swap flow or an order flow, then call the matching builder. For a straightforward TON-to-TON swap, that's useTonBuildSwap().

// src/features/swap/useBuildSwapTx.ts 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, }); }

Each of those four address fields serves a distinct purpose, and getting them wrong is one of the more common integration mistakes: transferSrcAddress is where the input tokens are pulled from, refundSrcAddress is where funds go if the swap fails partway, gasExcessAddress recovers any unused gas, and traderDstAddress is where the output tokens land. In the common case they're all the same connected wallet address, but keeping them as separate parameters means your app can support more advanced flows later (like swapping on behalf of a smart contract wallet) without changing the API shape.

Step 7: Sign and Send the Transaction with TonConnect

useTonBuildSwap() gives you back a set of unsigned messages - it doesn't sign or broadcast anything itself. That's intentional: signing is wallet territory, and Omniston stays wallet-agnostic. Here's how to hand those messages to TonConnect:

// src/features/swap/SwapButton.tsx 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) return; await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 300, // 5-minute validity window messages: swapTx.messages.map((message) => ({ address: message.address, amount: message.amount, payload: message.payload, })), }); } return ( <button onClick={handleSwap} disabled={!swapTx}> Confirm Swap </button> ); }

The validUntil field matters more than it looks like it should: if you set it too far in the future, a stale transaction can sit in the wallet's queue and eventually execute against a quote that's no longer accurate, potentially at a much worse price than the user agreed to. A five-minute window is a reasonable default for most swap UIs - long enough that a slow wallet app doesn't time out, short enough that market movement doesn't invalidate the trade.

Step 8: Track the Swap's Status

Sending the transaction isn't the end of the story - the user still wants to know whether it actually went through. swapTrack() gives you a live status stream keyed off the quote and the outgoing transaction.

// src/features/swap/useSwapTracking.ts import { useEffect, useState } from "react"; import { useOmniston, type ChainAddress, type Quote } from "@ston-fi/omniston-sdk-react";

export function useSwapTracking( quote: Quote, traderAddress: ChainAddress, outgoingTxQuery: string ) { const omniston = useOmniston(); const [status, setStatus] = useState<string>("pending"); 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 wallet transfer to confirm…"); break; case "progress": setStatus(event.value.status); break; case "unsubscribed": setStatus("Tracking stream closed"); break; } }, }); unsubscribe = () => subscription.unsubscribe(); }); return () => unsubscribe(); }, [omniston, quote.quoteId, traderAddress, outgoingTxQuery]); return status; }

outgoingTxQuery can be a transaction hash, message hash, or the outgoing message body - whichever identifier your wallet integration surfaces most reliably after sendTransaction() resolves. TonConnect's sendTransaction() response includes a boc (bag of cells) you can decode to extract this, though the exact extraction step depends on which TonConnect version and helper library you're using, so it's worth checking the current TonConnect docs for the specific decode helper rather than assuming the API surface hasn't shifted.

Common Pitfalls Worth Knowing Before You Ship

Treating the RFQ stream as a single request. Because useRfq() is a subscription, holding a quote in state and never re-checking it before building the transaction can mean signing against a price that's since moved. Always build the transaction from the latest quote event, not whatever was first received.

Skipping the sandbox environment. It's tempting to point straight at production (wss://omni-ws.ston.fi) while developing, but the sandbox endpoint exists precisely so test trades don't compete for real liquidity or risk real funds during development - use it until your flow is stable.

Assuming every quote is a swap quote. Because Omniston can return either swap or order settlement data depending on route and settlement params, code that only handles useTonBuildSwap() will silently break the moment a quote comes back as an order (which happens more often for cross-chain routes). Always branch on quote.settlementData?.$case rather than assuming one shape.

Ignoring the SDK's pre-1.0 status. As of writing, @ston-fi/omniston-sdk is still under active development with a major version of zero, meaning breaking changes can land in minor releases under semantic versioning conventions. Pin your version explicitly in package.json rather than trusting a caret range, and check the changelog before bumping.

Going From Prototype to Production

A few things worth doing before this ships to real users, beyond what's covered above:

Hardcode fewer addresses. Replace the hardcoded USDT/STON asset IDs from Step 4 with a proper token search or registry integration so users can swap any supported pair, not just the two you picked for testing.

Surface slippage as a user-facing setting, rather than a fixed constant in code - traders on volatile pairs often want to widen or tighten maxPriceSlippagePips themselves.

Handle the noQuote case gracefully in your UI instead of leaving a blank state - it happens for illiquid pairs or when input size exceeds what any connected resolver can fill.

Add error boundaries around the wallet-signing step specifically, since users rejecting a transaction in their wallet app is a normal, expected outcome your UI needs to handle without looking broken.

Wrapping Up

What you've built here - a live quote stream, a build-and-sign flow through TonConnect, and status tracking - is the same core loop every swap feature on TON ultimately needs, whether it's a full DEX front end or a single "swap" button tucked into an unrelated dApp. The heavy lifting Omniston does for you (multi-source routing, quote refreshing, settlement-type branching) is exactly the part that's tedious and error-prone to hand-roll against raw contracts. From here, the natural next steps are wiring in a real token list, adding the order/HTLC flow for cross-chain swaps if your app needs them, and hardening the edge cases called out above before pointing the integration at production.

🔗 Sources & Further Reading

STON.fi Developer Docs - Introduction: https://docs.ston.fi/
Omniston SDK - Node.js Quickstart: https://docs.ston.fi/developer-section/omniston/sdk/nodejs
Omniston SDK - React Quickstart: https://docs.ston.fi/developer-section/omniston/sdk/react
Omniston Protocol Overview: https://docs.ston.fi/developer-section/omniston
@ston-fi/omniston-sdk on npm: https://www.npmjs.com/package/@ston-fi/omniston-sdk
@ston-fi/omniston-sdk-react on npm: https://www.npmjs.com/package/@ston-fi/omniston-sdk-react
@ston-fi/sdk (classic DEX SDK) on npm: https://www.npmjs.com/package/@ston-fi/sdk
STON.fi SDK - GitHub source: https://github.com/ston-fi/sdk
Omniston SDK - GitHub source and example React app: https://github.com/ston-fi/omniston-sdk/tree/main/examples/react-app
Live SDK demo app: https://sdk-demo-app.ston.fi
TonConnect UI React docs: https://docs.tonconnect.io/docs/quick-start/react
TON Core - @ton/ton package installation guide: https://www.npmjs.com/package/@ton/ton

This walkthrough is based on the STON.fi and Omniston SDK documentation as of mid-2026 (protocol version v1beta8). Both the SDK API surface and the underlying protocol are under active development - verify method signatures and package versions against the current docs at docs.ston.fi before shipping to production, and check the official demo app (sdk-demo-app.ston.fi) for a working reference implementation.