Node.js

Primeros pasos con el SDK de Omniston en Node.js: integración del lado del servidor para trading automatizado y bots

Primeros pasos

Este paquete actúa como un envoltorio de TypeScript sobre Ston.fi API del protocolo Omniston y proporciona observables al estilo de RxJS sobre la conexión de la API WebSocket

📦 Paquete NPM: @ston-fi/omniston-sdk

Instalación

vía NPM

npm install @ston-fi/omniston-sdk

vía YARN

yarn add @ston-fi/omniston-sdk

vía PNPM

pnpm install @ston-fi/omniston-sdk

Crear una instancia

Crea una instancia de Omniston, especificando la URL de la API.

import { Omniston } from "@ston-fi/omniston-sdk";

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

El constructor toma los siguientes parámetros:

Nombre	Tipo	Descripción
client	ApiClient | undefined	Opcional. Proporcione esto si desea sobrescribir el cliente de API predeterminado. Por defecto, será un ApiClient usando ReconnectingTransport
apiUrl	URL | string	URL de la API WebSocket de Omniston.

Ejemplo en sandbox (pruebas)

Si está desarrollando o probando su integración, use el entorno público de sandbox en lugar de producción.

import { Omniston } from "@ston-fi/omniston-sdk";

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

Sandbox está destinado solo para desarrollo y pruebas de integración. No use sandbox en aplicaciones de producción.

Enviar una solicitud de cotización

Envía una solicitud de cotización para intercambiar un activo por otro activo.

import { GaslessSettlement } from "@ston-fi/omniston-sdk";

omniston
  .requestForQuote({
    settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
    askAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    },
    bidAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
    },
    amount: {
      bidUnits: "1000000", // 1 USDT
    },
    settlementParams: {
      maxPriceSlippageBps: 0,
      gaslessSettlement: GaslessSettlement.GASLESS_SETTLEMENT_POSSIBLE,
      maxOutgoingMessages: 4, // predeterminado para TON
      flexibleReferrerFee: true, // permite una comisión de referidor menor si el resolver mejora la cotización
    },
  })
  .subscribe((quoteResponseEvent) => {
    switch (quoteResponseEvent.type) {
      case 'ack': {
        // Solicitud de cotización reconocida
        const { rfqId } = quoteResponseEvent;
        console.log(`Solicitud de cotización reconocida con ID: ${rfqId}`);
        break;
      }
      case 'quoteUpdated': {
        // Cotización recibida
        const { quote, rfqId } = quoteResponseEvent;
        console.log(`Cotización actualizada para la solicitud ${rfqId}`);
        // Procesar la cotización...
        break;
      }
      case 'unsubscribed': {
        const { rfqId } = quoteResponseEvent;
        console.log(`Dado de baja de la solicitud de cotización ${rfqId}`);
        break;
      }
    }
  });

Un QuoteRequest tiene las siguientes propiedades:

Nombre	Tipo	Descripción
settlementMethods	SettlementMethod[]	Métodos admitidos de liquidación del swap
askAssetAddress	Address	Dirección específica de la blockchain del activo ask
bidAssetAddress	Address	Dirección específica de la blockchain del activo bid
amount	{ bidUnits: string } | { askUnits: string }	Ya sea la cantidad del activo bid o del activo ask
amount.bidUnits	string	La cantidad del activo bid que el trader desea pagar, incluidas todas las comisiones, en unidades del activo base
amount.askUnits	string	La cantidad del activo ask que el trader desea obtener después de todas las comisiones, en unidades del activo base
referrerAddress	Address | undefined	La dirección del referidor que recibirá las comisiones
referrerFeeBps	number | undefined	La cantidad de comisiones requerida por el referidor en puntos básicos (1/10000 o 0,01%)
settlementParams	RequestSettlementParams | undefined	Parámetros adicionales del RFQ relacionados con la liquidación. Consulte la tabla de abajo.

RequestSettlementParams

Nombre	Tipo	Descripción
max_price_slippage_bps	number | undefined	Deslizamiento máximo del precio, en puntos básicos (0,01%). Por ejemplo, 100 = 1% de deslizamiento. Establézcalo en 0 para usar el deslizamiento recomendado.
gasless_settlement	GaslessSettlement | undefined	Preferencia de liquidación sin gas. Opciones: GASLESS_SETTLEMENT_PROHIBITED (sin gasless), GASLESS_SETTLEMENT_POSSIBLE (permitir gasless), GASLESS_SETTLEMENT_REQUIRED (requiere gasless).
max_outgoing_messages	number | undefined	Número máximo de mensajes salientes admitidos por la cartera. Para la blockchain TON, el valor predeterminado es 4 si se omite.
flexible_referrer_fee	boolean | undefined	Establezca en true para permitir que los resolvers reduzcan la comisión efectiva del referidor por debajo de referrerFeeBps al ofrecer una mejor tasa. El valor predeterminado es false. En los SDK, páselo como flexibleReferrerFee. Consulte Comisión flexible del referidor para más detalles.

Nota: Algunos parámetros en RequestSettlementParams solo pueden ser relevantes para ciertas blockchains o ciertos métodos de liquidación. Si su método de liquidación o cartera no los requiere, puede omitarlos o establecerlos en valores predeterminados.

Opciones de liquidación sin gas:

• GASLESS_SETTLEMENT_PROHIBITED: Deshabilita completamente la liquidación sin gas

• GASLESS_SETTLEMENT_POSSIBLE: Permite la liquidación sin gas si está disponible (recomendado)

• GASLESS_SETTLEMENT_REQUIRED: Fuerza la liquidación sin gas (fallará si no está disponible)

El servidor devuelve Observable<QuoteResponseEvent>, que es un flujo de actualizaciones de cotización.

Un QuoteResponseEvent puede ser uno de los siguientes:

• { type: "ack"; rfqId: string; } - Confirmación de que se recibió la solicitud de cotización

• { type: "quoteUpdated"; quote: Quote; rfqId: string; } - Una actualización de la cotización (incluye rfqId después de la confirmación)

• { type: "noQuote"; }

• { type: "unsubscribed"; rfqId: string; } - Dado de baja del flujo de cotizaciones (incluye rfqId después de la confirmación)

Un Quote tiene las siguientes propiedades:

Nombre	Tipo	Descripción
quoteId	string	ID de la cotización generada por la plataforma (32 caracteres)
resolverId	string	ID del resolver
resolverName	string	Nombre del resolver
bidAssetAddress	Address	Dirección específica de la blockchain del activo bid
askAssetAddress	Address	Dirección específica de la blockchain del activo ask
bidUnits	string	La cantidad del activo bid que el trader debe pagar, incluidas todas las comisiones
askUnits	string	La cantidad del activo ask que el trader obtendrá después de todas las comisiones
referrerAddress	Address | undefined	La dirección del referidor que recibirá las comisiones
referrerFeeAsset	Address	El activo de las comisiones que recibirá el referidor
referrerFeeUnits	string	La cantidad de comisiones que recibirá el referidor (en unidades de referrerFeeAsset)
protocolFeeAsset	Address	El activo de las comisiones cobradas por el protocolo
protocolFeeUnits	string	La cantidad de comisiones cobradas por el protocolo (en unidades de protocolFeeAsset).
quoteTimestamp	number	La marca de tiempo (segundos UTC) de la cotización enviada por el resolver
tradeStartDeadline	number	Marca de tiempo máxima (segundos UTC) del inicio de la operación
gasBudget	string	La cantidad de presupuesto de gas para la operación
estimatedGasConsumption	string	Cantidad estimada de unidades de gas que se gastarán para realizar la operación
params	object | undefined	Varios parámetros específicos del método de liquidación. Consulte el código fuente para más detalles.

Construir una transacción

Ahora que tenemos una cotización, debemos solicitar al servidor que construya una transacción para iniciar la operación que el usuario pueda verificar y firmar.

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // dirección de la cartera remitente en `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // dirección de la cartera receptora en `askBlockchain`
  },
  gasExcessAddress: {
    blockchain: Blockchain.TON,
    address: "", // la dirección que recibirá el gas no gastado por la operación
  },
  useRecommendedSlippage: true, // usar el deslizamiento recomendado de la cotización
});

const messages = tx.ton?.messages ?? [];

El buildTransfer el método toma un TransactionRequest objeto como parámetro, que tiene las siguientes propiedades:

Nombre	Tipo	Descripción
quote	Quote	La cotización válida recibida de Omniston.requestForQuote
sourceAddress	Address	La dirección en offerBlockchain que enviará la transacción inicial para iniciar la operación
destinationAddress	Address	La dirección en askBlockchain que recibirá el resultado de la operación
gasExcessAddress	Address | undefined	La dirección que recibirá el gas no gastado por la operación
refundAddress	Address | undefined	La dirección a la que se devolverán los fondos en caso de un fallo
useRecommendedSlippage	boolean | undefined	Si se debe usar el deslizamiento recomendado de la cotización. El valor predeterminado es false.

Firmar la transacción

Puede enviar messages a cualquier biblioteca de su elección. Eche un vistazo a nuestra guía para enviar transacciones con ejemplos de diferentes paquetes populares

Escuchar actualizaciones del estado de la operación

Después de que el usuario haya firmado e iniciado la transacción, podemos rastrear el estado de la operación.

const tradeStatus = omniston.trackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: "", // dirección de la cartera remitente en `offerBlockchain`
  },
  outgoingTxHash: "", // Reemplace con el outgoingTxHash real
});

tradeStatus.subscribe((status) => {
  console.log(JSON.stringify(status));
});

El trackTrade el método tiene los siguientes parámetros:

Nombre	Tipo	Descripción
quoteId	string	ID de la cotización recibida de Omniston.requestFromQuote
traderWalletAddress	Address	La dirección de la cartera del trader que inició la transacción
outgoingTxHash	string	Hash de la transacción que inició la operación

Devuelve Observable<TradeStatus>. Para los distintos valores del estado de la operación, consulte el código fuente. Nos interesa el enum del resultado de la operación, que puede leerse del campo status.tradeSettled?.result? . El enum tiene los siguientes valores:

Nombre	Descripción
TRADE_RESULT_FULLY_FILLED	La operación se ha completado y ejecutado por completo.
TRADE_RESULT_PARTIALLY_FILLED	La operación se ha ejecutado parcialmente. Algo salió mal.
TRADE_RESULT_ABORTED	La operación ha sido abortada.
TRADE_RESULT_UNKNOWN
UNRECOGNIZED