LogoLogo
ston-fi/docs
ston-fi/docs
  • User section
    • About
    • STON.fi Protocol
    • Fees
    • Glossary
    • Procedure for Adding Tokens to the Default List
    • Whitepaper
  • Developer section
    • Architecture
    • SDK
      • DEX v1 guide
        • reference
        • swap
        • provide liquidity
        • refund liquidity
        • burn liquidity tokens
      • DEX v2 guide
        • swap
        • provide liquidity
        • refund liquidity
        • burn liquidity tokens
        • withdraw fee from vault
      • Farm guide
        • stake in farm
        • claim farm rewards
        • unstake from farm
        • destroy farm NFT
      • Transaction sending guide
        • via ton
        • via tonweb
        • via tonconnect
      • v0.5 > v1.0.0 migration guide
      • v0.5 (deprecated)
        • DEX guide
          • swap
          • provide liquidity
          • refund liquidity
          • burn liquidity tokens
        • Farm guide
          • stake in farm
          • claim farm rewards
          • unstake from farm
          • destroy farm NFT
        • Transaction sending guide
          • via ton
          • via tonweb
          • via tonconnect
      • v0.4 > v0.5 migration guide
      • v0.4 (deprecated)
        • perform a swap operation
        • provide liquidity
        • refund liquidity
        • burn liquidity tokens
        • using get methods
        • create a custom router revision
    • API reference v1
      • Router
      • Pool
      • LpAccount
      • LpWallet
    • API reference v2
      • Router
      • Pool
      • LpAccount
      • LpWallet
      • Vault
      • Swap examples
      • LpProvide examples
      • Vault examples
      • Op Codes
    • DEX API
    • OMNISTON
      • Resolvers (How to become a resolver)
      • Swap overview
      • Swap extra
      • Swap grpc
      • React
      • Nodejs
      • Referral fees
    • Quickstart Guides
      • Swap Guide
      • Omniston Guide
  • Help
    • Contact Us
Powered by GitBook
On this page
  • Specifying Referral Parameters
  • Referral Fees with DEX v1
  • Referral Fees with DEX v2
  • 1 · How fees are accumulated
  • 2 · Withdrawing your fees
  • How it works in practice
  • Referral Fees with DeDust
  • 1 · Find your personal vault
  • 2 · Collect the fees
  • Summary
  • Stats & Vaults API Endpoints
  • Additional Resources
Export as PDF
  1. Developer section
  2. OMNISTON

Referral fees

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

PreviousNodejsNextQuickstart Guides

Last updated 5 days ago

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 .


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

You have two options:

Method
When to use

UI

SDK / code

Automated dashboards, integrations, or batch claiming

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

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.


Additional Resources

Quick manual withdraws – open the and paste the pool address into the Pool address: field

Swagger UI Access the interactive API documentation at .

https://github.com/ston-fi/sdk/tree/main/examples/next-js-app/app/vault
https://api.ston.fi/swagger-ui/#/
Omniston Quick‑start
Glossary
Contact Support
Vault UI
Protocol Fees Introduction
gRPC
React SDK
WebSocket
Node.js SDK