Resumen general (Swap)

Comprender las operaciones de swap en el protocolo Omniston: ejecuta swaps de tokens eficientes a través de DEX de la blockchain TON

💡 Enfoque recomendado: Para la mayoría de las integraciones, recomendamos usar nuestros SDK de Node.js o SDK de React. Los SDK gestionan automáticamente las conexiones WebSocket, el streaming de cotizaciones, la construcción de transacciones y el manejo de errores. La documentación a continuación es para desarrolladores que necesitan acceso al protocolo de bajo nivel o que están implementando en otros lenguajes.

Puntos finales base de WebSocket (JSON-RPC)

Producción: wss://omni-ws.ston.fi Sandbox: wss://omni-ws-sandbox.ston.fi

Use el sandbox solo para desarrollo/pruebas.

Método de liquidación de swap

Liquidación de la operación mediante swap directo usando contratos de terceros.

Actores

Trader

Un usuario del protocolo que realiza el intercambio de tokens.

Resolver

Servicio que proporciona una tasa de intercambio de tokens, también conocido como Creador de mercado.

API de WebSocket

Nota: Los detalles de la API WebSocket a continuación se proporcionan como referencia. Si está implementando una integración de bajo nivel, consulte nuestra Guía rápida de Python para un ejemplo completo y funcional. También puede explorar el repositorio SDK de código abierto para estudiar el código real de implementación de bajo nivel.

Tipos de datos usados:

• Blockchain Número. Código de blockchain según lo definido por SLIP-044. (https://github.com/satoshilabs/slips/blob/master/slip-0044.md) Para TON, es 607.

• Address Objeto. Consta de dos campos:

• blockchain - blockchain del activo,

• dirección - dirección de los activos, monederos en el Blockchain.

Por ejemplo:

{
  "blockchain": 607,
  "address": "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO"
}

• Cantidad Cadena. Cantidad de activos en unidades.

• SettlementMethod Número. El método de liquidación de la operación. Valor del enum de métodos de liquidación. Actualmente, solo admite Swap método de liquidación, que es 0.

• Protocolo\

  • API de WebSocket usa un código numérico:

    • StonFiV1 = 1

    • StonFiV2 = 2

    • DeDust = 3

    • TonCo = 4

Para uso de gRPC, consulte la Guía de integración del Resolver.

• GaslessSettlement\

  • API de WebSocket usa un código numérico:

    • GASLESS_SETTLEMENT_PROHIBITED = 0 — La liquidación sin gas no está soportada o está prohibida por el trader.

    • GASLESS_SETTLEMENT_POSSIBLE = 1 — La liquidación sin gas está permitida si el resolver la soporta.

    • GASLESS_SETTLEMENT_REQUIRED = 2 — La liquidación sin gas es obligatoria.

• Número Número entero.

• RequestSettlementParams Objeto. Parámetros adicionales para la solicitud de cotización (RFQ):

  • max_price_slippage_bps: Deslizamiento máximo de precio, en puntos básicos (0,01%). Por ejemplo, 100 = 1% de deslizamiento.

  • max_outgoing_messages: Número máximo de mensajes salientes admitidos por el monedero. Para la blockchain TON, esto es 4 por defecto si se omite.

  • gasless_settlement: Valor del enum GaslessSettlement que especifica la preferencia del trader para la liquidación sin gas (consulte GaslessSettlement arriba).

  • flexible_referrer_fee: Marca booleana que permite a los resolvers reducir la comisión efectiva del referidor por debajo de referrer_fee_bps cuando eso genera una mejor tasa de swap. El valor predeterminado es false. Consulte Comisión flexible del referidor para más detalles.

  Nota: Estos parámetros son ajustes generales de RFQ y pueden usarse en distintos métodos de liquidación. No son específicos de ningún método de liquidación en particular.

• SwapSettlementParams Objeto. Parámetros de liquidación específicos del método de liquidación swap. Este tipo se usa en el campo params de Quote cuando el método de liquidación es swap. Contiene:

  • routes: Matriz de SwapRoute objetos que definen los posibles caminos para el swap.

  Cada SwapRoute consta de:

  • steps: Matriz de SwapStep objetos que describen cada paso en la ruta de swap

  • gas_budget: Cadena que indica el presupuesto de gas para completar la transferencia

  Cada SwapStep contiene:

  • bid_asset_address: Objeto Address del activo ofertado

  • ask_asset_address: Objeto Address del activo solicitado

  • chunks: Matriz de SwapChunk objetos que describen cada paso en la ruta de swap.

  Nota sobre Steps vs. Chunks:

  • Un "step" transforma un activo en otro (por ejemplo, TON → USDC).

  • Cada paso puede contener uno o más "chunks", y cada uno representa una operación de swap individual para ese paso.

  • En la blockchain TON, normalmente verá exactamente una chunk por paso. Mantenemos la capacidad de especificar varios chunks en un solo paso para otras blockchains si es necesario.

  Cada SwapChunk representa una sola operación de swap:

  • protocol: Protocolo usado para esta operación de swap. En este documento, se usan códigos numéricos para la API WebSocket. Para uso de gRPC, consulte Guía de integración del Resolver.

  • bid_amount: Cantidad del activo ofertado

  • ask_amount: Cantidad esperada del activo solicitado

  • extra_version: Actualmente, solo 1 es compatible.

  • extra: Matriz de bytes usada por el protocolo subyacente para coordinar el swap (codificada en base64 en JSON). Consulte Documento de extras de Swap

• quote_id Cadena. Un identificador de 32 bytes de la cotización.

Métodos de la API

Cada nombre de método contiene la versión de la API. La versión más reciente es v1beta7. Las versiones anteriores pueden ser compatibles por retrocompatibilidad.

Método de suscripción quote

Le permite crear una nueva solicitud de cotización (RFQ).

Cuando envía una solicitud de cotización, el servidor hará lo siguiente:

1. Primero, enviará inmediatamente un mensaje QuoteRequestAck que contiene el rfq_id (una cadena hex SHA-256) que identifica de forma única su solicitud de cotización

2. Luego, comenzará a enviar eventos quote_updated de los resolvers a medida que las cotizaciones estén disponibles

Acepta los siguientes parámetros como entrada:

Nombre	Tipo	Descripción
bid_asset_address	Address	Dirección específica de la blockchain del activo ofertado.
ask_asset_address	Address	Dirección específica de la blockchain del activo solicitado.
amount	Cantidad	Ya sea la cantidad del activo ofertado o del activo solicitado: bid_units - La cantidad del activo ofertado que el trader quiere pagar, incluidas todas las comisiones. ask_units - La cantidad del activo solicitado que el trader quiere recibir después de todas las comisiones.
referrer_address	Address	La dirección del referidor que recibirá las comisiones o una cadena vacía si no se especifica referidor.
referrer_fee_bps	Número	La cantidad de comisiones requerida por el referidor en puntos básicos (1/10000 o 0,01%)
settlement_methods	Array(SettlementMethod)	Métodos admitidos de liquidación del swap. El protocolo limita los métodos de liquidación en las cotizaciones a los métodos especificados. Diferentes combinaciones de cadenas de bid y ask pueden admitir distintos métodos.

Ejemplo:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "v1beta7.quote",
  "params": {
    "bid_asset_address": {
      "blockchain": 607,
      "address": "EQDB8JYMzpiOxjCx7leP5nYkchF72PdbWT1LV7ym1uAedINh"
    },
    "amount": {
      "ask_units": "1000"
    },
    "ask_asset_address": {
      "blockchain": 607,
      "address": "EQCH-yP4S3nA_j7K7EIV1QIhVTWMyNJfxeYzacUH76ks2hUF"
    },
    "referrer_address": {
      "blockchain": 607,
      "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
    },
    "referrer_fee_bps": 10,
    "settlement_methods": [0],
    "settlement_params": {
      "max_price_slippage_bps": 100,
      "max_outgoing_messages": 4,
      "gasless_settlement": 1,
      "flexible_referrer_fee": false
    }
  }
}

📘 Ejemplo práctico: Consulte el Guía rápida de Python para una implementación completa que muestra cómo solicitar cotizaciones, manejar respuestas, construir transacciones y ejecutar swaps. El código de Python puede adaptarse a cualquier lenguaje de programación.

Acuse de recibo de la solicitud de cotización

Al recibir su RFQ, el servidor responde inmediatamente con:

Nombre	Tipo	Descripción
rfq_id	Cadena	Cadena hex SHA-256 que identifica de forma única la RFQ

Este acuse confirma que su solicitud fue recibida y está siendo procesada.

Actualizaciones de cotización

Después del acuse, el canal comenzará a recibir eventos quote_updated de los resolvers, que consisten en un quote. Un Quote en el canal se actualiza si llega un acuerdo más rentable para el trader. El Quote incluye los siguientes campos:

Nombre	Tipo	Descripción
quote_id	Cadena	ID de la cotización generado por la plataforma (32 bytes)
resolver_id	Cadena	ID del Resolver
resolver_name	Cadena	Nombre del Resolver
bid_asset_address	Address	Dirección específica de la blockchain del activo ofertado.
ask_asset_address	Address	Dirección específica de la blockchain del activo solicitado.
bid_units	Cantidad	La cantidad del activo ofertado que el trader debe pagar, incluidas todas las comisiones.
ask_units	Cantidad	La cantidad del activo solicitado que el trader recibirá después de todas las comisiones.
referrer_address	Address	La dirección del referidor que recibirá las comisiones o una cadena vacía si no se especifica referidor.
referrer_fee_asset	Address	El activo de las comisiones que recibirá el referidor
referrer_fee_units	Número	La cantidad de comisiones que recibirá el referidor (en unidades de referrer_fee_asset)
protocol_fee_asset	Address	El activo de las comisiones cobradas por el protocolo (siempre jetton ASK)
protocol_fee_units	Número	La cantidad de comisiones cobradas por el protocolo (en unidades de protocol_fee_asset, que es jetton ASK).
quote_timestamp	Número	La marca de tiempo (segundos UTC) de la cotización enviada por el resolver.
trade_start_deadline	Número	Marca de tiempo máxima (segundos UTC) del inicio de la operación. El inicio de la operación se define como la recepción del activo ofertado por el contrato inteligente correspondiente. El resolver aún puede liquidar las operaciones iniciadas después de que venza este plazo, a su propia discreción.
estimated_gas_consumption	Número	Cantidad estimada de unidades de gas que se gastarán para realizar la operación
params	Objeto	Parámetros adicionales específicos del método de liquidación. Los detalles se ven a continuación

Para Swap método de liquidación el params es:

Nombre	Tipo	Descripción
routes	Array(SwapRoute)	Matriz de rutas de swap
min_ask_amount	Cantidad	Cantidad mínima a recibir (rellenada por el servicio Omniston)
recommended_min_ask_amount	Cantidad	Cantidad mínima recomendada (rellenada por el servicio Omniston)
recommended_slippage_bps	Número	Deslizamiento recomendado en puntos básicos

Objeto SwapRoute:

Nombre	Tipo	Descripción
steps	Array(SwapStep)	Matriz de pasos de swap
gas_budget	Cantidad	Cantidad de presupuesto de gas para completar la transferencia

Objeto SwapStep:

Nombre	Tipo	Descripción
bid_asset_address	Address	Dirección específica de la blockchain del activo ofertado.
ask_asset_address	Address	Dirección específica de la blockchain del activo solicitado.
chunks	Array(SwapChunk)	Matriz de chunks de swap

Objeto SwapChunk:

Nombre	Tipo	Descripción
protocol	Protocolo	Protocolo usado para esta operación de swap. En este documento, se usan códigos numéricos para la API WebSocket. Para uso de gRPC, consulte Guía de integración del Resolver.
bid_amount	Cantidad	La cantidad del activo ofertado que el trader debe pagar, incluidas todas las comisiones.
ask_amount	Cantidad	La cantidad esperada del activo solicitado que el trader recibirá después de todas las comisiones.
extra_version	Número	Actualmente, solo 1 es compatible. Los intentos de usar cualquier otra versión serán rechazados.
extra	bytes	Matriz de bytes usada por el protocolo subyacente para coordinar el swap (codificada en base64 en JSON). Consulte Documento de extras de Swap

Para más detalles sobre cómo completar o interpretar el campo extra para estos protocolos, consulte el (Documento de extras de Swap).

Ejemplo:

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "subscription": 608688935135881,
    "result": {
      "event": {
        "quote_updated": {
          "quote_id": "98616cab2097d3f9e64e9447f2f3b736",
          "bid_asset_address": {
            "blockchain": 607,
            "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
          },
          "ask_asset_address": {
            "blockchain": 607,
            "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
          },
          "bid_units": "100000",
          "ask_units": "33757",
          "referrer_address": {
            "blockchain": 607,
            "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
          },
          "referrer_fee_units": "0",
          "protocol_fee_units": "0",
          "quote_timestamp": 1723144166,
          "trade_start_deadline": 1723144766,
          "params": {
            "swap": {
              "routes": [
                {
                  "steps": [
                    {
                      "bid_asset_address": {
                        "blockchain": 607,
                        "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
                      },
                      "ask_asset_address": {
                        "blockchain": 607,
                        "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
                      },
                      "chunks": [
                        {
                          "protocol": "StonFiV1",
                          "bid_amount": "100000",
                          "ask_amount": "33757",
                          "extra_version": 1,
                          "extra": "SGVsbG8sIHRoaXMgaXMgYW4gZXhhbXBsZSBiYXNlNjQgZW5jb2RlZCBzdHJpbmcgZm9yIHRoZSBleHRyYSBmaWVsZC4="
                        }
                      ]
                    }
                  ],
                  "gas_budget": "300000000"
                }
              ]
            }
          }
        }
      }
    }
  }
}

Método de suscripción trade.track

Método que le permite seguir el estado de un intercambio de tokens.

Acepta los siguientes parámetros como entrada:

Nombre	Tipo	Descripción
quote_id	Cadena	ID de la cotización (32 bytes)
trader_wallet_address	Address	La dirección de la cartera del trader que inició la transacción
outgoing_tx_hash	Cadena	Hash de la transacción que inició la operación

Ejemplo:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "v1beta7.trade.track",
  "params": {
    "quote_id": "cf1f9bf159a26a7be14616da637882df",
    "trader_wallet_address": {
      "blockchain": 607,
      "address": "0QCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYsMs"
    },
    "outgoing_tx_hash": "b35fb27b0aa9867e4072905cb967c3d08c6be8b0a66398fe08d2a72cb7c45082"
  }
}

El canal comenzará a recibir registros sobre el estado actual de la transferencia. Los siguientes estados están disponibles:

Estado	Descripción	Campos adicionales
awaiting_transfer	Esperando a que el trader inicie la operación.
transferring	Transacción inicial encontrada, esperando a que se complete la transferencia de fondos.
swapping	(solo método SWAP) Esperando transacciones de swap en los pools.	routes - Información sobre el llenado parcial de la operación. Matriz de RouteStatus.
awaiting_fill	(solo ESCROW / HTLC) Esperando a que se complete la operación.
claim_available	(solo HTLC) El depósito del resolver puede reclamarse.
refund_available	(ESCROW / HTLC) El tiempo de espera del depósito ha expirado, es necesario reembolsarlo.
receiving_funds	Se encontró la transacción con fondos entrantes, esperando a que se mine.	routes - Información sobre el llenado parcial de la operación.
trade_settled	La operación se ha completado (llenada total o parcialmente o abortada por completo)	result - Resultado de la operación: - 0 - Desconocido - 1 - llenado total - 2 - llenado parcial - 3 - abortado routes - Información sobre el llenado parcial de la operación. Matriz de RouteStatus

Descripciones de objetos

RouteStatus

• steps - Matriz de StepStatus objetos.

StepStatus

• chunks - Matriz de ChunkStatus objetos.

ChunkStatus

Nombre	Tipo	Descripción
target_address	Address	Dirección del contrato que procesa este chunk. Generalmente, esta dirección recibe tokens ofertados. Más específicamente, puede ser la dirección de un protocolo o de un pool de liquidez.
bid_units	Cantidad	La cantidad del activo ofertado transferida desde la billetera del trader
expected_ask_units	Cantidad	La cantidad esperada del activo solicitado que se transferirá a la billetera del trader
actual_ask_units	Cantidad	La cantidad real del activo solicitado transferida a la billetera del trader
result	Número	Resultado del chunk: - 0 - Procesando - 1 - Completado - 2 - Abortado
protocol	Protocolo	Protocolo de esta operación de swap
tx_hash	Cadena	Hash de la transacción que ejecutó este chunk

Ejemplos:

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 4374307320472544,
    "result": {
      "status": {
        "awaiting_transfer": {}
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "transferring": {}
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "trade_settled": {
          "result": 1,
          "routes": [
            {
              "steps": [
                {
                  "chunks": [
                    {
                      "target_address": {
                        "blockchain": 607,
                        "address": "EQACpXPHyLueReUMCmStesRXA77IK_ZAhHnLKAsQ5MjMUliK"
                      },
                      "bid_units": "1000000",
                      "expected_ask_units": "3379",
                      "actual_ask_units": "3378",
                      "result": 1,
                      "protocol": "StonFiV1",
                      "tx_hash": "97c06867d0e891369fa0f621e0b7d549c888af8f34e4bde6752d580c6da508c2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Método transaction.build_transfer

Una solicitud para generar una transferencia sin firmar para iniciar la operación.

Acepta los siguientes parámetros como entrada:

Nombre	Tipo	Descripción
source_address	Address	La dirección en bid_blockchain que enviará la transacción inicial para iniciar la operación
destination_address	Address	La dirección en ask_blockchain que recibirá el resultado de la operación
gas_excess_address	Address	La dirección que recibirá el gas no gastado por la operación
refund_address	Address	(Opcional) La dirección a la que deben devolverse los fondos si la transacción falla. Si no se especifica, los fondos se devuelven a la billetera del remitente. Actualmente solo funciona para swaps a través de STON.fi
quote	Quote	La cotización válida recibida de quote subscription
use_recommended_slippage	Booleano	Usar el deslizamiento recomendado por Omniston en lugar del deslizamiento proporcionado por el trader

Ejemplo:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "v1beta7.transaction.build_transfer",
  "params": {
    "source_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "destination_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "gas_excess_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "refund_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "quote": {
      "quote_id": "3d1d9ad4656f883ce63cb80c67b8698c",
      "bid_asset_address": {
        "blockchain": 607,
        "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
      },
      "ask_asset_address": {
        "blockchain": 607,
        "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
      },
      "bid_units": "100000000",
      "ask_units": "33787874",
      "referrer_address": "",
      "referrer_fee_units": "0",
      "protocol_fee_units": "0",
      "quote_timestamp": 1723146414,
      "trade_start_deadline": 1723144766,
      "params": {
        "swap": {
          "routes": [
            {
              "steps": [
                {
                  "bid_asset_address": {
                    "blockchain": 607,
                    "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
                  },
                  "ask_asset_address": {
                    "blockchain": 607,
                    "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
                  },
                  "chunks": [
                    {
                      "protocol": 0,
                      "bid_amount": "100000",
                      "ask_amount": "33757",
                      "extra": "SGVsbG8sIHRoaXMgaXMgYW4gZXhhbXBsZSBiYXNlNjQgZW5jb2RlZCBzdHJpbmcgZm9yIHRoZSBleHRyYSBmaWVsZC4=",
                      "extra_version": 1
                    }
                  ]
                }
              ],
              "gas_budget": "300000000"
            }
          ]
        }
      }
    }
  }
}

La respuesta contiene un ton objeto con los datos de transacción específicos de la blockchain:

Nombre	Tipo	Descripción
ton	Objeto	Contiene datos de transacción específicos de TON
ton.messages	Array(Message)	Matriz de mensajes a enviar

Cada Message objeto contiene:

Nombre	Tipo	Descripción
target_address	Cadena	La dirección del destinatario
send_amount	Cadena	Cantidad en nanotons a enviar como valor adjunto
payload	Cadena	Datos de transacción codificados en hex o en base64

{
  "jsonrpc": "2.0",
  "result": {
    "ton": {
      "messages": [
        {
          "target_address": "EQCJ7SWUt1weFuOCN32XNzT6dOM2stAe2LZZtOelF0hyoIRv",
          "send_amount": "300000000",
          "payload": "b5ee9c7241010201008800016d0f8a7ea5e63cb80c67b8698c405f5e1008013d9e00e89901bff71ffe5d1c1c92610888072c54e8fa27242807d7c6976a36ac103b9aca0301009725938561801af7bf08bea0d52dcdcf23d2c039f33a4184f23406bf0351e922a6bf6431e78ba803d391610000a95cf1f22ee791794302992b5eb115c0efb20afd90211e72ca02c43932331490056baf1e"
        }
      ]
    }
  },
  "id": 3
}

---

Próximos pasos

Elija su ruta de integración según sus necesidades:

Si quiere...	Use esto
Crear una aplicación frontend rápidamente	SDK de React - Hooks listos para usar
Crear una servicio backend o bot	SDK de Node.js - Soporte completo de TypeScript
Implementar en Python o en otro lenguaje	Inicio rápido de Python - Adáptelo a su lenguaje
Estudiar la implementación de bajo nivel	Código fuente del SDK - Referencia de código abierto
Comprender el protocolo en profundidad	Continúe leyendo arriba y Funciones avanzadas
Usar gRPC de alto rendimiento	Integración gRPC

Inicio rápido del SDK

# Node.js
npm install @ston-fi/omniston-sdk

# React
npm install @ston-fi/omniston-sdk-react

Consulta la documentación del SDK para ejemplos completos y referencia de la API.

💡 Código abierto: Nuestros SDK son totalmente de código abierto en github.com/ston-fi/omniston-sdk. Puede estudiar la implementación, contribuir con mejoras o usarlo como referencia para crear integraciones en otros lenguajes.