> 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/omniston/sdk/nodejs.md).

# Node.js

El SDK de Node.js te da acceso directo a la superficie de la API de Omniston. En `v1beta8`, el flujo principal de integración es:

1. preparar `settlementParams` para los métodos de liquidación que quieras permitir
2. suscríbete a las actualizaciones de RFQ y selecciona una cotización del flujo
3. ramifica según `quote.settlementData?.$case`
4. construye y firma un flujo de swap o un flujo de orden
5. haz seguimiento de la liquidación resultante

También hay disponible una implementación de referencia de código abierto de extremo a extremo en nuestra app de ejemplo: [examples/react-app](https://github.com/ston-fi/omniston-sdk/tree/main/examples/react-app)

## Instalación

* [Código fuente](https://github.com/ston-fi/omniston-sdk/tree/main/packages/omniston-sdk)
* [@ston-fi/omniston-sdk](https://www.npmjs.com/package/@ston-fi/omniston-sdk) Paquete NPM

Instala el SDK en tu proyecto:

```sh
npm install @ston-fi/omniston-sdk
```

## Creación de una instancia

Crea una `Omniston` instancia que apunte al endpoint de API deseado.

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

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

Si estás integrando contra el **sandbox** entorno, usa:

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

## Preparación de parámetros de liquidación

Antes de solicitar una cotización, decide qué métodos de liquidación quieres que la red de resolutores considere. En `v1beta8`, esto se controla mediante `settlementParams`, donde cada elemento habilita una rama de liquidación.

Usa solo swap cuando quieras una ejecución clásica de swap, normalmente para flujos TON sencillos. Usa solo orden cuando quieras solo liquidación por orden, por ejemplo cuando tu aplicación esté construida específicamente alrededor de órdenes firmadas o flujos HTLC. Usa ambos cuando quieras que Omniston devuelva la mejor opción disponible y decidir más tarde según la cotización devuelta.

```ts
import {
  type SettlementParams,
  type SwapSettlementParams,
  type OrderSettlementParams,
} from "@ston-fi/omniston-sdk";

const swapOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "swap",
      value: {
        maxPriceSlippagePips: 10_000, // 1%
        flexibleIntegratorFee: true,
      } satisfies SwapSettlementParams,
    },
  },
];

const orderOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "order",
      value: {} satisfies OrderSettlementParams,
    },
  },
];

const swapAndOrderSettlementParams: SettlementParams[] = [
  ...swapOnlySettlementParams,
  ...orderOnlySettlementParams,
];
```

## Recepción de cotizaciones basada en parámetros

Después de preparar los parámetros de liquidación, solicita una cotización y suscríbete al flujo RFQ. `requestForQuote()` es un flujo en vivo y puede emitir múltiples `quoteUpdated` eventos con el tiempo, así que tu integración debe manejarlo como una suscripción continua y no como una solicitud única.

```ts
import type { AssetId, QuoteRequest } from "@ston-fi/omniston-sdk";

const inputAsset: AssetId = {
  chain: {
    $case: "ton",
    value: {
      kind: {
        $case: "jetton",
        value: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // ejemplo: USDT
      },
    },
  },
};

const outputAsset: AssetId = {
  chain: {
    $case: "ton",
    value: {
      kind: {
        $case: "jetton",
        value: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // ejemplo: STON
      },
    },
  },
};

const quoteRequest: QuoteRequest = {
  inputAsset,
  outputAsset,
  amount: {
    $case: "inputUnits",
    value: "1000000",
  },
  settlementParams: swapAndOrderSettlementParams,
};

omniston.requestForQuote(quoteRequest).subscribe({
  next(event) {
    switch (event?.$case) {
      case "ack":
        console.log("ID de RFQ:", event.value.rfqId);
        break;
      case "quoteUpdated":
        console.log("Cotización recibida:", event.value.quoteId);
        break;
      case "noQuote":
        console.log(`No hay cotización disponible para el RFQ ${event.rfqId}`);
        break;
      case "unsubscribed":
        console.log("El flujo de cotizaciones fue cerrado por el servidor");
        break;
    }
  },
  error(error) {
    console.error("El flujo RFQ falló", error);
  },
});
```

## Flujos de liquidación

Una vez que hayas seleccionado una `cotización` del flujo RFQ, `quote.settlementData?.$case` sigue el flujo de liquidación correspondiente.

### Cotizaciones de swap

#### Construcción y firma de la transacción

Una vez que hayas seleccionado una `cotización` del flujo y utiliza liquidación de swap, construye una transacción TON con `tonBuildSwap()`, luego pasa los mensajes resultantes a la billetera o biblioteca de firma que uses en tu aplicación.

```ts
import { isSwapQuote, type ChainAddress } from "@ston-fi/omniston-sdk";

if (!isSwapQuote(quote)) {
  throw new Error("Se esperaba una cotización de swap");
}

const traderAddress: ChainAddress = {
  chain: {
    $case: "ton",
    value: "EQ...",
  },
};

const swapTx = await omniston.tonBuildSwap({
  quoteId: quote.quoteId,
  transferSrcAddress: traderAddress,
  refundSrcAddress: traderAddress,
  gasExcessAddress: traderAddress,
  traderDstAddress: traderAddress,
});

// `swapTx.messages` debe firmarse y enviarse con el paquete de billetera TON que use tu proyecto.
```

#### Seguimiento

Después de enviar la transacción de swap, haz seguimiento del swap con `swapTrack()`. Necesitas el `quoteId`, la dirección de la billetera del trader y un identificador que permita a Omniston encontrar la transacción saliente.

```ts
const swapTrackStream = await omniston.swapTrack({
  quoteId: quote.quoteId,
  traderAddress,
  outgoingTxQuery, // hash de la tx, hash del mensaje o cuerpo del mensaje saliente
});

swapTrackStream.subscribe({
  next(event) {
    switch (event?.$case) {
      case "awaitingTransfer":
        console.log("Esperando la transferencia");
        break;
      case "progress":
        console.log("Estado del swap:", event.value.status);
        break;
      case "unsubscribed":
        console.log("El flujo de seguimiento del swap se cerró");
        break;
    }
  },
});
```

### Cotizaciones de orden

#### Construcción y firma de la transacción

Una vez que hayas seleccionado una `cotización` del flujo y utiliza liquidación de órdenes, el flujo de construcción y firma depende de la cadena de origen.

Para la liquidación de órdenes en TON, construye una transferencia en depósito en garantía y firma los mensajes TON resultantes:

```ts
import {
  isHtlcOrderQuote,
  isOrderQuote,
  type HtlcSecrets,
} from "@ston-fi/omniston-sdk";

if (!isOrderQuote(quote)) {
  throw new Error("Se esperaba una cotización de orden");
}

const tonOrderTx = await omniston.tonBuildEscrowTransfer({
  quoteId: quote.quoteId,
  ownerSrcAddress: traderAddress,
  transferSrcAddress: traderAddress,
  refundSrcAddress: traderAddress,
  gasExcessAddress: traderAddress,
  traderDstAddress: traderAddress,
});

// `tonOrderTx.messages` debe firmarse y enviarse con el paquete de billetera TON que use tu proyecto.
```

Para la liquidación de órdenes EVM, construye el payload de la orden, fírmalo con tu billetera EVM y registra la orden firmada con Omniston:

```ts
if (!isOrderQuote(quote)) {
  throw new Error("Se esperaba una cotización de orden");
}

const evmTraderAddress: ChainAddress = {
  chain: {
    $case: "base",
    value: "0x...",
  },
};

const htlcSecrets: HtlcSecrets | undefined = isHtlcOrderQuote(quote)
  ? {
      secretMode: {
        $case: "provided",
        value: {
          hashes: myGeneratedHashlocks,
        },
      },
    }
  : undefined;

const orderPayload = await omniston.evmBuildOrderPayload({
  quoteId: quote.quoteId,
  ownerSrcAddress: evmTraderAddress,
  traderDstAddress: traderAddress,
  htlcSecrets,
  traderDstDiscloseAddress: traderAddress,
});

const signedOrder = await buildSignedOrderSomehow(orderPayload);

await omniston.orderRegisterSignedOrder({
  quoteId: quote.quoteId,
  ownerSrcAddress: evmTraderAddress,
  signedOrder,
  serializedOrderDetails: orderPayload.serializedOrderDetails,
});
```

#### Seguimiento

Una vez que se envíe la orden, usa `orderTrack()` para monitorear su ciclo de vida. Para ejecuciones parciales basadas en HTLC, la aplicación debe generar los secretos por su cuenta, pasar sus hashes al construir el payload de la orden y luego revelar los secretos originales con `orderDiscloseHtlcSecret()` cuando las ejecuciones alcancen la fase adecuada.

```ts
const orderTrackStream = await omniston.orderTrack({
  quoteId: quote.quoteId,
  traderAddress,
});

orderTrackStream.subscribe({
  next(event) {
    switch (event?.$case) {
      case "order":
        console.log("Estado de la orden:", event.value.status);
        console.log("Ejecuciones:", event.value.executions.length);
        break;
      case "unsubscribed":
        console.log("El flujo de seguimiento de la orden se cerró");
        break;
    }
  },
});
```

Si estás usando liquidación de órdenes HTLC y gestionas los secretos tú mismo, revélalos una vez que una ejecución esté lista:

```ts
await omniston.orderDiscloseHtlcSecret({
  quoteId: quote.quoteId,
  executionIndex: 0,
  secret: mySecretBytes,
});
```

## Lista de órdenes activas

Si tu aplicación necesita restaurar el estado de órdenes existente o mostrar todas las órdenes activas de un trader, llama a `orderGetActive()`. A diferencia de `requestForQuote()`, este es un método normal de solicitud-respuesta, así que deberías llamarlo bajo demanda o consultarlo periódicamente desde tu aplicación si necesitas actualización periódica.

```ts
import type { ChainAddress } from "@ston-fi/omniston-sdk";

const traderAddress: ChainAddress = {
  chain: {
    $case: "ton",
    value: "EQ...",
  },
};

const activeOrders = await omniston.orderGetActive({
  traderAddress,
});

for (const activeOrder of activeOrders.activeOrders) {
  console.log("ID de la cotización de la orden:", activeOrder.quote.quoteId);
  console.log("Estado de la orden:", activeOrder.order.status);
}
```


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.ston.fi/es/seccion-para-desarrolladores/omniston/sdk/nodejs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.