> 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/dex/sdk/v2/swap.md).

# Swap (v2)

{% hint style="info" %}
**Más información**

* **Guía de inicio rápido**: Consulta nuestro [Inicio rápido de swaps](/es/seccion-para-desarrolladores/quickstart/swap.md) para un ejemplo completo de aplicación React
* **Blog**: [DeFi fácil para proyectos de TON: integración de STON.fi](https://blog.ston.fi/easy-defi-for-ton-projects-stonfi-integration/)
  {% endhint %}

> El patrón listo para producción es **basado en API**. Siempre deja que la API de STON.fi dicte qué router usar y trabaja contra el endpoint de mainnet. Esto mantiene tu integración compatible con futuras actualizaciones del router y evita codificar direcciones de contrato.

## Flujo centrado primero en mainnet

La API REST de STON.fi (`api.ston.fi`) solo sirve datos de mainnet, así que cada swap de producción debe seguir este flujo:

1. Simula el swap para obtener metadatos de enrutamiento (cantidades esperadas, información del vault y el objeto router completo).
2. Pasa `simulationResult.router` directamente a `dexFactory()` para crear contratos dinámicamente.
3. Genera los parámetros de la transacción de swap con los helpers del router.

```typescript
import { dexFactory, Client } from "@ston-fi/sdk";
import { StonApiClient } from "@ston-fi/api";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

const apiClient = new StonApiClient();

// 1. Simula el swap para descubrir los detalles de enrutamiento
const simulationResult = await apiClient.simulateSwap({
  offerAddress: "<dirección del activo de origen o 'ton'>",
  askAddress: "<dirección del activo de destino>",
  offerUnits: "<cantidad en unidades de blockchain>",
  slippageTolerance: "0.01",
});

// 2. Los metadatos del router vienen con el resultado de la simulación
const { router: routerInfo } = simulationResult;
const dexContracts = dexFactory(routerInfo);

// 3. Abre el contrato del router
const router = tonClient.open(
  dexContracts.Router.create(routerInfo.address)
);

// Ayudante opcional cuando TON forma parte de la ruta
const proxyTon = dexContracts.pTON.create(routerInfo.ptonMasterAddress);
```

El `simulationResult` el objeto contiene `offerUnits`, `minAskUnits`, `offerAddress`, `askAddress` y `router`. Reutiliza esos valores al construir la transacción de swap real para asegurarte de que la transacción firmada coincida con la ruta simulada.

> **Comisiones de referidos**: Puedes especificar una comisión de referido en tu swap si es necesario. Para más contexto, consulta la [guía de comisiones de referido de Omniston](/es/seccion-para-desarrolladores/omniston/referral-fees.md#referral-fees-with-dex-v2) (aunque está orientado a Omniston, el párrafo enlazado detalla cómo funcionan las comisiones de referido de DEX V2).

## Swap de TON a jetton

```typescript
const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  askJettonAddress: simulationResult.askAddress,
  proxyTon,
  // Parámetros opcionales de referido:
  referralAddress: "<tu dirección de referido de TON>",
  referralValue: 10, // p. ej., 10 => comisión del 0.1%
  queryId: 12345,
});
```

Envía los parámetros resultantes usando la integración con billetera que prefieras. Consulta nuestra [guía de envío de transacciones](/es/seccion-para-desarrolladores/common/transaction-sending.md) para ver ejemplos específicos de billetera.

## Swap de jetton a jetton

```typescript
const txParams = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerJettonAddress: simulationResult.offerAddress,
  askJettonAddress: simulationResult.askAddress,
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  // Parámetros opcionales de referido:
  referralAddress: "<tu dirección de referido de TON>",
  referralValue: 25, // p. ej., 25 => comisión del 0.25%
  queryId: 12345,
});
```

## Swap de jetton a TON

```typescript
const txParams = await router.getSwapJettonToTonTxParams({
  userWalletAddress: "<la dirección de tu billetera>",
  offerJettonAddress: simulationResult.offerAddress,
  offerAmount: simulationResult.offerUnits,
  minAskAmount: simulationResult.minAskUnits,
  proxyTon, // reutilizar de la configuración común
  // Parámetros opcionales de referido:
  referralAddress: "<tu dirección de referido de TON>",
  referralValue: 50, // p. ej., 50 => comisión del 0.5%
  queryId: 12345,
});
```

Usa el [guía de envío de transacciones](/es/seccion-para-desarrolladores/common/transaction-sending.md) para transmitir la transacción. TonConnect, el SDK de Tonkeeper, los firmantes custodiales y otras bibliotecas aceptan todos el `txParams` generados arriba.

## Swaps en la testnet (configuración manual)

Si realmente necesitas probar swaps v2 en la testnet de TON, debes recurrir a contratos codificados manualmente porque `api.ston.fi` solo sirve para mainnet. La liquidez es escasa, así que planifica conseguir o acuñar los jettons tú mismo, crear los pools de liquidez necesarios y financiarlos antes de intentar hacer un swap.

Para reproducir los tres tipos de swap del ejemplo de mainnet, los testers suelen ejecutar la siguiente secuencia en la testnet:

1. intercambiar 1 TON por TesREED (ton -> jetton)
2. intercambiar TesREED por TestBlue (jetton -> jetton)
3. intercambiar TestBlue de vuelta a TON (jetton -> ton)

```typescript
import { TonClient, toNano } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";

const client = new TonClient({
  endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create("kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v") // Router CPI v2.1.0 (testnet)
);

const proxyTon = pTON.v2_1.create("kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px"); // pTON v2.1.0 (testnet)

const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "<your testnet wallet>",
  proxyTon,
  offerAmount: toNano("1"),
  askJettonAddress: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // jetton TesREED (testnet)
  minAskAmount: "1",
});
```

Este enfoque manual es estrictamente **para pruebas**. Vuelve al flujo impulsado por la API para cualquier cosa orientada a mainnet.


---

# 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/dex/sdk/v2/swap.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.