Referral fees

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

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

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:

  1. Go to the vault interface by visiting the following link: https://sdk-demo-app.ston.fi/vault

  2. Connect your wallet to the site.

  3. Once connected, the interface will display all available referral fees you can claim.

  4. Find the fee you'd like to claim and click the "Claim" button.

  5. A transaction will be sent to your wallet — confirm it.

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

  1. Find your personal vault using the same methods described in the DeDust section

  2. Collect fees by sending a message to your vault with collectFees()

  3. 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: With the latest Omniston release, we have deployed a new Fee-Vault Minter contract at EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL. New fees will be directed to this new contract. Users can claim fees from both the old contract (EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye) 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:

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

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

PreviousNodejsNextContact Us

Last updated