Referral fees

This section contains information about referral fees in the Omniston protocol, covering DEX v1, DEX v2, and DeDust flow.

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 Protocol Fees Introduction.

---

Specifying Referral Parameters

When you request a quote you can attach referral data so that a share of the swap fee is redirected to your address.

Parameter	Description
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

{
  "referrer_address": {
    "blockchain": 607,
    "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
  },
  "referrer_fee_bps": 10
}

Implementation‑specific details are in:

• Node.js SDK

• React SDK

• gRPC

• WebSocket

---

Referral Fees with DEX v1

Characteristic	Details
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.

---

Referral Fees with DEX v2

1 · How fees are accumulated

• 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).

2 · Withdrawing your fees

You have two options:

Method	When to use
UI	Quick manual withdraws – open the Vault UI and paste the pool address into the Pool address: field
SDK / code	Automated dashboards, integrations, or batch claiming

For a fully-working reference open the Vault withdrawal demo inside our SDK mono-repo:

https://github.com/ston-fi/sdk/tree/main/examples/next-js-app/app/vault

How it works in practice

• 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:

  1. the pool address used for the swap, and

  2. 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).

---

Referral Fees with DeDust

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.

1 · Find your personal vault

Each jetton has its own vault contract. To find your vault address for a specific jetton:

1. Create the minter's jetton-wallet address Every Fee-Vault Minter owns a regular jetton wallet. Retrieve it once via jettonMinter.getWalletAddress(minter.address).

2. Query your personal vault by calling minter.getVaultAddress({ owner: <your_wallet>, jettonWallet: <minter_jetton_wallet> }).

// --- TypeScript example ------------------------------------------------------
const minterAddress = "EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye";
const minter = provider.open(
  Minter.createFromAddress(minterAddress),
); 

const jetton = "USDT_jetton_master_address";
const senderAddress = "your_wallet_address";

const jettonMinter = provider.open(
  JettonMinterContract.createFromAddress(jetton),
);
const minterWalletAddress = await jettonMinter.getWalletAddress(minter.address);

const vaultAddress = await minter.getVaultAddress({
  owner: senderAddress,
  jettonWallet: minterWalletAddress,
});

// Need more than just the address? Query on-chain data with getVaultData():
const vault = provider.open(VaultContract.createFromAddress(vaultAddress));
const vaultData = await vault.getVaultData();
// vaultData.balance, vaultData.lastCollectTime, …

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.

2 · Collect the fees

1. Send an internal message to your vault calling collectFees() (no payload) with about 0.3 TON attached for gas.

2. The vault immediately transfers the accumulated fee-tokens to your wallet and resets its balance.

3. 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:

Step	Contract	Method	Purpose
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

---

Summary

Protocol	Fee mechanism	Range	How to receive funds
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()

Stats & Vaults API Endpoints

In addition to on-chain reading or direct contract calls, you can track and manage referral fees using our REST API. These endpoints are available for both v1 and v2. (They are not related to DeDust—only Ston.fi DEX v1 and v2.) In v1, there are no fee vaults, but all referral fee accruals will still appear in the listed endpoints:

• GET /v1/wallets/{addr_str}/fee_vaults Lists all known vaults per referrer (not supported in v1).

• GET /v1/stats/fee_accruals Shows all operations leading to fee accrual for the referrer, filterable by time period.

• GET /v1/stats/fee_withdrawals Shows all withdrawals from the referrer's vaults, filterable by time period.

• GET /v1/stats/fees Returns aggregated referral fee metrics (like total accrued USD value) by time period.

• Swagger UI Access the interactive API documentation at https://api.ston.fi/swagger-ui/#/.

---

Additional Resources

• Omniston Quick‑start
• Glossary
• Contact Support