Swap (v2)

Ejecuta swaps en STON.fi v2: enrutamiento mejorado con mecánica de vault para obtener las mejores tasas

Más información

• Guía de inicio rápido: Consulte nuestro Inicio rápido de Swap para un ejemplo completo de aplicación React

• Blog: DeFi fácil para proyectos TON: integración de STON.fi

El patrón listo para producción es basado en API. Deja siempre que la API de STON.fi dicte qué router usar y trabaja con el endpoint de mainnet. Esto mantiene tu integración compatible con futuras actualizaciones del router y evita codificar direcciones de contrato de forma fija.

Flujo de trabajo primero para mainnet

La API REST de STON.fi (api.ston.fi) solo sirve datos de mainnet, así que cada swap en producción debe seguir este flujo:

1. Simula el swap para obtener metadatos de enrutamiento (cantidades esperadas, información de la bóveda y el objeto completo del router).

2. Pase simulationResult.router directamente a dexFactory() para crear contratos dinámicamente.

3. Genera los parámetros de la transacción de swap con los helpers del router.

import { dexFactory, Client } from "@ston-fi/sdk";
import { StonApiClient } from "@ston-fi/api";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

const apiClient = new StonApiClient();

// 1. Simula el swap para descubrir los detalles de enrutamiento
const simulationResult = await apiClient.simulateSwap({
  offerAddress: "<dirección del activo de origen o 'ton'>",
  askAddress: "<dirección del activo de destino>",
  offerUnits: "<cantidad en unidades de blockchain>",
  slippageTolerance: "0.01",
});

// 2. Los metadatos del router vienen con el resultado de la simulación
const { router: routerInfo } = simulationResult;
const dexContracts = dexFactory(routerInfo);

// 3. Abra el contrato del router
const router = tonClient.open(
  dexContracts.Router.create(routerInfo.address)
);

// Helper opcional cuando TON forma parte de la ruta
const proxyTon = dexContracts.pTON.create(routerInfo.ptonMasterAddress);

El simulationResult el objeto contiene offerUnits, minAskUnits, offerAddress, askAddress, y router. Reutiliza esos valores al construir la transacción real de swap para asegurar que la transacción firmada coincida con la ruta simulada.

Comisiones por referidos: Puedes especificar una comisión de referido en tu swap si es necesario. Para más contexto, consulta la guía de comisiones de referido de Omniston (aunque está orientado a Omniston, el párrafo enlazado detalla cómo funcionan las comisiones de referido de DEX V2).

Swap de TON a jetton

const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  askJettonAddress: simulationResult.askAddress,
  proxyTon,
  // Parámetros opcionales de referido:
  referralAddress: "<la dirección TON de tu referido>",
  referralValue: 10, // p. ej. 10 => comisión del 0.1%
  queryId: 12345,
});

Envía los parámetros resultantes usando tu integración de billetera preferida. Consulta nuestro guía para enviar transacciones para ejemplos específicos de billeteras.

Swap de jetton a jetton

const txParams = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerJettonAddress: simulationResult.offerAddress,
  askJettonAddress: simulationResult.askAddress,
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  // Parámetros opcionales de referido:
  referralAddress: "<la dirección TON de tu referido>",
  referralValue: 25, // p. ej. 25 => comisión del 0.25%
  queryId: 12345,
});

Swap de jetton a TON

const txParams = await router.getSwapJettonToTonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerJettonAddress: simulationResult.offerAddress,
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  proxyTon, // reutilizar de la configuración común
  // Parámetros opcionales de referido:
  referralAddress: "<la dirección TON de tu referido>",
  referralValue: 50, // p. ej. 50 => comisión del 0.5%
  queryId: 12345,
});

Usa el guía para enviar transacciones para transmitir la transacción. TonConnect, Tonkeeper SDK, firmantes custodiales y otras bibliotecas aceptan todos el txParams generados arriba.

Swaps en testnet (configuración manual)

Si realmente necesitas ejecutar swaps v2 en la testnet de TON, debes recurrir a contratos codificados de forma fija porque api.ston.fi solo sirve para mainnet. La liquidez es escasa, así que planifica obtener o acuñar los jettons tú mismo, crear los pools de liquidez necesarios y financiarlos antes de intentar hacer el swap.

Para reflejar los tres tipos de swap del ejemplo de mainnet, los testers suelen ejecutar la siguiente secuencia en testnet:

1. swap 1 TON por TesREED (ton -> jetton)

2. swap TesREED por TestBlue (jetton -> jetton)

3. swap TestBlue de vuelta a TON (jetton -> ton)

import { TonClient, toNano } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";

const client = new TonClient({
  endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create("kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v") // Router CPI v2.1.0 (testnet)
);

const proxyTon = pTON.v2_1.create("kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px"); // pTON v2.1.0 (testnet)

const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "<su billetera de testnet>",
  proxyTon,
  offerAmount: toNano("1"),
  askJettonAddress: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // jetton TesREED (testnet)
  minAskAmount: "1",
});

Este enfoque manual es estrictamente para pruebas. Vuelva al flujo de trabajo impulsado por la API para cualquier cosa orientada a mainnet.