Referral fees
This section contains information about referral fees in the Omniston protocol, covering DEX v1, DEX v2, and DeDust flow.
Last updated
This section contains information about referral fees in the Omniston protocol, covering DEX v1, DEX v2, and DeDust flow.
Last updated
This guide explains how referral fees are applied in the Omniston liquidity‑aggregation protocol when trades route through DEX v1, DEX v2, or DeDust. For general Ston.fi protocol fees, see .
When you request a quote you can attach referral data so that a share of the swap fee is redirected to your address.
referrer_address
TON address that receives the referral fee
referrer_fee_bps
Fee rate in basis‑points (1 bps = 0.01 %)
Example JSON in a quote request
Implementation‑specific details are in:
Fee rate
Fixed 0.1 % (10 bps) enforced by the pool contract
Settlement
Paid on‑chain in the same swap tx to referrer_address
Nothing else is required—fees arrive automatically.
Fee rate is configurable from 0.01 % to 1 % per swap.
Instead of being paid instantly, fees are deposited into a Vault (one vault per token × referral‑address pair).
You have two options:
UI
SDK / code
Automated dashboards, integrations, or batch claiming
For a fully-working reference open the Vault withdrawal demo inside our SDK mono-repo:
Suppose a trader swaps A → B and a referral fee is specified.
During that swap the Router deploys (or re-uses) a Vault whose address is derived deterministically from the pool address and the router address.
To locate the vault later you therefore need two pieces of data:
the pool address used for the swap, and
the router address (each pool stores a pointer to the router that served it).
With those addresses in hand, instantiate a Router
from the SDK and call the helper (e.g. withdrawFees()
) to collect the accumulated tokens via TonConnect or any preferred wallet integration.
The linked example shows this discover → instantiate → withdraw flow end-to-end, including robust TypeScript patterns and TonConnect wiring.
Note For TON-denominated fees in DEX v2, the
tokenMinter
is the pTON master address (ptonMasterAddress
).
For DeDust swaps, we implement our own referral fee mechanism through a stand-alone Fee-Vault Minter contract. This flow bypasses the Router used in Ston.fi DEX v2, so the existing SDK helpers cannot be used—you must call the contract methods directly on-chain.
Each jetton has its own vault contract. To find your vault address for a specific jetton:
Create the minter's jetton-wallet address
Every Fee-Vault Minter owns a regular jetton wallet.
Retrieve it once via jettonMinter.getWalletAddress(minter.address)
.
Query your personal vault by calling
minter.getVaultAddress({ owner: <your_wallet>, jettonWallet: <minter_jetton_wallet> })
.
The getter returns:
0:0
– no fees accrued yet for this jetton
vault address – your dedicated Fee-Vault contract for this jetton
Vault addresses are derived deterministically based on both the referrer address and jetton address.
Send an internal message to your vault calling collectFees()
(no payload) with about 0.3 TON attached for gas.
The vault immediately transfers the accumulated fee-tokens to your wallet and resets its balance.
For TON fees, they are credited instantly to the referrer address during the swap transaction.
The complete flow consists of two or three on-chain calls:
Read
Fee-Vault Minter
getVaultAddress(user, jetton)
Get your vault address
Read (optional)
Your Fee-Vault
getVaultData()
Check balance before collecting
Write
Your Fee-Vault
collectFees()
Transfer accumulated fees to your wallet
DEX v1
Direct payment inside the swap tx
0.1 %
Automatic
DEX v2
Fees accrue in a vault (token × referrer)
0.01 – 1 %
UI or code withdrawal
DeDust
Token-aware vaults (one per jetton)
0.01 – 1 %
TON: instant, Jettons: getVaultAddress
→ collectFees()
Quick manual withdraws – open the and paste the pool address into the Pool address: field