> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/migration/fee-payouts.md).

# TON payout contract reference

Deployment-specific TON fee-Vault and escrow collection recipes for existing accrued payouts.

Collect accrued TON fees from external liquidity-protocol minters and escrow Vaults. Use [Integrator fees](https://docs.ston.fi/developer-section/omniston/referral-fees.md) to configure the fee when requesting a quote.

## External TON liquidity-protocol minters

For DeDust, TONCO, and CoffeeSwap swaps, Omniston uses a shared referral fee mechanism through **stand-alone Fee-Vault Minter contracts**. 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.

CoffeeSwap DEX is supported in Omniston referral fee accruals alongside DeDust and TONCO. Referral fees from CoffeeSwap routes use the same Fee-Vault Minter flow described below: jetton-denominated fees are accumulated in token-aware vaults and must be claimed on-chain, while TON-denominated fees are credited directly during the swap transaction.

### Fee-Vault Minter addresses

Referral fees for these routes are collected through **Fee-Vault Minter contracts**. Use the minter associated with the fee accrual transaction.

New referral fees are directed to the current minter listed below. Older minters are only needed for claiming fees accrued before their respective migrations.

**Fee-Vault Minter**

`EQDybO88l2lrrAmALRUqpmgEE_tuxk510F4Yd4xjbQZxC9IA`

**Previous Fee-Vault Minters**

Use these only to claim fees accrued before the migration:

* `EQDw5eLrxLnkFmw2QfSayJcjQ4kP2KdW42Sc3gSiCKhay5Jh`
* `EQCcJf2KFlH9xIx3dztytxxRFk3KQZKEYBr-f0nFIO1h3dvv`
* `EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH`
* `EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye`
* `EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL`

> **Important:** Older Fee-Vault Minters remain available only for claiming fees accrued before the migration.

> **Implementation Note:** The code examples below demonstrate **on-chain contract calls** using the TON blockchain. These are **not part of the STON.fi SDK**. To use them, you need:
>
> 1. **TON development environment** - Use [Blueprint](https://github.com/ton-org/blueprint) framework with `@ton/core` and `@ton/ton` packages
> 2. **Contract wrappers** - You must implement wrapper classes (`FeeVaultMinter`, `FeeVaultContract`) for the fee vault contracts. For `JettonMaster`, you can use the one from `@ton/ton`
> 3. **RPC access** - A TON RPC provider like [toncenter.com](https://toncenter.com) for blockchain queries
>
> If you prefer not to write contract wrappers, see the [Low-level RPC approach](#low-level-rpc-approach) section below.

### 1 · Find your personal vault

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

1. **Get the Fee-Vault Minter's jetton wallet address** Every **Fee-Vault Minter** owns a *regular jetton wallet*. Retrieve it via `jettonMaster.getWalletAddress(feeVaultMinter.address)`.
2. **Query your personal vault** by calling `feeVaultMinter.getVaultAddress({ owner: <your_wallet>, jettonWallet: <feeVaultMinterWallet> })`.

```ts
// --- TypeScript example ------------------------------------------------------
import { Address } from '@ton/core';
import { JettonMaster } from '@ton/ton';
// FeeVaultMinter, FeeVaultContract are custom wrappers you must implement

// Documented Fee-Vault Minter for this recipe.
// See "Fee-Vault Minter addresses" above for older minters that can still
// be used to claim existing fees.
const feeVaultMinterAddress = Address.parse("EQDybO88l2lrrAmALRUqpmgEE_tuxk510F4Yd4xjbQZxC9IA");
const feeVaultMinter = provider.open(
  FeeVaultMinter.createFromAddress(feeVaultMinterAddress),
);

const jettonMasterAddress = Address.parse("USDT_jetton_master_address");
const ownerAddress = Address.parse("your_wallet_address"); // owner receiving the accrued TON payout

// JettonMaster from @ton/ton (sometimes called "Jetton Minter")
const jettonMaster = provider.open(JettonMaster.create(jettonMasterAddress));
const feeVaultMinterWallet = await jettonMaster.getWalletAddress(feeVaultMinter.address);

const vaultAddress = await feeVaultMinter.getVaultAddress({
  owner: ownerAddress,
  jettonWallet: feeVaultMinterWallet,
});

// Need more than just the address? Query on-chain data with getVaultData():
const vault = provider.open(FeeVaultContract.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 |

### Low-level RPC Approach

If you don't want to set up Blueprint or write contract wrappers, you can query vault data directly using RPC calls to any TON API provider (e.g., [toncenter.com](https://toncenter.com)).

> **Slice encoding:** Stack items of type `tvm.Slice` must be base64-encoded BOC (bag of cells). To convert an address to a slice:
>
> ```ts
> import { beginCell, Address } from '@ton/core';
> const addr = Address.parse("EQ...");
> const sliceBoc = beginCell().storeAddress(addr).endCell().toBoc().toString('base64');
> ```

**Step 1: Get the Fee-Vault Minter's jetton wallet address**

Call `get_wallet_address` on the Jetton Master contract:

```bash
curl -X POST "https://toncenter.com/api/v2/runGetMethod" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "<JETTON_MASTER_ADDRESS>",
    "method": "get_wallet_address",
    "stack": [["tvm.Slice", "<FEE_VAULT_MINTER_ADDRESS_AS_SLICE_BOC>"]]
  }'
```

**Step 2: Get your vault address**

Call `get_vault_address` on the Fee-Vault Minter:

```bash
curl -X POST "https://toncenter.com/api/v2/runGetMethod" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "<FEE_VAULT_MINTER_ADDRESS>",
    "method": "get_vault_address",
    "stack": [
      ["tvm.Slice", "<YOUR_WALLET_ADDRESS_AS_SLICE_BOC>"],
      ["tvm.Slice", "<FEE_VAULT_MINTER_WALLET_AS_SLICE_BOC>"]
    ]
  }'
```

**Step 3: Query vault data**

Call `get_vault_data` on your vault:

```bash
curl -X POST "https://toncenter.com/api/v2/runGetMethod" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "<YOUR_VAULT_ADDRESS>",
    "method": "get_vault_data",
    "stack": []
  }'
```

The response contains cells that encode: owner address, jetton wallet address, balance, and minter address.

> **Tip:** You can view vault data directly on [tonviewer.com](https://tonviewer.com) by navigating to your vault address and clicking "Methods" to run `get_vault_data`.

### Verifying Your Vault Address

To confirm your vault address is correct:

1. **Compute the vault address** using the code example above
2. **Open your swap transaction** on [tonviewer.com](https://tonviewer.com) and expand the transaction trace
3. **Find the vault address** in the trace - it should match the address computed from your code
4. **Navigate to your vault** on tonviewer: `https://tonviewer.com/<vault_address>?section=method`
5. **Run `get_vault_data`** - this returns the same data structure as `vault.getVaultData()` in the code example:
   * Owner address (your referrer address)
   * Jetton wallet address
   * Balance (accumulated fees)
   * Minter address

If the data matches your expected values, your vault address derivation is correct.

> **API status** At the moment, Omniston does not expose DeDust or TONCO referral fees via the public REST API. To track these fees you should use the on-chain flow described above or your own indexer for the specific deployed payout contracts.

***

## TON escrow payout contracts

For Escrow swaps, referral fees are collected through a dedicated **Escrow Minter contract**. While the mechanism is conceptually similar to DeDust, Escrow uses **different vault contracts with different interfaces**. These are not the same vaults used by the cross-dex protocol.

> **SDK Note:** The SDK wrappers (`EscrowMinter`/`EscrowVault`) are not yet available in the SDK. The examples below use direct contract calls.

> **Implementation Note:** Like DeDust, Escrow fee collection requires **on-chain contract calls** that are **not part of the STON.fi SDK**. You need:
>
> 1. **TON development environment** - Use [Blueprint](https://github.com/ton-org/blueprint) framework with `@ton/core` and `@ton/ton` packages
> 2. **Contract wrappers** - You must implement wrapper classes (`EscrowMinter`, `EscrowVault`) for the escrow contracts. For `JettonMaster`, you can use the one from `@ton/ton`
> 3. **RPC access** - A TON RPC provider like [toncenter.com](https://toncenter.com) for blockchain queries
>
> The [Low-level RPC approach](#low-level-rpc-approach) described in the DeDust and TONCO section also applies here - just substitute the Escrow Minter address and use the appropriate get-methods.

### 1 · Find your personal vault

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

1. **Get the Escrow Minter's jetton wallet address** Retrieve it via `jettonMaster.getWalletAddress(escrowMinter.address)`.
2. **Query your personal vault** by calling `escrowMinter.getVaultAddress(escrowMinterWallet, ownerAddress)`.

```ts
// --- TypeScript example ------------------------------------------------------
import { Address } from '@ton/core';
import { JettonMaster } from '@ton/ton';
// EscrowMinter, EscrowVault are custom wrappers you must implement

// Official Escrow Minter deployment address (mainnet)
const escrowMinterAddress = Address.parse('EQDybO88l2lrrAmALRUqpmgEE_tuxk510F4Yd4xjbQZxC9IA');
const escrowMinter = provider.open(EscrowMinter.createFromAddress(escrowMinterAddress));

const jettonMasterAddress = Address.parse('USDT_jetton_master_address');
const ownerAddress = Address.parse('your_wallet_address'); // owner receiving the accrued TON payout

// JettonMaster from @ton/ton (sometimes called "Jetton Minter")
const jettonMaster = provider.open(JettonMaster.create(jettonMasterAddress));

const escrowMinterWallet = await jettonMaster.getWalletAddress(escrowMinter.address);
const vaultAddress = await escrowMinter.getVaultAddress(escrowMinterWallet, ownerAddress);
const escrowVault = provider.open(EscrowVault.createFromAddress(vaultAddress));

const vaultData = await escrowVault.getVaultData();
// {
//      minter: Address;
//      jettonWallet: Address;
//      balance: bigint;
//      owner: Address;
// }
```

The getter returns:

* **null or zero address (`0:0`)**: no fees accrued yet for this jetton
* **vault address**: your dedicated Escrow Fee-Vault contract for this jetton

### 2 · Withdraw the fees

The wrapper recipe also requires `toNano` from `@ton/core`.

To withdraw accumulated fees, call `sendVaultWithdrawTokens()` on your vault:

```ts
// amount is in jetton base units; adjust for decimals (e.g., 1_000_000n = 1 USDT for 6-decimal tokens)
const amount = 1_000_000n; // 1 USDT

if (vaultData.owner.toString() !== ownerAddress.toString()) {
    throw new Error('Sender is not the owner of the vault');
}
if (vaultData.balance < amount) {
    throw new Error('Not enough tokens in the vault');
}

await escrowVault.sendVaultWithdrawTokens(provider.sender(), toNano('0.2'), { // ~0.2 TON for gas (may vary)
    queryId: 0n,
    amount: amount,
    excesses: ownerAddress,
    withdrawForwardParams: null,
});
```

The complete flow consists of **three or four on-chain calls**:

| Step            | Contract       | Method                                       | Purpose                                        |
| --------------- | -------------- | -------------------------------------------- | ---------------------------------------------- |
| Read            | Jetton Master  | `getWalletAddress(escrowMinter.address)`     | Get Escrow Minter's jetton wallet              |
| Read            | Escrow Minter  | `getVaultAddress(escrowMinterWallet, owner)` | Get your vault address                         |
| Read (optional) | Your Fee-Vault | `getVaultData()`                             | Check balance and ownership before withdrawing |
| Write           | Your Fee-Vault | `sendVaultWithdrawTokens()`                  | Transfer accumulated fees to your wallet       |

> **API status** At the moment, Omniston does not expose Escrow referral fees via the public REST API. To track these fees you should use the on-chain flow described above or your own indexer for the specific deployed payout contracts.

***

## Data and compatibility

For STON.fi DEX v2 Vault discovery and fee history, use the [DEX REST reference](https://docs.ston.fi/developer-section/dex/api/reference.md#fee-statistics). For API upgrades, see [Versions and migrations](https://docs.ston.fi/developer-section/omniston/migration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/omniston/migration/fee-payouts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
