Referral Fees

Omniston referral fees guide - earn commissions from DEX v1, v2, DeDust, and Tonco swap volumes

This guide explains how referral fees are applied in the Omniston liquidity‑aggregation protocol when trades route through DEX v1, DEX v2, DeDust, or Tonco.

Quick start: Looking for code examples? Jump to Platform-specific implementation guides for SDK and API integration samples.

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.

Top-level referral parameters

Parameter

Description

referrer_address

TON address that receives the referral fee

referrer_fee_bps

Fee rate in basis‑points (1 bps = 0.01 %)

Settlement parameters

Parameter

Description

flexible_referrer_fee

Boolean flag (inside settlementParams) allowing resolvers to lower the effective referrer fee when it yields a better swap rate. Defaults to false. See Flexible Referrer Fee for details.

Example JSON in a quote request

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

Platform-specific implementation guides

For detailed implementation examples and code samples:

Node.js SDK - TypeScript/JavaScript integration with referral parameters
React SDK - React hooks and components for referral tracking
gRPC API - Direct gRPC integration for custom implementations
WebSocket API - Real-time quote streaming with referral support

Flexible Referrer Fee

The flexible_referrer_fee parameter (part of settlementParams / RequestSettlementParams) allows the Omniston protocol to automatically adjust your referral fee downward when doing so would provide a better swap rate for the user.

Why this feature exists

This feature was designed to solve a specific compatibility issue between different DEX versions:

DEX v1 has a fixed maximum referral fee of 0.1% (10 bps) enforced by the pool contract
DEX v2, DeDust, and Tonco support configurable fees from 0.01% to 1%

The problem: Suppose you set a referral fee of 0.3% (30 bps) in your quote request. If the best swap rate happens to be through a DEX v1 pool, that route would normally be excluded because v1 cannot support a 0.3% referral fee. This forces the protocol to use a suboptimal route through v2, DeDust, or Tonco—even if the v1 pool offers a significantly better rate for the user.

The solution: When you enable flexible_referrer_fee: true, the protocol can automatically reduce your referral fee from 0.3% to 0.1% when routing through v1 pools. This allows the user to benefit from the best available rate while you still earn the maximum referral fee that v1 supports.

Usage guidelines

Defaults to false—you must explicitly enable it
Only affects routes where a lower fee would unlock a better rate
Your referral fee will never be increased, only decreased when beneficial
Most useful when setting referral fees above 0.1% (10 bps)

Example scenario:

{
  "referrer_address": { "blockchain": 607, "address": "EQC..." },
  "referrer_fee_bps": 30,
  "settlement_params": {
    "flexible_referrer_fee": true
  }
}

With this configuration:

If the best rate is through v2/DeDust/Tonco: you receive the full 0.3%
If the best rate is through v1: your fee is automatically reduced to 0.1%, but the user gets a better swap rate

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

DEX v2 referral fees are stored in a special vault and must be claimed manually.

To claim your fees:

Go to the vault interface by visiting the following link: https://sdk-demo-app.ston.fi/vault
Connect your wallet to the site.
Once connected, the interface will display all available referral fees you can claim.
Find the fee you'd like to claim and click the "Claim" button.
A transaction will be sent to your wallet — confirm it.
After confirmation, the claimed referral fees will appear in your wallet.

For automated withdrawals via SDK/code:

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.
The API can automatically discover all your vaults using the /v1/wallets/{addr_str}/fee_vaults endpoint, eliminating the need to manually track pool addresses.
With the vault addresses retrieved, 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 Tonco

For Tonco swaps, we use the same referral fee mechanism as DeDust through the stand-alone Fee-Vault Minter contract. The flow is identical to DeDust:

Find your personal vault using the same methods described in the DeDust section
Collect fees by sending a message to your vault with collectFees()
TON fees are credited instantly, while jetton fees accumulate in your vault

Refer to the DeDust section below for detailed implementation instructions.

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.

Important Update: We have deployed a new Fee-Vault Minter contract at EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH. New fees will be directed to this new contract. Users can claim fees from previous contracts (EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye and EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL) and the new contract.

1 · Find your personal vault

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

// --- TypeScript example ------------------------------------------------------
// Old minters (for claiming existing fees):
// - EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye
// - EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL
// New minter (for new fees): EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH
const minterAddress = "EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH";
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

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:

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()

Tonco

Token-aware vaults (same flow as DeDust)

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

Implementation guides:

Other resources:

PreviousHow to Become a Resolver NextCommon Utilities

Last updated 10 days ago