Comisiones por referidos

Guía de comisiones de referidos de Omniston: gana comisiones por los volúmenes de swap de DEX v1, v2, DeDust, Tonco y Escrow

Esta guía explica cómo se aplican las comisiones de referido en el protocolo de agregación de liquidez de Omniston cuando las operaciones se enrutan a través de DEX v1, DEX v2, DeDust, Tonco o Escrow.

Inicio rápido: ¿Buscas ejemplos de código? Ve a guías de implementación específicas de la plataforma para ver ejemplos de integración con SDK y API.

---

Especificación de parámetros de referido

Cuando solicitas una cotización, puedes adjuntar datos de referido para que una parte de la comisión del swap se redirija a tu dirección.

Parámetros de referido de nivel superior

Parámetro	Descripción
referrer_address	Dirección TON que recibe la comisión de referido
referrer_fee_bps	Tasa de comisión en puntos básicos (1 bps = 0,01 %)

Parámetros de liquidación

Parámetro	Descripción
flexible_referrer_fee	Bandera booleana (dentro de settlementParams) que permite a los resolutores reducir la comisión efectiva del referido cuando eso produce una mejor tasa de swap. El valor predeterminado es false. Consulte Comisión flexible del referidor para más detalles.

Ejemplo de JSON en una solicitud de cotización

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

guías de implementación específicas de la plataforma

Para ver ejemplos detallados de implementación y muestras de código:

• SDK de Node.js - Integración TypeScript/JavaScript con parámetros de referido

• SDK de React - Hooks y componentes de React para el seguimiento de referidos

• API gRPC - Integración directa con gRPC para implementaciones personalizadas

• API de WebSocket - Transmisión de cotizaciones en tiempo real con soporte de referido

---

Comisión flexible del referidor

El flexible_referrer_fee parámetro (parte de settlementParams / RequestSettlementParams) permite al protocolo Omniston ajustar automáticamente a la baja tu comisión de referido cuando hacerlo proporcione una mejor tasa de swap para el usuario.

Por qué existe esta función

Esta función fue diseñada para resolver un problema específico de compatibilidad entre distintas versiones de DEX:

• DEX v1 tiene una comisión máxima fija de referido de 0.1% (10 bps) impuesta por el contrato del pool

• DEX v2, DeDust, Tonco y Escrow admiten comisiones configurables de 0,01 % a 1 %

El problema: Supongamos que estableces una comisión de referido de 0.3% (30 bps) en tu solicitud de cotización. Si la mejor tasa de swap resulta ser a través de un pool de DEX v1, esa ruta normalmente se excluiría porque v1 no puede admitir una comisión de referido del 0,3 %. Esto obliga al protocolo a usar una ruta subóptima a través de v2, DeDust, Tonco o Escrow, incluso si el pool v1 ofrece una tasa significativamente mejor para el usuario.

La solución: Cuando habilitas flexible_referrer_fee: true, el protocolo puede reducir automáticamente tu comisión de referido del 0,3 % al 0,1 % al enrutar a través de pools v1. Esto permite que el usuario se beneficie de la mejor tasa disponible mientras tú sigues ganando la comisión de referido máxima que v1 admite.

Pautas de uso

• Por defecto es false—debes habilitarlo explícitamente

• Solo afecta a rutas donde una comisión menor desbloquearía una mejor tasa

• Tu comisión de referido nunca aumentará, solo disminuirá cuando sea beneficioso

• Es más útil cuando se establecen comisiones de referido superiores al 0,1 % (10 bps)

Ejemplo de escenario:

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

Con esta configuración:

• Si la mejor tasa es a través de v2/DeDust/Tonco/Escrow: recibes el total 0.3%

• Si la mejor tasa es a través de v1: tu comisión se reduce automáticamente a 0.1%, pero el usuario obtiene una mejor tasa de swap

---

Comisiones de referido con DEX v1

Característica	Detalles
Tasa de comisión	Fija del 0,1 % (10 bps) impuesta por el contrato del pool
Liquidación	Pagada on-chain en la misma tx de swap a referrer_address

No se requiere nada más: las comisiones llegan automáticamente.

---

Comisiones de referido con DEX v2

1 · Cómo se acumulan las comisiones

• La tasa de comisión es configurable de 0,01 % a 1 % por swap.

• En lugar de pagarse al instante, las comisiones se depositan en un Bóveda (una bóveda por par token × dirección de referido ).

2 · Retiro de tus comisiones

Las comisiones de referido de DEX v2 se almacenan en una bóveda especial y deben reclamarse manualmente.

Para reclamar tus comisiones:

1. Ve a la interfaz de la bóveda visitando el siguiente enlace: https://sdk-demo-app.ston.fi/vault

2. Conecta tu billetera al sitio.

3. Una vez conectada, la interfaz mostrará todas las comisiones de referido disponibles que puedes reclamar.

4. Encuentra la comisión que quieres reclamar y haz clic en el botón "Claim".

5. Se enviará una transacción a tu billetera; confírmala.

6. Después de la confirmación, las comisiones de referido reclamadas aparecerán en tu billetera.

Para retiros automatizados mediante SDK/código:

Para una referencia completamente funcional, abre la demo de retiro de la bóveda dentro de nuestro mono-repo del SDK:

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

Cómo funciona en la práctica

• Supón que un trader intercambia A → B y se especifica una comisión de referido.

• Durante ese swap, el Enrutador despliega (o reutiliza) un Bóveda cuya dirección se deriva de forma determinista de la dirección del pool y la dirección del router.

• La API puede descubrir automáticamente todas tus bóvedas usando el /v1/wallets/{addr_str}/fee_vaults endpoint, eliminando la necesidad de rastrear manualmente las direcciones de los pools.

• Con las direcciones de las bóvedas recuperadas, instancia un Enrutador desde el SDK y llama al helper (por ejemplo, withdrawFees()) para recoger los tokens acumulados mediante TonConnect o cualquier integración de billetera preferida.

El ejemplo vinculado muestra este flujo de descubrir → instanciar → retirar de extremo a extremo, incluyendo patrones robustos de TypeScript y la conexión con TonConnect.

Nota Para comisiones denominadas en TON en DEX v2, el tokenMinter es la pTON dirección maestra (ptonMasterAddress).

---

Comisiones de referido con Tonco

Para swaps de Tonco, usamos el mismo mecanismo de comisión de referido que DeDust a través del contrato independiente Fee-Vault Minter. El flujo es idéntico al de DeDust:

1. Encuentra tu bóveda personal usando los mismos métodos descritos en la sección de DeDust

2. Reclama las comisiones enviando un mensaje a tu bóveda con collectFees()

3. Las comisiones en TON se acreditan al instante, mientras que las comisiones en jetton se acumulan en tu bóveda

Consulta la sección de DeDust más abajo para obtener instrucciones detalladas de implementación.

Estado de la API Por el momento, Omniston no expone las comisiones de referido de Tonco a través de la API REST pública. Para rastrear estas comisiones debes usar el flujo on-chain descrito arriba o tu propio indexador hasta que se publique la API de omni-fees.

---

Comisiones de referido con DeDust

Para swaps de DeDust, implementamos nuestro propio mecanismo de comisión de referido a través de un contrato independiente Fee-Vault Minter. Este flujo omite el Router usado en Ston.fi DEX v2, por lo que los helpers existentes del SDK no se pueden usar—debes llamar directamente a los métodos del contrato on-chain.

Actualización importante: Hemos desplegado un nuevo contrato Fee-Vault Minter en EQCcJf2KFlH9xIx3dztytxxRFk3KQZKEYBr-f0nFIO1h3dvv. Las nuevas comisiones se dirigirán a este nuevo contrato. Los usuarios pueden reclamar comisiones de contratos anteriores (EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH, EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye, y EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL) y del nuevo contrato.

Nota de implementación: Los ejemplos de código a continuación demuestran llamadas on-chain a contratos usando la blockchain TON. Estos no forman parte del SDK de STON.fi. Para usarlos, necesitas:

1. Entorno de desarrollo TON - Usa Blueprint framework con @ton/core y @ton/ton paquetes

2. wrappers de contratos - Debes implementar clases wrapper (FeeVaultMinter, FeeVaultContract) para los contratos de la bóveda de comisiones. Para JettonMaster, puedes usar el de @ton/ton

3. acceso RPC - Un proveedor RPC de TON como toncenter.com para consultas a la blockchain

Si prefieres no escribir wrappers de contratos, consulta la sección de enfoque RPC de bajo nivel más abajo.

1 · Encuentra tu bóveda personal

Cada jetton tiene su propio contrato de bóveda. Para encontrar la dirección de tu bóveda para un jetton específico:

1. Obtén la dirección de la billetera jetton del Fee-Vault Minter Cada Fee-Vault Minter posee una billetera jetton normal. Recupérala mediante jettonMaster.getWalletAddress(feeVaultMinter.address).

2. Consulta tu bóveda personal llamando a feeVaultMinter.getVaultAddress({ owner: <your_wallet>, jettonWallet: <feeVaultMinterWallet> }).

// --- Ejemplo de TypeScript ------------------------------------------------------
import { Address } from '@ton/core';
import { JettonMaster } from '@ton/ton';
// FeeVaultMinter, FeeVaultContract son wrappers personalizados que debes implementar

// Old Fee-Vault Minters (para reclamar comisiones existentes):
// - EQD5TIvGT6NxphRDKX9wRUkJOHyE0VTuTGdVSGA5N_b62naH
// - EQBCAUfvMMSn-WHP0bKDs4wUVOK1r55OuHJIq25_QnVFCFye
// - EQAAoyu0C-aMYGPVEoMfuAge2-meJWeO5KLJKrKWJAJAKXGL
// Nuevo Fee-Vault Minter (para nuevas comisiones): EQCcJf2KFlH9xIx3dztytxxRFk3KQZKEYBr-f0nFIO1h3dvv
const feeVaultMinterAddress = Address.parse("EQCcJf2KFlH9xIx3dztytxxRFk3KQZKEYBr-f0nFIO1h3dvv");
const feeVaultMinter = provider.open(
  FeeVaultMinter.createFromAddress(feeVaultMinterAddress),
);

const jettonMasterAddress = Address.parse("USDT_jetton_master_address");
const ownerAddress = Address.parse("your_wallet_address"); // igual que referrer_address en la solicitud de cotización

// JettonMaster de @ton/ton (a veces llamado "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,
});

// ¿Necesitas más que solo la dirección? Consulta los datos on-chain con getVaultData():
const vault = provider.open(FeeVaultContract.createFromAddress(vaultAddress));
const vaultData = await vault.getVaultData();
// vaultData.balance, vaultData.lastCollectTime, …

El getter devuelve:

• 0:0 – aún no se han acumulado comisiones para este jetton

• dirección de la bóveda – tu contrato Fee-Vault dedicado para este jetton

Las direcciones de las bóvedas se derivan de forma determinista tanto de la dirección del referido como de la dirección del jetton.

2 · Reclamación de las comisiones

1. Envía un mensaje interno a tu bóveda llamando a collectFees() (sin carga útil) con aproximadamente 0,3 TON adjuntos para gas.

2. La bóveda transfiere inmediatamente los fee-tokens acumulados a tu billetera y restablece su saldo.

3. Para las comisiones en TON, se acreditan al instante en la dirección del referido durante la transacción de swap.

El flujo completo consta de dos o tres llamadas on-chain:

Paso	Contrato	Método	Propósito
Leer	Fee-Vault Minter	getVaultAddress(user, jetton)	Obtener la dirección de tu bóveda
Lectura (opcional)	Tu Fee-Vault	getVaultData()	Comprobar el saldo antes de reclamar
Escribir	Tu Fee-Vault	collectFees()	Transferir las comisiones acumuladas a tu billetera

Enfoque RPC de bajo nivel

Si no quieres configurar Blueprint ni escribir wrappers de contratos, puedes consultar los datos de la bóveda directamente usando llamadas RPC a cualquier proveedor de API de TON (por ejemplo, toncenter.com).

Codificación de slice: Los elementos de la pila de tipo tvm.Slice deben ser BOC codificado en base64 (bag of cells). Para convertir una dirección en un slice:

import { beginCell, Address } from '@ton/core';
const addr = Address.parse("EQ...");
const sliceBoc = beginCell().storeAddress(addr).endCell().toBoc().toString('base64');

Paso 1: Obtén la dirección de la billetera jetton del Fee-Vault Minter

Llama a get_wallet_address en el contrato Jetton Master:

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>"]]
  }'

Paso 2: Obtén la dirección de tu bóveda

Llama a get_vault_address en el Fee-Vault Minter:

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>"]
    ]
  }'

Paso 3: Consulta los datos de la bóveda

Llama a get_vault_data en tu bóveda:

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

La respuesta contiene celdas que codifican: dirección del owner, dirección de la billetera jetton, saldo y dirección del minter.

Consejo: Puedes ver los datos de la bóveda directamente en tonviewer.com yendo a la dirección de tu bóveda y haciendo clic en "Methods" para ejecutar get_vault_data.

Verificación de la dirección de tu bóveda

Para confirmar que la dirección de tu bóveda es correcta:

1. Calcula la dirección de la bóveda usando el ejemplo de código anterior

2. Abre tu transacción de swap en tonviewer.com y expande el rastro de la transacción

3. Encuentra la dirección de la bóveda en el rastro: debe coincidir con la dirección calculada desde tu código

4. Navega a tu bóveda en tonviewer: https://tonviewer.com/<vault_address>?section=method

5. Ejecuta get_vault_data - esto devuelve la misma estructura de datos que vault.getVaultData() en el ejemplo de código:

   • Dirección del owner (tu dirección de referido)

   • Dirección de la billetera jetton

   • Saldo (comisiones acumuladas)

   • Dirección del minter

Si los datos coinciden con los valores esperados, la derivación de la dirección de tu bóveda es correcta.

Estado de la API Por el momento, Omniston no expone las comisiones de referido de DeDust a través de la API REST pública. Para rastrear estas comisiones debes usar el flujo on-chain descrito arriba o tu propio indexador hasta que se publique la API de omni-fees.

---

Comisiones de referido con Escrow

Para swaps de Escrow, las comisiones de referido se recogen a través de un contrato Escrow Minter. Aunque el mecanismo es conceptualmente similar al de DeDust, Escrow usa distintos contratos de bóveda con diferentes interfaces—estas no son las mismas bóvedas usadas por el protocolo cross-dex.

Nota sobre el SDK: Los wrappers del SDK (EscrowMinter/EscrowVault) aún no están disponibles en el SDK. Los ejemplos siguientes usan llamadas directas al contrato.

Nota de implementación: Al igual que DeDust, la recolección de comisiones de Escrow requiere llamadas on-chain a contratos que son no forman parte del SDK de STON.fi. Necesitas:

1. Entorno de desarrollo TON - Usa Blueprint framework con @ton/core y @ton/ton paquetes

2. wrappers de contratos - Debes implementar clases wrapper (EscrowMinter, EscrowVault) para los contratos de escrow. Para JettonMaster, puedes usar el de @ton/ton

3. acceso RPC - Un proveedor RPC de TON como toncenter.com para consultas a la blockchain

El sección de enfoque RPC de bajo nivel descrito en la sección de DeDust también aplica aquí: solo sustituye la dirección de Escrow Minter y usa los get-methods apropiados.

1 · Encuentra tu bóveda personal

Cada jetton tiene su propio contrato de bóveda. Para encontrar la dirección de tu bóveda para un jetton específico:

1. Obtén la dirección de la billetera jetton del Escrow Minter Recupérala mediante jettonMaster.getWalletAddress(escrowMinter.address).

2. Consulta tu bóveda personal llamando a escrowMinter.getVaultAddress(escrowMinterWallet, ownerAddress).

// --- Ejemplo de TypeScript ------------------------------------------------------
import { Address } from '@ton/core';
import { JettonMaster } from '@ton/ton';
// EscrowMinter, EscrowVault son wrappers personalizados que debes implementar

// Dirección oficial de despliegue de Escrow Minter (mainnet)
const escrowMinterAddress = Address.parse('EQAhedmtkPnKnQRlkkK3aEUDqGMg4Ewwz0LPj18HwLasAJdp');
const escrowMinter = provider.open(EscrowMinter.createFromAddress(escrowMinterAddress));

const jettonMasterAddress = Address.parse('USDT_jetton_master_address');
const ownerAddress = Address.parse('your_wallet_address'); // igual que referrer_address en la solicitud de cotización

// JettonMaster de @ton/ton (a veces llamado "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;
// }

El getter devuelve:

• dirección nula o cero (0:0) – aún no se han acumulado comisiones para este jetton

• dirección de la bóveda – tu contrato Escrow Fee-Vault dedicado para este jetton

2 · Retirar las comisiones

Para retirar las comisiones acumuladas, llama a sendVaultWithdrawTokens() en tu bóveda:

// la cantidad está en unidades base del jetton; ajústala según los decimales (por ejemplo, 1_000_000n = 1 USDT para tokens de 6 decimales)
const amount = 1_000_000n; // 1 USDT

if (vaultData.owner.toString() !== ownerAddress.toString()) {
    throw new Error('El remitente no es el propietario de la bóveda');
}
if (vaultData.balance < amount) {
    throw new Error('No hay suficientes tokens en la bóveda');
}

await escrowVault.sendVaultWithdrawTokens(provider.sender(), toNano('0.2'), { // ~0,2 TON para gas (puede variar)
    queryId: 0n,
    amount: amount,
    excesses: ownerAddress,
    withdrawForwardParams: null,
});

El flujo completo consta de tres o cuatro llamadas on-chain:

Paso	Contrato	Método	Propósito
Leer	Jetton Master	getWalletAddress(escrowMinter.address)	Obtener la billetera jetton del Escrow Minter
Leer	Escrow Minter	getVaultAddress(escrowMinterWallet, owner)	Obtener la dirección de tu bóveda
Lectura (opcional)	Tu Fee-Vault	getVaultData()	Comprobar saldo y propiedad antes de retirar
Escribir	Tu Fee-Vault	sendVaultWithdrawTokens()	Transferir las comisiones acumuladas a tu billetera

Estado de la API Por el momento, Omniston no expone las comisiones de referido de Escrow a través de la API REST pública. Para rastrear estas comisiones debes usar el flujo on-chain descrito arriba o tu propio indexador hasta que se publique la API de omni-fees.

---

Resumen

Protocolo	Mecanismo de comisión	Rango	Cómo recibir los fondos
DEX v1	Pago directo dentro de la tx de swap	0.1 %	Automático
DEX v2	Las comisiones se acumulan en una bóveda (token × referido)	0,01 – 1 %	retiro desde la interfaz o por código
DeDust	Bóvedas conscientes del token (una por jetton)	0,01 – 1 %	TON: instantáneo, Jettons: getVaultAddress → collectFees()
Tonco	Bóvedas conscientes del token (mismo flujo que DeDust)	0,01 – 1 %	TON: instantáneo, Jettons: getVaultAddress → collectFees()
Escrow	Bóvedas conscientes del token (contratos distintos a cross-dex)	0,01 – 1 %	getVaultAddress → sendVaultWithdrawTokens()

Endpoints de la API de estadísticas y bóvedas

Además de la lectura on-chain o las llamadas directas al contrato, puedes rastrear y gestionar las comisiones de referido usando nuestra API REST.

Nota de alcance Estos endpoints exponen datos de referido solo para pools de STON.fi DEX. Ellos no devuelven datos de referido a nivel Omniston para rutas ejecutadas en DeDust, Tonco o Escrow. Se planea una API dedicada para comisiones de omni (que cubra el volumen de DeDust/Tonco/Escrow), pero aún no está disponible. Los endpoints de bóvedas de comisiones (fee_vaults, fee_accruals, fee_withdrawals) se aplican solo a DEX v2, porque en DEX v1 no existen bóvedas.

• GET /v1/wallets/{addr_str}/fee_vaults Lista todas las bóvedas de comisión de referido para STON.fi DEX v2 (una bóveda por referrer × token). DEX v1 no usa bóvedas, así que este endpoint no mostrará actividad de referido exclusiva de v1.

• GET /v1/stats/fee_accruals Devuelve una fila por cada acumulación de comisión de referido registrada en vaults de comisiones de referidos de STON.fi DEX v2. El conjunto de datos subyacente se construye a partir de operaciones de bóveda filtradas por owner y rango de tiempo, por lo que las comisiones de referido de DEX v1 (pagadas directamente a las billeteras de los referidos) no están incluidas.

• GET /v1/stats/fee_withdrawals Muestra los retiros de DEX v2 bóvedas de comisión de referido. No hay entradas de v1 aquí, ya que las comisiones de referido de DEX v1 nunca se almacenan en bóvedas.

• GET /v1/stats/fees Devuelve métricas agregadas de comisiones de referido (por ejemplo, el valor total acumulado en USD) durante un período de tiempo. Usa la documentación Swagger para ver los filtros exactos admitidos (por ejemplo, por referido, token o rango de tiempo).

• Swagger UI Accede a la documentación interactiva de la API en https://api.ston.fi/swagger-ui/#/.

---

Recursos adicionales

Guías de implementación:

• SDK de Node.js - Solicitudes de cotización

• SDK de React - Solicitudes de cotización

• API gRPC - Flujo del trader

• API WebSocket - Suscripción a cotizaciones

Otros recursos:

• Omniston Inicio rápido

• Contactar con soporte