> 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/es/seccion-para-desarrolladores/widget.md).

# Widget de STON.fi

El widget STON.fi es una interfaz de intercambio lista para usar para tu app o sitio web. Solo incrusta nuestro script ligero y tus usuarios obtienen funcionalidad completa de intercambio al instante, mientras tú ganas comisiones por cada intercambio.

<figure><img src="/files/38f42afea1cb742f38f862a9e8f704064bb3d03e" alt=""><figcaption></figcaption></figure>

Configuración rápida, sin sobrecarga. Empieza con la configuración predeterminada o personalízala para que coincida con tu marca. Se entrega mediante un paquete alojado en CDN para un rendimiento máximo. Se ve y se comporta como una parte nativa de tu interfaz.

### Pruébalo con Lovable

¿Quieres ver el widget en acción rápidamente? Usa Lovable para generar un ejemplo funcional:

<a href="https://lovable.dev/?autosubmit=true#prompt=Build%20a%20simple%20webpage%20with%20the%20STON.fi%20swap%20widget%20integrated.%20No%20need%20to%20style%20it%20fancy.%20I%20just%20need%20a%20simple%20page%20with%20TON%20token%20swaps%20via%20the%20widget.%20After%20implementation%2C%20inform%20the%20user%20that%20if%20they%20see%20%27Failed%20to%20load%20Manifest%3A%20404%27%20that%27s%20because%20they%20are%20in%20Lovable%20website%20and%20testing%20it%20in%20preview%20mode.%20Tell%20them%20to%20publish%20the%20app%2C%20then%20manually%20replace%20the%20URL%20in%20manifest.json%20with%20the%20published%20URL%2C%20and%20then%20publish%20the%20app%20again%20after%20changes.%20If%20the%20user%20is%20in%20free%20credit%20mode%20and%20can%27t%20manually%20change%20the%20manifest%2C%20they%20should%20prompt%20and%20paste%20the%20URL%20so%20the%20agent%20will%20replace%20the%20manifest%20URL.%20Then%20tell%20them%20to%20go%20to%20the%20published%20URL%20to%20test%20the%20connection.%20Documentation%20is%20available%20at%20https://docs.ston.fi/developer-section/widget/widget" class="button primary">🚀 Crea con Lovable</a>

Haz clic en el botón de arriba para generar automáticamente una página web funcional con el widget de intercambio STON.fi integrado.

> 🚀 **Nota:** Si ves 'Failed to load Manifest: 404', es porque estás en el sitio web de Lovable y lo pruebas en modo de vista previa. Publica la app, reemplaza la URL dentro de `manifest.json` con la URL publicada, y luego vuelve a publicar la app después de los cambios. Si estás en modo de créditos gratis y no puedes cambiar el manifest manualmente, pide y pega la URL para que el agente la reemplace. Luego ve a la URL publicada para probar la conexión.

También puedes seguir un recorrido grabado:

{% embed url="<https://www.youtube.com/watch?v=zESpTWxka2s>" %}

### Intégralo tú mismo

Si quieres integrar el widget tú mismo, continúa leyendo abajo.

Dos formas de incrustarlo:

1. **Mediante el cargador de NPM** (para compilaciones modernas): Deja que el cargador obtenga el paquete optimizado en tiempo de ejecución.
2. **Script CDN directo** (por simplicidad): Inserta una línea de código en tu proyecto.

Ambos métodos exponen el mismo `OmnistonWidget` constructor, dándote control total.

* **`@ston-fi/omniston-widget-loader`** ([npm](https://www.npmjs.com/package/@ston-fi/omniston-widget-loader/v/latest)) – paquete npm que descarga el paquete CDN cuando llamas a `load()`.
* **Script CDN** – opción sin compilación que expone `window.OmnistonWidget` en navegadores modernos:

```html
  <script src="https://widget.ston.fi/v0/index.js"></script>
```

Las URL de CDN están **versionadas por versión mayor** (`/v0/`, `/v1/`, ...). Recibes todas las actualizaciones compatibles dentro de una versión principal; aumenta la ruta principal para adoptar cambios incompatibles.

## Inicio rápido en 30 segundos

1. Aloja tu [manifiesto de TON Connect](https://docs.ton.org/v3/guidelines/ton-connect/creating-manifest) en tu dominio.
2. Elige CDN (sin compilación) o npm (frameworks).
3. Pega un fragmento para montar el widget; consulta la [Guía completa del widget](/es/seccion-para-desarrolladores/widget/widget.md) para ver ejemplos completos.

**Opción A — CDN (sin compilación)**

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>STON.fi Swap Widget vía CDN</title>
  </head>
  <body>
    <div id="omniston-widget-container" style="max-width: 420px; margin: 0 auto;"></div>

    <script src="https://widget.ston.fi/v0/index.js"></script>
    <script>
      const widget = new window.OmnistonWidget({
        tonconnect: {
          type: 'standalone',
          options: {
            // ver https://docs.ton.org/ecosystem/ton-connect/manifest
            manifestUrl: 'https://[myapp.com]/tonconnect-manifest.json',
          },
        },
        widget: {
          // Opcional: defaultBidAsset: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // TON
          // Opcional: defaultAskAsset: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
        },
      });

      widget.mount(document.querySelector("#omniston-widget-container"));
    </script>
  </body>
</html>
```

**Opción B — npm (React, TON Connect UI integrada)**

```tsx
import { useEffect, useRef } from 'react';
import { TonConnectUIProvider, TonConnectButton, useTonConnectUI } from '@tonconnect/ui-react';
import omnistonWidgetLoader, { type OmnistonWidget } from '@ston-fi/omniston-widget-loader';

function SwapWidget() {
  const [tonconnect] = useTonConnectUI();
  const containerRef = useRef<HTMLDivElement | null>(null);
  const widgetRef = useRef<OmnistonWidget | null>(null);

  useEffect(() => {
    let isMounted = true;

    omnistonWidgetLoader.load().then((OmnistonWidgetConstructor) => {
      if (!isMounted || !containerRef.current || !tonconnect) return;

      widgetRef.current = new OmnistonWidgetConstructor({
        tonconnect: {
          type: 'integrated',
          instance: tonconnect,
        },
        widget: {
          defaultBidAsset: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // TON
          defaultAskAsset: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
        },
      });

      widgetRef.current.mount(containerRef.current);
    });

    return () => {
      isMounted = false;
      widgetRef.current?.unmount();
      widgetRef.current = null;
    };
  }, [tonconnect]);

  return (
    <div
      style={{
        minHeight: '100vh',
        padding: '2rem',
        display: 'flex',
        flexDirection: 'column',
        gap: 16,
        alignItems: 'center',
        width: '100%',
      }}
    >
      <h1 style={{ textAlign: 'center', marginBottom: '1rem' }}>Widget de intercambio STON.fi</h1>
      <div style={{ textAlign: 'center', marginBottom: '1.5rem' }}>
        <TonConnectButton />
      </div>
      <div
        ref={containerRef}
        style={{ width: '100%', maxWidth: 500, margin: '0 auto' }}
      />
    </div>
  );
}

export default function App() {
  return (
    <TonConnectUIProvider
      // ver https://docs.ton.org/ecosystem/ton-connect/manifest
      manifestUrl="https://[myapp.com]/tonconnect-manifest.json"
    >
      <SwapWidget />
    </TonConnectUIProvider>
  );
}
```

Consulta la [Guía completa del widget](/es/seccion-para-desarrolladores/widget/widget.md) para ver ejemplos completos de CDN, React y vanilla.

## Constructor visual para el STON.fi Swap Widget

**Personalización rápida sin código:** Usa nuestro constructor visual de widgets en [widget.ston.fi/constructor](https://widget.ston.fi/constructor) para configurar tu widget interactivamente.

<figure><img src="/files/9446ca029342e4e538c0422069ec33a97e81ff23" alt=""><figcaption></figcaption></figure>

El constructor ofrece:

* **Personalización del tema** — Empieza con claro u oscuro y adáptalo a tu marca
* **Control de la lista de activos** — Usa los activos predeterminados, añade los tuyos o reemplaza la lista por completo
* **Comisiones de referido** — Configura tu dirección de referidor y comisión
* **Exportación de código** — Copia fragmentos de CSS y JS listos para usar

¿Prefieres hacerlo en código? Consulta **Configurar en código** abajo.

## Configurar en código

Todas las opciones del constructor visual se asignan directamente al `OmnistonWidget` objeto de configuración. Tú controlas cuatro áreas principales:

### 1. Comisiones de referidos

Establece ambos `referrerAddress` como `referrerFeeBps` para ganar entre 0,01 % y 1 % (1–100 bps) en cada swap. Consulta la [guía de comisiones de referidos](/es/seccion-para-desarrolladores/omniston/referral-fees.md) para detalles de pago y mejores prácticas.

### 2. Lista de activos

El widget incluye valores predeterminados sensatos y solo requiere la URL de tu manifiesto de TON Connect. Para anulaciones opcionales de activos y la tabla completa de configuración, consulta [si tu app ya tiene una instancia de TON Connect.](/es/seccion-para-desarrolladores/widget/widget.md#configuration-options).

### 3. Tema (variables CSS)

Anula las propiedades personalizadas CSS en el contenedor que pasas a `widget.mount(...)` para alinear el widget con tu marca. Consulta [Personaliza los estilos del widget](/es/seccion-para-desarrolladores/widget/widget.md#customize-widget-styles) para la lista completa de variables y ejemplos de estilo.

### 4. Modos de TON Connect

* **`independiente`** – El widget gestiona TON Connect solo con la URL de tu manifiesto.
* **`integrado`** – Reutiliza una instancia existente de TON Connect de tu aplicación.

Para ejemplos de integración, advertencias sobre múltiples instancias y la configuración completa, consulta la sección de TON Connect en el [Guía completa del widget](/es/seccion-para-desarrolladores/widget/widget.md).

### Funciones avanzadas

La distribución por CDN también está disponible como una opción sin compilación; consulta la [sección de distribución CDN](/es/seccion-para-desarrolladores/widget/widget.md#cdn-distribution-no-bundler-required) en [Avanzado: eventos del ciclo de vida y montaje/desmontaje manual](/es/seccion-para-desarrolladores/widget/widget.md#advanced-lifecycle-events-and-manual-mountunmount) para detalles de implementación.

## Próximos pasos

Continúa con la [Guía completa del widget](/es/seccion-para-desarrolladores/widget/widget.md) para una instalación, configuración, uso de CDN, integración de TON Connect, configuración de la comisión del integrador, temas y eventos del ciclo de vida exhaustivos.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ston.fi/es/seccion-para-desarrolladores/widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.