Guía de Omniston (React)

Guía rápida de integración para Omniston: empieza a construir funciones de agregación entre DEX en minutos

Esta guía te guiará a través de la creación de una aplicación básica de intercambio de tokens usando el Omniston protocolo para intercambiar activos entre diferentes DEXes (STON.fi V1, STON.fi V2, DeDust, etc.). Integraremos la conectividad de billetera con TonConnect (a través de @tonconnect/ui-react) para permitir que los usuarios conecten su billetera TON y realicen un intercambio. La guía está pensada para principiantes y asume una experiencia mínima con React.

Nota: En esta demo, aprovecharemos Tailwind CSS para el estilo en lugar de usar CSS personalizado. La configuración de Tailwind CSS ya está incluida en las instrucciones de abajo, así que no necesitas configurarlo por separado.

Nota: Puedes usar cualquier gestor de paquetes (npm, yarn, pnpm o bun) para configurar tu proyecto React. En este tutorial, lo mostraremos con pnpm.

---

Índice

1. Introducción

2. Configuración del proyecto

3. Conectar la billetera

4. Obtener los activos disponibles

5. Solicitar una cotización

6. Construir una transacción

7. Rastrear tu operación

8. Probar tu intercambio

9. Conclusión

10. Demo en vivo

11. Aplicación de ejemplo avanzada

12. Uso de agentes de IA para la implementación automatizada

---

1. Introducción

En este inicio rápido, construiremos una aplicación React mínima para:

• Conectarse a una billetera TON (a través de TonConnect UI).

• Obtener los tokens disponibles de STON.fi y mostrarlos en menús desplegables.

• Solicitar una cotización (RFQ) a Omniston para obtener la mejor ruta de intercambio (no se necesita un paso separado de "Simular"; Omniston obtiene las cotizaciones automáticamente).

• Construir y ejecutar una transacción de intercambio a través de múltiples DEXes.

• Rastrear el estado de la operación hasta su finalización.

Usaremos:

• @ston-fi/omniston-sdk-react – Hooks de React para interactuar con Omniston (solicitar cotizaciones, rastrear operaciones, etc.).

• @ston-fi/api – Obtener listas de tokens desde STON.fi (y potencialmente otros datos).

• @tonconnect/ui-react – Proporciona un botón de conexión a billetera TON basado en React y utilidades.

• @ton/core – Biblioteca de bajo nivel de TON utilizada para funcionalidades avanzadas.

---

2. Configuración del proyecto

2.1 Crear una aplicación React

Primero, comprobemos si pnpm está instalado en tu sistema:

pnpm --version

Si ves un número de versión (como 10.4.0), pnpm está instalado. Si obtienes un error, primero tendrás que instalar pnpm:

npm install -g pnpm

Ahora crearemos un nuevo proyecto de React usando Vite. Sin embargo, puedes usar cualquier configuración de React que prefieras (Next.js, CRA, etc.).

Ejecuta el siguiente comando para crear un nuevo proyecto de React basado en Vite:

pnpm create vite --template react-ts

Cuando se te pregunte, escribe el nombre de proyecto que desees (por ejemplo, omniston-swap-app):

Nombre del proyecto: » omniston-swap-app

Luego entra en la carpeta:

cd omniston-swap-app

---

2.2 Instalación de los paquetes necesarios

Dentro del directorio de tu nuevo proyecto de React, instala el SDK de Omniston, TonConnect UI, la biblioteca TON core y la biblioteca API de STON.fi:

pnpm add @ston-fi/omniston-sdk-react @tonconnect/ui-react @ton/core @ston-fi/api

A continuación, instala Tailwind CSS y su plugin para Vite:

pnpm add tailwindcss @tailwindcss/vite

Además, instala el plugin de polyfills de Node.js para Vite, que es necesario para proporcionar Buffer y otras APIs de Node.js en el entorno del navegador (requerido por las bibliotecas de TON):

pnpm add vite-plugin-node-polyfills

Configura el plugin de Vite actualizando el archivo vite.config.js . Solo se requieren el buffer shim y el global Buffer para las bibliotecas de TON, así que la configuración se mantiene reducida:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    nodePolyfills({
      include: ['buffer'],
      globals: {
        Buffer: true,
      },
    }),
  ],
})

Luego, importa Tailwind CSS en tu archivo CSS principal. Abre src/index.css y reemplaza cualquier código existente con:

@import "tailwindcss";

También puedes eliminar src/App.css (no lo necesitamos), y eliminar la instrucción de importación import './App.css' de src/App.tsx.

Después de hacer estos cambios, puedes verificar que tu aplicación sigue funcionando correctamente iniciando el servidor de desarrollo:

pnpm install
pnpm dev

Esto debería iniciar tu aplicación en modo desarrollo, normalmente en http://localhost:5173. Deberías ver el logotipo y el texto de Vite + React sobre un fondo blanco simple. Como hemos eliminado el estilo predeterminado (App.css), la página se verá más sencilla que la plantilla por defecto.

Si ves el logotipo y el texto, significa que tu configuración de Vite + React está funcionando correctamente. Asegúrate de que todo cargue sin errores antes de continuar con el siguiente paso.

---

3. Conectar la billetera

3.1 Añadir los proveedores necesarios

Abre src/main.tsx (punto de entrada predeterminado de Vite) y envuelve tu aplicación con ambos TonConnectUIProvider y OmnistonProvider. El TonConnectUIProvider hace que el contexto de TonConnect esté disponible para tu app para la conectividad con la billetera, mientras que el OmnistonProvider habilita la funcionalidad de Omniston en toda tu aplicación. Además, apunta el proveedor de TonConnect a un archivo manifest (que crearemos a continuación) que describa tu aplicación para las billeteras.

// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { TonConnectUIProvider } from '@tonconnect/ui-react';
import { Omniston, OmnistonProvider } from '@ston-fi/omniston-sdk-react';
import './index.css'
import App from './App.tsx'

const omniston = new Omniston({ apiUrl: "wss://omni-ws.ston.fi" });

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <TonConnectUIProvider 
      // Para fines de demostración, usamos una URL estática para el manifiesto
      // Reemplaza por la tuya: manifestUrl={`${window.location.origin}/tonconnect-manifest.json`}`
      manifestUrl="https://gist.githubusercontent.com/mrruby/243180339f492a052aefc7a666cb14ee/raw/">
      <OmnistonProvider omniston={omniston}>
        <App />
      </OmnistonProvider>
    </TonConnectUIProvider>
  </StrictMode>,
)

---

3.2 Crear el manifiesto de TonConnect

En la public carpeta de tu proyecto, crea un archivo llamado tonconnect-manifest.json. Este manifest proporciona a las apps de billetera información sobre tu aplicación (como el nombre y el icono). Debes personalizar este manifest para tu propia aplicación. Aquí tienes un ejemplo:

{
  "url": "https://omniston-demo.example.com",
  "name": "Omniston Swap Demo",
  "iconUrl": "https://omniston-demo.example.com/icon-192x192.png"
}

Asegúrate de actualizar estos campos para tu aplicación:

• url: La URL base desde la que se sirve tu aplicación

• name: El nombre visible de tu aplicación (esto es lo que las billeteras mostrarán a los usuarios)

• iconUrl: Un enlace al icono de tu aplicación (debe ser una imagen PNG de 180×180)

Asegúrate de que este archivo sea accesible. Cuando se ejecute el servidor de desarrollo, deberías poder obtenerlo en tu navegador en http://localhost:5173/tonconnect-manifest.json.

---

3.3 Agregar el botón de conectar billetera

En tu App principal, componente (por ejemplo, src/App.tsx), importa e incluye el TonConnectButton. Por ejemplo:

// src/App.tsx
import { TonConnectButton } from '@tonconnect/ui-react';

function App() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen p-4">
      <h1 className="text-2xl font-bold mb-4">Omniston Swap Demo</h1>
      <TonConnectButton />
    </div>
  );
}

export default App;

---

4. Obtener los activos disponibles

A continuación, recuperemos dinámicamente la lista de tokens (activos) que se pueden intercambiar en STON.fi. Usamos el cliente de la API de STON.fi (@ston-fi/api) para esto. Aquí tienes un ejemplo simplificado que filtra los activos por liquidez (de alta a media). Los almacenaremos en el estado y los presentaremos en los menús desplegables From/To.

Primero, añade las importaciones necesarias a lo que tenemos en src/App.tsx:

import { useEffect, useState } from 'react';
import { StonApiClient, AssetTag, type AssetInfoV2 } from '@ston-fi/api';

Inicializa las variables de estado en tu componente App:

function App() {
  const [assets, setAssets] = useState<AssetInfoV2[]>([]);
  const [fromAsset, setFromAsset] = useState<AssetInfoV2 | undefined>();
  const [toAsset, setToAsset] = useState<AssetInfoV2 | undefined>();
  const [amount, setAmount] = useState('');

Añade la lógica de obtención de activos con useEffect:

  // obtener activos al montar
  useEffect(() => {
    const fetchAssets = async () => {
      try {
        const client = new StonApiClient();
        // Filtrar los tokens de mayor liquidez para abreviar
        const condition = [
          AssetTag.LiquidityVeryHigh,
          AssetTag.LiquidityHigh,
          AssetTag.LiquidityMedium
        ].join(' | ');
        const assetList = await client.queryAssets({ condition });

        setAssets(assetList);
        if (assetList.length > 0) {
          setFromAsset(assetList[0]);
        }
        if (assetList.length > 1) {
          setToAsset(assetList[1]);
        }
      } catch (err) {
        console.error('No se pudieron obtener los activos:', err);
      }
    };
    fetchAssets();
  }, []);

Crea la estructura principal de la interfaz:

  return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gradient-to-b from-blue-50 to-indigo-100 p-6">
      <div className="w-full max-w-md bg-white rounded-xl shadow-lg p-6 space-y-6">
        <div className="flex justify-between items-center">
          <h1 className="text-3xl font-bold text-indigo-700">Omniston Swap</h1>
          <TonConnectButton />
        </div>

        <div className="h-px bg-gray-200 w-full my-4"></div>

Añade los menús desplegables de selección de tokens:

        {assets.length > 0 ? (
          <div className="space-y-6">
            {/* From */}
            <div className="flex flex-col">
              <label className="text-sm font-medium text-gray-600 mb-1">
                Desde
              </label>
              <select
                value={fromAsset?.contractAddress || ''}
                onChange={(e) => {
                  const selected = assets.find(a => a.contractAddress === e.target.value);
                  setFromAsset(selected);
                }}
                className="w-full p-3 bg-gray-50 border border-gray-200 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-indigo-500 transition-all"
              >
                {assets.map(asset => (
                  <option
                    key={asset.contractAddress}
                    value={asset.contractAddress}
                  >
                    {asset.meta?.symbol || asset.meta?.displayName || 'token'}
                  </option>
                ))}
              </select>
            </div>

            {/* To */}
            <div className="flex flex-col">
              <label className="text-sm font-medium text-gray-600 mb-1">
                A
              </label>
              <select
                value={toAsset?.contractAddress || ''}
                onChange={(e) => {
                  const selected = assets.find(a => a.contractAddress === e.target.value);
                  setToAsset(selected);
                }}
                className="w-full p-3 bg-gray-50 border border-gray-200 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-indigo-500 transition-all"
              >
                {assets.map(asset => (
                  <option
                    key={asset.contractAddress}
                    value={asset.contractAddress}
                  >
                    {asset.meta?.symbol || asset.meta?.displayName || 'token'}
                  </option>
                ))}
              </select>
            </div>

            {/* Amount */}
            <div className="flex flex-col">
              <label className="text-sm font-medium text-gray-600 mb-1">
                Cantidad
              </label>
              <input
                type="text"
                value={amount}
                onChange={(e) => setAmount(e.target.value)}
                placeholder="0.0"
                className="w-full p-3 bg-gray-50 border border-gray-200 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-indigo-500 transition-all"
              />
            </div>
          </div>

Añade el estado de carga y cierra el componente:

        ) : (
          <div className="flex justify-center items-center py-10">
            <div className="animate-pulse flex space-x-2">
              <div className="h-2 w-2 bg-indigo-500 rounded-full"></div>
              <div className="h-2 w-2 bg-indigo-500 rounded-full"></div>
              <div className="h-2 w-2 bg-indigo-500 rounded-full"></div>
            </div>
            <p className="ml-3 text-gray-600">Cargando activos...</p>
          </div>
        )}
      </div>

      <div className="mt-6 text-center text-xs text-gray-500">
        Impulsado por Ston.fi
      </div>
    </div>
  );
}

export default App;

---

5. Solicitar una cotización

Usaremos el useRfq hook de @ston-fi/omniston-sdk-react para solicitar una cotización. Obtendrá cotizaciones automáticamente según los parámetros proporcionados.

Añade importaciones adicionales en la parte superior del archivo:

import { useRfq, SettlementMethod, Blockchain, GaslessSettlement } from "@ston-fi/omniston-sdk-react";

Añade funciones de utilidad para convertir cantidades de tokens:

// Convertir una cantidad en cadena de punto flotante a una cadena de unidades base enteras
// Esencial para transacciones blockchain que usan aritmética entera
function toBaseUnits(amount: string, decimals?: number) {
  return Math.floor(parseFloat(amount) * 10 ** (decimals ?? 9)).toString();
}

// Convertir unidades base enteras de vuelta a una cadena fija de 2 decimales para mostrar
function fromBaseUnits(baseUnits: string, decimals?: number) {
  return (parseInt(baseUnits) / 10 ** (decimals ?? 9)).toFixed(2);
}

Configura el useRfq hook para obtener cotizaciones automáticamente:

function App() {
  ...
  const { data: quote, isLoading: quoteLoading, error: quoteError } = useRfq({
    settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
    bidAssetAddress: fromAsset
      ? { blockchain: Blockchain.TON, address: fromAsset.contractAddress }
      : undefined,
    askAssetAddress: toAsset
      ? { blockchain: Blockchain.TON, address: toAsset.contractAddress }
      : undefined,
    amount: {
      bidUnits: fromAsset ? toBaseUnits(amount, fromAsset.meta?.decimals) : '0'
    },
    settlementParams: {
      gaslessSettlement: GaslessSettlement.GASLESS_SETTLEMENT_POSSIBLE,
      maxPriceSlippageBps: 500,
    },
  }, {
    enabled: !!fromAsset?.contractAddress && !!toAsset?.contractAddress && amount !== ''
  });

Añade la sección de visualización de la cotización a tu tsx (inserta después del campo de entrada de cantidad):

            {/* Sección de cotización */}
            <div className="pt-4">
              {quoteLoading && <p>Cargando cotización...</p>}
              {quoteError && <p className="text-red-500">Error: {String(quoteError)}</p>}
              {quote && 'quote' in quote && (
                <div className="p-4 bg-gray-50 rounded-lg border border-gray-200">
                  <p className="font-semibold text-gray-700">Información de la cotización</p>
                  <p className="text-sm text-gray-600">Resolver: {quote.quote.resolverName}</p>
                  <p className="text-sm text-gray-600">Unidades Bid: {fromBaseUnits(quote.quote.bidUnits, fromAsset?.meta?.decimals)}  {fromAsset?.meta?.symbol}</p>
                  <p className="text-sm text-gray-600">Unidades Ask: {fromBaseUnits(quote.quote.askUnits, toAsset?.meta?.decimals)} {toAsset?.meta?.symbol}</p>
                </div>
              )}
            </div>

Cada vez que el usuario cambie el token o la cantidad, useRfq se actualiza automáticamente la cotización.

---

6. Construir una transacción y enviarla

Una vez que tengamos una cotización, podemos construir la transacción que ejecutará el intercambio. Usaremos el useOmniston hook para acceder a la instancia de Omniston y construir la transacción.

Reemplaza las importaciones de @tonconnect/ui-react y @ston-fi/omniston-sdk-react con:

import { TonConnectButton, useTonAddress, useTonConnectUI } from "@tonconnect/ui-react";
import {
  useRfq,
  SettlementMethod,
  Blockchain,
  GaslessSettlement,
  useOmniston,
  type QuoteResponseEvent_QuoteUpdated,
} from "@ston-fi/omniston-sdk-react";

Añade los hooks de conexión de la billetera y la instancia de omniston:

function App() {  
  // ... variables de estado existentes ...
  const walletAddress = useTonAddress();
  const [tonConnect] = useTonConnectUI();
  const omniston = useOmniston();

Crea la función de construcción de la transacción:

  // ... después del hook useRfq ...
  async function buildTx(willTradedQuote: QuoteResponseEvent_QuoteUpdated | undefined) {
    if (!willTradedQuote || !walletAddress) {
      alert("Por favor, conecta tu billetera y asegúrate de que haya una cotización válida cargada.");
      return null;
    }

    try {
      const tx = await omniston.buildTransfer({
        quote: willTradedQuote.quote,
        sourceAddress: {
          blockchain: Blockchain.TON,
          address: walletAddress, // la billetera que envía el token ofertado
        },
        destinationAddress: {
          blockchain: Blockchain.TON,
          address: walletAddress, // la misma billetera que recibe el token solicitado
        },
        gasExcessAddress: {
          blockchain: Blockchain.TON,
          address: walletAddress, // el gas sobrante vuelve al remitente
        },
        useRecommendedSlippage: false, // Usar el deslizamiento recomendado de la cotización
      });

      return tx.ton?.messages || [];
    } catch (err) {
      console.error("Error al construir la transacción:", err);
      alert("No se pudo construir la transacción. Revisa la consola para más detalles.");
      return null;
    }
  }

Añade la función de ejecución del intercambio:

  async function handleSwap() {
    if (!quote || quote.type !== 'quoteUpdated') {
      alert("No hay una cotización válida disponible");
      return;
    }
    const willTradedQuote = quote;
    const messages = await buildTx(willTradedQuote);
    if (!messages) return;
    
    try {
      await tonConnect.sendTransaction({
        validUntil: Date.now() + 1000000,
        messages: messages.map((message) => ({
          address: message.targetAddress,
          amount: message.sendAmount,
          payload: message.payload,
        })),
      });
    } catch (err) {
      console.error("Error al enviar la transacción:", err);
      alert("No se pudo enviar la transacción. Revisa la consola para más detalles.");
    }
  }

Añade el botón Ejecutar intercambio (insertar después en la sección de cotización):

        {quote && 'quote' in quote && (
        <>
          <div className="p-4 bg-gray-50 rounded-lg border border-gray-200">
            <p className="font-semibold text-gray-700">Información de la cotización</p>
            <p className="text-sm text-gray-600">Resolver: {quote.quote.resolverName}</p>
            <p className="text-sm text-gray-600">Unidades Bid: {fromBaseUnits(quote.quote.bidUnits, fromAsset?.meta?.decimals)}  {fromAsset?.meta?.symbol}</p>
            <p className="text-sm text-gray-600">Unidades Ask: {fromBaseUnits(quote.quote.askUnits, toAsset?.meta?.decimals)} {toAsset?.meta?.symbol}</p>
          </div>
          <button
            onClick={handleSwap}
            className="mt-4 w-full bg-indigo-500 hover:bg-indigo-600 text-white font-medium py-3 px-4 rounded-lg transition-all"
          >
            Ejecutar intercambio
          </button>
        </>
      )}

---

7. Rastrear tu operación

7.1 Instalar el paquete TON

Rastrearemos las operaciones usando el useTrackTrade hook de @ston-fi/omniston-sdk-react. Primero, asegúrate de tener el @ton/ton paquete instalado si aún no lo has hecho:

pnpm add @ton/ton

7.2 Uso del hook useTrackTrade

Después de haber construido y enviado la transacción de intercambio, puedes rastrear su estado con useTrackTrade. Este hook toma el quoteId de la operación, la dirección de tu billetera y el hash de la transacción saliente. Comprueba periódicamente el estado on-chain de la operación, permitiéndote saber si está pendiente, liquidada o parcialmente ejecutada.

Reemplaza las importaciones de @ton/ton y @ston-fi/omniston-sdk-react para el seguimiento de la operación:

import {
  useRfq,
  SettlementMethod,
  Blockchain,
  GaslessSettlement,
  useOmniston,
  useTrackTrade,
  type QuoteResponseEvent_QuoteUpdated,
  type TradeStatus,
} from "@ston-fi/omniston-sdk-react";
import { TonClient, Address, Cell, beginCell, storeMessage } from "@ton/ton";

Añade variables de estado para el seguimiento:

function App() {
  // ... variables de estado existentes ...
  const [outgoingTxHash, setOutgoingTxHash] = useState("");
  const [tradedQuote, setTradedQuote] = useState<QuoteResponseEvent_QuoteUpdated | null>(null);

Restablece el estado de seguimiento cuando cambien las entradas:

  // Restablecer outgoingTxHash y tradedQuote cuando cambien las entradas
  useEffect(() => {
    setTradedQuote(null);
    setOutgoingTxHash("");
  }, [fromAsset, toAsset, amount]);

Actualiza el hook useRfq para dejar de obtener cotizaciones durante la ejecución de la operación:

  const {
    data: quote,
    isLoading: quoteLoading,
    error: quoteError,
  } = useRfq({
    // ... configuración existente de useRfq ...
  }, {
    enabled:
      !!fromAsset?.contractAddress &&
      !!toAsset?.contractAddress &&
      amount !== "" &&
      // añade esto para dejar de obtener nuevas cotizaciones cuando hagamos una transacción
      !outgoingTxHash,
  });

Configura el hook de seguimiento de la operación:

  const {
    isLoading: trackingLoading,
    error: trackingError,
    data: tradeStatus,
  } = useTrackTrade({
    quoteId: tradedQuote?.quote?.quoteId || '',
    traderWalletAddress: {
      blockchain: Blockchain.TON,
      address: walletAddress || '',
    },
    outgoingTxHash,
  }, {
    enabled: !!tradedQuote?.quote?.quoteId && !!walletAddress && !!outgoingTxHash,
  });

Añade una función auxiliar para traducir los resultados de la operación:

  // Función para traducir el resultado de la operación a texto legible
const getTradeResultText = (status: TradeStatus) => {
    if (!status?.status?.tradeSettled) return "";
    
    const result = status.status.tradeSettled.result;
    switch (result) {
      case "TRADE_RESULT_FULLY_FILLED":
        return "La operación se completó con éxito y se ejecutó completamente";
      case "TRADE_RESULT_PARTIALLY_FILLED":
        return "La operación se ejecutó parcialmente - algo salió mal";
      case "TRADE_RESULT_ABORTED":
        return "La operación fue abortada";
      case "TRADE_RESULT_UNKNOWN":
      case "UNRECOGNIZED":
      default:
        return "Resultado de operación desconocido";
    }
  };

Añade funciones de utilidad para la extracción del hash de la transacción:

    // Función de utilidad para reintentar una operación asíncrona
    const retry = async (fn: () => Promise<string>, { retries = 5, delay = 1000 }): Promise<string> => {
      try {
        return await fn();
      } catch (error) {
        if (retries === 0) throw error;
        await new Promise(resolve => setTimeout(resolve, delay));
        return retry(fn, { retries: retries - 1, delay });
      }
    };

    const getTxByBOC = async (exBoc: string, walletAddress: string): Promise<string> => {
      if (!exBoc || !walletAddress) {
        throw new Error('Faltan parámetros requeridos para el seguimiento de la transacción');
      }
  
      const client = new TonClient({
        endpoint: 'https://toncenter.com/api/v2/jsonRPC'
      });
  
      const myAddress = Address.parse(walletAddress);
  
      return retry(async () => {
        const transactions = await client.getTransactions(myAddress, {
          limit: 5,
        });
  
        for (const tx of transactions) {
          const inMsg = tx.inMessage;
          if (inMsg?.info.type === 'external-in') {
            const inBOC = inMsg?.body;
            if (typeof inBOC === 'undefined') {
              continue;
            }
  
            const extHash = Cell.fromBase64(exBoc).hash().toString('hex');
            const inHash = beginCell().store(storeMessage(inMsg)).endCell().hash().toString('hex');
  
            if (extHash === inHash) {
              return tx.hash().toString('hex');
            }
          }
        }
        throw new Error('Transacción no encontrada');
      }, { retries: 30, delay: 1000 });
    }; 

Actualiza la función handleSwap para capturar los detalles de la transacción:

 async function handleSwap() {
    if (!quote || quote.type !== 'quoteUpdated') {
      alert("No hay una cotización válida disponible");
      return;
    }
    const messages = await buildTx(quote);
    if (!messages) return;
    
    try {
      setTradedQuote(quote);

      const res = await tonConnect.sendTransaction({
        validUntil: Date.now() + 1000000,
        messages: messages.map((message) => ({
          address: message.targetAddress,
          amount: message.sendAmount,
          payload: message.payload,
        })),
      });

      const exBoc = res.boc;
      const txHash = await getTxByBOC(exBoc, walletAddress);
      setOutgoingTxHash(txHash);

    } catch (err) {
      setTradedQuote(null);
      console.error("Error al enviar la transacción:", err);
      alert("No se pudo enviar la transacción. Revisa la consola para más detalles.");
    }
  }

Añade la visualización del estado de la operación (insertar después de la línea divisoria):

        {/* Estado de la operación */}
        {/* justo después de <div className="h-px bg-gray-200 w-full my-4"></div> */}
        <div className="mt-4 p-4 bg-gray-50 rounded-lg border border-gray-200">
          {trackingLoading && <p className="text-sm text-blue-600">Rastreando operación...</p>}
          {trackingError && (
            <p className="text-sm text-orange-600">Error al rastrear la operación: {String(trackingError)}</p>
          )}
          {tradeStatus?.status?.tradeSettled && (
            <p className="text-sm text-green-600">
              Resultado de la operación: {getTradeResultText(tradeStatus)}
            </p>
          )}
        </div>

Actualiza la visualización de errores en la sección de cotización

        {quoteError && !outgoingTxHash && <p className="text-red-500">Error: {String(quoteError)}</p>}

---

8. Probar tu intercambio

1. Inicia el servidor de desarrollo:

pnpm dev

1. Abre tu aplicación en el navegador en http://localhost:5173.

2. Conecta tu billetera TON mediante el botón "Connect Wallet".

3. Selecciona tokens en los menús desplegables e introduce una cantidad.

4. Omniston obtiene y muestra automáticamente una cotización. Confirma que sea válida.

5. Haz clic en "Execute Swap" para finalizar la transacción. Apruébala en tu billetera.

6. Una vez que el intercambio se complete on-chain, los saldos de tu billetera deberían actualizarse en consecuencia.

---

9. Conclusión

¡Felicidades! Has creado una aplicación mínima de React + Vite con Tailwind CSS que:

• Se conecta a una billetera TON usando TonConnect.

• Obtiene dinámicamente los tokens disponibles desde STON.fi.

• Solicita cotizaciones en tiempo real (RFQs) desde Omniston automáticamente.

• Construye y envía transacciones de intercambio.

Siéntete libre de ampliar esta demo con:

• Ajustes personalizados de deslizamiento.

• Mejor manejo de errores y notificaciones de éxito.

• Métodos de liquidación adicionales o lógica entre cadenas.

• Aprende cómo añadir comisiones de referencia a tus intercambios de Omniston leyendo el guía de comisiones por referidos.

¡Feliz desarrollo con Omniston!

10. Demostración en vivo

Con esta demo de Replit, puedes:

• Abrir el proyecto directamente en tu navegador

• Hacer un fork del Replit para crear tu propia copia

• Ejecutar la aplicación para verla en acción

• Explorar y modificar el código para aprender cómo funciona

• Experimentar con diferentes funciones y cambios en la interfaz

Como alternativa, puedes ejecutar este ejemplo localmente clonando el repositorio de GitHub:

git clone https://github.com/mrruby/omniston-swap-app.git
cd omniston-swap-app
pnpm install
pnpm dev

Esto iniciará el servidor de desarrollo y podrás acceder a la app en http://localhost:5173.

11. Aplicación de ejemplo avanzada

Para quienes buscan un enfoque más avanzado y rico en funciones, también tenemos una aplicación de demostración de Omniston en Next.js que:

• Usa Next.js para un framework escalable

• Utiliza hooks y providers para una arquitectura elegante

• Demuestra un mejor manejo de errores, una gestión de estado robusta y funciones adicionales de STON.fi y Omniston

Puedes explorar el código en nuestro repositorio:

Aplicación de demostración del SDK de Omniston en Next.js

O verla en acción en nuestra demo en vivo:

Aplicación de demostración de Omniston

12. Uso de agentes de IA para la implementación automatizada

Para los desarrolladores que buscan acelerar su proceso de desarrollo, pueden aprovechar agentes de programación de IA para implementar automáticamente la funcionalidad de intercambio de Omniston descrita en esta guía. Aunque mostramos Gemini CLI en nuestro ejemplo (debido a su generoso plan gratuito), puedes usar cualquier asistente de programación de IA como Claude Code, GitHub Copilot, Cursor Agent, o herramientas similares.

También puedes seguir una guía grabada:

12.1 ¿Por qué agentes de IA?

Los modernos agentes de programación de IA pueden:

• Entender documentación compleja e implementar funciones completas

• Configurar automáticamente la estructura del proyecto y las dependencias

• Gestionar errores comunes de configuración y puesta en marcha

• Proporcionar implementaciones funcionales en minutos en lugar de horas

12.2 Configuración con Gemini CLI (ejemplo)

Haremos la demostración con Gemini CLI, pero el enfoque funciona con cualquier agente de IA que pueda leer documentación y ejecutar comandos.

12.2.1 Instalación de Gemini CLI

1. Instala Gemini CLI siguiendo las instrucciones en: https://github.com/google-gemini/gemini-cli

2. Autentícate con tu cuenta de Google cuando se te solicite. El nivel gratuito incluye:

   • 60 solicitudes al modelo por minuto

   • 1.000 solicitudes al modelo por día

12.2.2 Configuración de la guía de implementación

1. Descarga el GEMINI.md archivo desde el gist: https://gist.github.com/mrruby/311a9d96f12bc7303bb1046dc92092b3

2. Renombra el archivo según tu agente de IA:

   • Para Gemini CLI: Usa GEMINI.md tal cual (no es necesario renombrarlo)

   • Para Claude Code: Renombra GEMINI.md to CLAUDE.md

   • Para otros agentes de IA (GitHub Copilot, Cursor, etc.): Renombra GEMINI.md to AGENTS.md

3. Crea un nuevo directorio para tu proyecto y coloca el archivo de guía dentro de él:

   mkdir my-omniston-app
   cd my-omniston-app
   # Coloca aquí el archivo renombrado (GEMINI.md, CLAUDE.md o AGENTS.md)

12.2.3 Ejecutar la implementación automatizada

1. Desde el directorio de tu proyecto, ejecuta Gemini CLI:

   gemini

2. Cuando se abra la interfaz de la CLI, escribe:

   Implementa Omniston de acuerdo con la Guía rápida de Omniston

3. El agente de IA:

   • Pedirá permiso para usar comandos como pnpm, npm, etc.

   • Creará automáticamente la estructura del proyecto

   • Instalará todas las dependencias necesarias

   • Implementa la funcionalidad completa de intercambio

   • Configurará los componentes de la interfaz y el estilo

4. Si ocurre algún error durante el proceso:

   • Simplemente vuelve a pegar el mensaje de error al agente de IA

   • Analizará y corregirá el problema automáticamente

   • En la mayoría de los casos, la implementación se completa correctamente de una sola vez

12.3 Uso de otros agentes de IA

El mismo enfoque funciona con otros asistentes de programación de IA:

• Gemini CLI: Descarga GEMINI.md desde el gist y úsalo tal cual

• Claude Code: Descarga GEMINI.md desde el gist y renómbralo a CLAUDE.md, luego colócalo en tu proyecto y pide a Claude Code que implemente la guía

• GitHub Copilot: Descarga GEMINI.md desde el gist y renómbralo a AGENTS.md, abre la guía en tu editor y usa Copilot Chat para implementar paso a paso

• Cursor Agent: Descarga GEMINI.md desde el gist y renómbralo a AGENTS.md, carga la documentación y solicita la implementación completa mediante el modo agente de Cursor

• Otras herramientas de IA: Descarga GEMINI.md y renómbralo a AGENTS.md para compatibilidad con la mayoría de los asistentes de IA

Nota: El gist contiene GEMINI.md que funciona directamente con Gemini CLI. Para Claude Code, renómbralo a CLAUDE.md. Para otros agentes de IA (GitHub Copilot, Cursor, etc.), renómbralo a AGENTS.md para una mejor compatibilidad.

12.4 Beneficios de usar agentes de IA

• Velocidad: Obtén una implementación funcional en minutos en lugar de horas

• Precisión: Los agentes de IA siguen la guía rápida con exactitud

• Gestión de errores: Resuelven automáticamente la mayoría de los problemas comunes de configuración

• Herramienta de aprendizaje: Observa cómo se desarrolla la implementación paso a paso

• Personalización: Después de la configuración inicial, puedes modificar el código generado para adaptarlo a tus necesidades específicas

• Rentable: Muchas herramientas de programación con IA ofrecen niveles gratuitos (como Gemini CLI) o están incluidas en suscripciones existentes

12.5 Mejores prácticas

1. Revisar el código: Revisa siempre el código generado por IA antes de usarlo en producción

2. Entender el flujo: Usa el código generado como una herramienta de aprendizaje para comprender el protocolo de Omniston

3. Personalizar: Adapta el código generado a tus requisitos específicos

4. Probar a fondo: Prueba la implementación con cantidades pequeñas antes de procesar transacciones más grandes

5. Seguridad: Nunca confirmes claves de API ni mnemónicos en el control de versiones

Este enfoque es especialmente útil para:

• Desarrolladores nuevos en el ecosistema TON

• Prototipado rápido y pruebas de concepto

• Aprender con un ejemplo de una implementación funcional

• Evitar errores comunes de configuración y problemas de puesta en marcha

• Explorar rápidamente diferentes enfoques de implementación