How Do Referral Fees Affect an Omniston Widget Quote?
STON.fi / Omniston integration guide • Updated September 14, 2026
Referral fees in the STON.fi Omniston Widget are more than a payout setting for the integrator. Once a referral fee is configured, it becomes part of the request for quote itself — which means the quote shown to the user is calculated with that fee already included in the trade economics.
That distinction matters more than it might first appear. The fee is not simply added after Omniston finds a price, and it is not a hidden surcharge applied once the user accepts a quote. Omniston receives the referral parameters together with the RFQ, resolvers compete under those conditions, and the resulting quote describes what the trader pays and receives after the relevant fees have already been incorporated into the calculation.
For anyone embedding the Widget, the practical consequence is direct: changing the referral fee can change the displayed rate, the amount received, the amount required for an exact-output trade, and — in some cases — even which liquidity routes remain competitive or available at all.
💭 The mental model that causes the most confusion here is treating a referral fee like a service charge stapled onto an invoice after the total is calculated. It isn't. It's closer to a constraint handed to the pricing engine before it starts searching — which is why the effect isn't always a clean subtraction.
⚙️ How the Widget Passes a Referral Fee Into Omniston
The public Widget configuration exposes two referral-related fields:
-
referrerAddress— the TON wallet address that receives the integrator fee. -
referrerFeeBps— the requested fee in basis points, where 1 basis point equals 0.01%.
The documented programmatic range is 1 to 100 bps, or 0.01% to 1%. A value of 50 therefore means a 0.5% referral fee.
In practice, configuring this looks like:
const widget = new OmnistonWidget({
tonconnect: {
type: 'standalone',
options: {
manifestUrl: 'https://your-app.example/tonconnect-manifest.json',
},
},
widget: {
referrerAddress: 'EQB_yourReferralWallet...',
referrerFeeBps: 50, // 0.5%
},
});
At the Omniston protocol level, the same idea surfaces in quote requests as referrer_address and referrer_fee_bps. Because these values are submitted as part of the RFQ, the resolver is never quoting a fee-free trade and then attaching an integrator charge afterward. It is quoting the trade under the requested fee conditions from the very start of the pricing process.
Key idea: a referral fee is part of the RFQ itself. The quote the user sees is therefore already calculated under that fee configuration, rather than receiving an extra referral deduction after pricing.
🔍 The Quote the User Sees Is Already Fee-Aware
Omniston's swap documentation defines these two fields precisely:
| Field | Definition |
|---|---|
bid_units |
The amount of the bid asset the trader must pay, including all fees |
ask_units |
The amount of the ask asset the trader receives, after all fees |
The quote also contains dedicated referral-fee fields, including the referral fee amount and the fee asset it's denominated in.
This is the single most important concept for understanding the Widget's numbers. If a referral fee is active, the displayed exchange outcome should be treated as a net quote — not as a raw market price still awaiting an additional referral deduction.
In practice, that means the user should evaluate the quote exactly as displayed: how much is being spent, how much is being received, and what route is being offered. The integrator fee is already baked into the conditions that produced those numbers, which is precisely why there's no "hidden charge" moment later in the flow.
↔️ What Changes for Exact-Input and Exact-Output Trades
Omniston can quote with either the input side or the output side fixed. Referral fees affect these two directions differently from the user's perspective, and the difference is worth understanding separately rather than assuming symmetry.
Exact input: the user fixes how much to spend
If the user wants to swap a fixed amount of the bid asset, that bid amount represents the total amount paid, including fees. Omniston then competes to maximize the ask amount the user receives under those conditions.
With a higher referral fee, the resulting output may become less favorable compared with an otherwise identical fee-free request. However — and this is the part that surprises integrators — the difference is not guaranteed to equal the referral percentage exactly. A new RFQ can surface a different resolver, a different pool, a different split route, or a different effective market price altogether.
Exact output: the user fixes how much to receive
If the user requests a fixed ask amount, that target represents what the trader wants to receive after fees. The quote therefore has to work backward to determine how much input is required to satisfy that net output.
In this direction, increasing the referral fee tends to show up as a higher required bid amount rather than a lower displayed ask amount. Again, the result is route-dependent: the fee changes the economic constraints of the quote, and Omniston searches for the best available deal under those revised constraints.
📐 Why a 0.5% Fee Doesn't Always Make a Quote Exactly 0.5% Worse
It's tempting to assume a 50 bps referral fee should mechanically make every quote 0.5% worse. That is not how an aggregator behaves.
The referral rate is one component of the RFQ, but the final quote also depends on liquidity depth, pool fees, price impact, resolver competition, route composition, and which protocols can actually support the requested referral configuration. When the referral fee changes, Omniston can effectively be solving a different routing problem — not the same problem with a percentage shaved off the end.
Consider two requests with the same token pair and trade size:
| Request | Referral fee | What Omniston evaluates |
|---|---|---|
| A | 0 bps | Best available quote without integrator referral revenue |
| B | 50 bps | Best available quote that can satisfy a 0.5% referral fee |
The second quote may use the same route with slightly different net economics, or it may select an entirely different route. Therefore, the cleanest way to measure the real user cost of a referral setting is to compare live quotes using the same pair, direction, amount, and market conditions — rather than subtracting the fee percentage from a theoretical spot price and calling it the answer.
🚧 Referral Fees Can Affect Route Eligibility
The effect becomes especially visible when comparing STON.fi DEX versions. According to the current Omniston referral-fee documentation:
- DEX v1 has a fixed maximum referral fee of 0.1% (10 bps)
- DEX v2, DeDust, Tonco, CoffeeSwap, and Escrow can support configurable referral fees from 0.01% to 1%
Suppose an integrator requests a 30 bps fee. A DEX v1 pool simply cannot satisfy that fee as requested. At the protocol level, a strict 30 bps request can therefore prevent a v1 route from being used at all — even if that pool would otherwise offer the strongest underlying price for the trade.
Omniston provides a lower-level flexible_referrer_fee settlement option for exactly this situation. When enabled, the protocol may reduce the effective referral fee when doing so unlocks a better route for the trader. The documentation gives the concrete example of reducing a 30 bps request down to the 10 bps maximum supported by DEX v1, if that produces a better overall swap rate.
One important detail for Widget integrators: the current public Widget configuration table documents referrerAddress and referrerFeeBps, but it does not list flexible_referrer_fee as a Widget configuration field. Developers who need explicit control over that settlement behavior should consult the lower-level Omniston SDK or API documentation rather than assuming the Widget exposes the same parameter.
🏦 The Payout Mechanism Doesn't Change What the Quote Means
Where the integrator eventually receives the fee depends on the route — but this settlement detail should not be confused with quote calculation itself.
| Route | How the referral fee is paid |
|---|---|
| STON.fi DEX v1 | Paid on-chain within the same swap transaction |
| STON.fi DEX v2 | Accumulates in a dedicated vault, claimed later |
| DeDust, Tonco, CoffeeSwap | Separate fee-vault mechanism for jetton-denominated fees; TON-denominated fees credited directly during the swap |
| Escrow | Uses its own fee-vault contracts |
These differences matter operationally for the integrator — they affect cash-flow timing and claiming workflows. But the user's quote remains fee-aware regardless. A fee being stored in a vault rather than transferred immediately does not mean it sits outside the quoted trade economics.
📊 What an Integrator Should Monitor
Referral revenue is attractive because it lets a product monetize swap flow without building its own execution layer. But the fee level is also a product decision — it changes the economic conditions presented to your users.
A practical monitoring framework tracks several things together:
- Net ask amount for exact-input trades. Compare what users actually receive at different referral settings.
- Required bid amount for exact-output trades. Measure how much additional input is needed to preserve the same target output.
- Route and protocol mix. Watch whether higher fees quietly reduce the use of routes that would otherwise be competitive.
- Quote competitiveness. Compare your Widget's net quote against a zero-fee or lower-fee control under similar market conditions.
- Conversion behavior. A higher fee can increase revenue per completed swap while potentially reducing completion rate if users notice worse pricing.
The optimal fee is therefore not automatically the maximum 100 bps. The best setting depends on the balance between monetization and execution quality for the specific audience using your Widget.
🧪 A Simple Way to Test Impact Before Choosing a Fee
Before publishing a referral setting, run repeated quote comparisons across the token pairs and trade sizes that actually matter to your users.
For each test case, request or observe the same trade at several fee levels — for example 0, 10, 30, and 50 bps — and record the final bid and ask amounts. Repeat the comparison over time, because routing and liquidity conditions change independently of your configuration.
Do not judge the result only by the referral percentage. What matters is the net difference in the actual quote. A 30 bps fee that leaves route quality almost unchanged may be far less noticeable to users than a smaller fee that happens to exclude a particularly efficient route for a specific pair.
If you're working with the lower-level Omniston SDK or API, also test the flexible-referrer-fee behavior whenever your requested rate exceeds 10 bps. That can reveal whether accepting a smaller fee on some trades improves execution enough to increase swap completion — and, counterintuitively, total referral revenue.
🎯 Final Takeaway
Referral fees in the Omniston Widget are part of quote formation, not an afterthought added after pricing. The configured referrerFeeBps becomes part of the RFQ, and Omniston returns a fee-aware result in which the trader's input is defined including fees and the expected output is defined after fees.
For an exact-input trade, a referral fee can reduce the net amount received. For an exact-output trade, it can increase the amount the trader needs to spend. More importantly, the fee can change routing itself — so the difference between two quotes is rarely a simple percentage calculation.
That is why referral-fee optimization should be treated as an execution-quality problem as much as a monetization problem. The right question isn't only, "How much can the integrator earn per swap?" It's also, "What net quote does the user actually receive once Omniston has re-optimized the trade under that fee?"
❓ Frequently Asked Questions
Does the user see the referral fee as a separate line item?
Not as an additional deduction applied after pricing. The quote's bid_units already includes all fees and ask_units already reflects the amount received after fees — though the quote does contain dedicated referral-fee fields describing the fee amount and asset.
Why did raising my fee by 20 bps change the output by more (or less) than 20 bps?
Because the referral fee is a constraint inside the RFQ, not a post-pricing subtraction. A different fee can lead Omniston to select a different resolver, pool, or split route entirely — so the net difference reflects a re-optimized trade, not just the arithmetic.
Can a referral fee make a route unavailable?
Yes. DEX v1 supports a maximum of 10 bps, so a strict request above that can exclude v1 routes even when they'd otherwise offer the best underlying price. The lower-level flexible_referrer_fee option exists to let the protocol reduce the fee when doing so unlocks a better route.
Is the maximum 100 bps fee the best choice for revenue?
Not necessarily. Higher fees increase revenue per completed swap but can worsen displayed pricing and reduce completion rate. Testing across realistic pairs and trade sizes is the only reliable way to find the balance for your specific audience.
📚 Sources and References
- STON.fi — Full Guide & Reference for the Omniston Widget: https://docs.ston.fi/developer-section/widget/widget
- STON.fi — Omniston Referral Fees: https://docs.ston.fi/developer-section/omniston/referral-fees
- STON.fi — Omniston Swap Overview / Quote Fields: https://docs.ston.fi/developer-section/omniston/swap/overview
- STON.fi — Omniston Widget GitHub Repository: https://github.com/ston-fi/omniston-widget
Tags: STON.fi, Omniston, Referral Fees, Widget Integration, RFQ, Quote Formation, TON Blockchain, DeFi Development
Top comments (0)