> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de TypeScript

> @raydium-io/raydium-sdk-v2 de principio a fin — instalación, las cuatro fachadas de módulos, construcción de transacciones y los problemas que afectan a cada nuevo integrador.

<Info>
  **Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.**

  [Ver versión en inglés →](/sdk-api/typescript-sdk)
</Info>

<Info>
  **Banner de versión.** Esta página documenta `@raydium-io/raydium-sdk-v2@0.2.42-alpha`, la versión verificada en todas las demostraciones de código de este sitio (2026-04). El SDK está en pre-1.0 y la superficie de tipos ha evolucionado entre versiones — fija la versión que utilices.
</Info>

## Instalar

```bash theme={null}
npm install @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
# o
pnpm add @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
```

El SDK está escrito en TypeScript y distribuye `.d.ts` junto con su artefacto JS. Herramientas mínimas requeridas: Node 18+, TypeScript 5.0+, `moduleResolution: "bundler"` o `"node16"`.

## Inicializar

El punto de entrada es `Raydium.load`:

```ts theme={null}
import { Raydium } from "@raydium-io/raydium-sdk-v2";
import { Connection, Keypair, clusterApiUrl } from "@solana/web3.js";

const connection = new Connection(process.env.RPC_URL ?? clusterApiUrl("mainnet-beta"));
const owner      = Keypair.fromSecretKey(/* ... */);

const raydium = await Raydium.load({
  owner,
  connection,
  cluster: "mainnet",           // "mainnet" | "devnet"
  disableFeatureCheck: true,    // omitir la llamada a API de detección de características del SDK al iniciar
  blockhashCommitment: "confirmed",
});
```

`Raydium.load` es asincrónica porque obtiene una pequeña carga útil `/config` desde `api-v3.raydium.io` al iniciar (listando cuentas actuales de `AmmConfig`, capas de tarifas, etc.). Establece `disableFeatureCheck: true` en entornos sin conexión; tendrás que proporcionar esos valores manualmente a algunos constructores.

## Las cuatro fachadas de módulos

Una vez cargado, el objeto `raydium` expone cuatro fachadas de módulos, una por superficie de producto:

```ts theme={null}
raydium.cpmm       // Pools CPMM: createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // Pools CLMM: createPool, openPositionFromBase, increasePositionFromBase,
                   //             decreaseLiquidity, harvestAllRewards, swap, ...
raydium.liquidity  // Pools AMM v4: computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // Farm v3/v5/v6: deposit, withdraw, harvestAllRewards, create, setRewards
raydium.launchpad  // LaunchLab: createLaunchpad, buyExactIn, sellExactIn, graduate, ...
raydium.trade      // Enrutamiento multi-pool: quotes, route-execution (beta en 0.2.41)
raydium.token      // Utilidades: obtener lista de tokens, metadatos, creación de ATA
```

(Sí, cinco fachadas en total — "cuatro" es la forma en que Raydium las agrupa públicamente, siendo `trade` y `token` utilidades de apoyo.)

## Constructores de transacciones

Cada función que realiza cambios devuelve un constructor en lugar de ejecutarse inmediatamente:

```ts theme={null}
const { execute, builder, transaction, innerTransactions, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    amountInA,
    amountInB,
    slippage: 0.005,
    txVersion: TxVersion.V0,
  });
```

Campos devueltos:

* **`execute`** — una función de conveniencia que firma + envía. Equivalente a `builder.execute`.
* **`builder`** — la instancia de `TxBuilder` con todas las instrucciones y firmantes acumulados. Llama a `.build()` para obtener un `VersionedTransaction[]`; útil cuando necesitas inyectar tus propias instrucciones o firmar con firmantes externos.
* **`transaction` / `innerTransactions`** — los arrays de instrucciones crudas. Úsalos cuando construyas transacciones compuestas multi-programa.
* **`extInfo`** — extras específicos del producto. Por ejemplo, `createPool` devuelve `extInfo.poolId`; `createLaunchpad` devuelve el nuevo PDA de estado de lanzamiento.

`txVersion` controla el formato de transacción heredada vs V0. V0 (tablas de búsqueda de direcciones) es la recomendación predeterminada — permite que swaps más grandes se ajusten en una sola transacción.

### ¿Por qué constructores asincronos?

Casi cada constructor obtiene internamente estado en cadena: información del pool (para quotes), propiedad del programa de tokens (para enrutamiento Token-2022 vs SPL), exención de alquiler de cuenta (para creación de ATA), etc. El SDK cachea agresivamente pero la primera llamada para un pool nuevo implica viajes por RPC. Mantén una instancia `raydium` con vida larga para evitar re-obtener.

## Adiciones del módulo CLMM (versión más reciente)

La fachada CLMM adquirió superficies para las nuevas características de tarifa dinámica, tarifa de un lado y órdenes limitadas:

* **`raydium.clmm.createCustomizablePool`** — superconjunto de `createPool` que acepta `collectFeeOn`, `enableDynamicFee` y `dynamicFeeConfigId`. Úsalo para cualquier nuevo pool que necesite estos nuevos controles; `createPool` clásico continúa funcionando para pools con tarifa predeterminada.
* **`raydium.clmm.openLimitOrder`** — abre una orden limitada de un solo tick en un pool que las admite. Toma `poolInfo`, `poolKeys`, `limitOrderConfig` (de `/main/clmm-limit-order-config`), `inputMint`, `inputAmount` y el `tick` objetivo.
* **`raydium.clmm.increaseLimitOrder` / `decreaseLimitOrder`** — ajusta la porción sin llenar de una orden existente. Disminuir revierte en una orden completamente llena con `InvalidOrderPhase`.
* **`raydium.clmm.settleLimitOrder` / `settleAllLimitOrder`** — barre la salida llenada hacia el ATA del propietario. Ya sea el propietario de la orden o el guardián `limit_order_admin` del pool pueden llamarlos.
* **`raydium.clmm.closeLimitOrder` / `closeAllLimitOrder`** — cierra órdenes completamente liquidadas para recuperar alquiler.
* **`raydium.api.getClmmDynamicConfigs()` / `getClmmLimitOrderConfigs()`** — ayudantes REST que conectan con los nuevos endpoints `/main/clmm-dynamic-config` y `/main/clmm-limit-order-config`.

Una pequeña reorganización también movió `utils/` a `libraries/`. El código que importaba desde `@raydium-io/raydium-sdk-v2/utils/...` debe cambiar a `@raydium-io/raydium-sdk-v2/libraries/...`. El barril del paquete de nivel superior permanece sin cambios, así que la mayoría de usuarios nunca ven el cambio de nombre.

Los tutoriales de TypeScript de principio a fin se encuentran en [`products/clmm/code-demos`](/es/products/clmm/code-demos).

## Errores comunes

### 1. Desajuste de cluster

La configuración de inicio del SDK es específica del cluster. Mezclar `cluster: "mainnet"` con una `Connection` de devnet causa enrutamiento erróneo silencioso: el SDK cita contra `AmmConfig` de mainnet pero envía a devnet. Siempre pasa ambos.

### 2. Olvidar pre-crear ATAs

En la primera interacción con un mint, la Cuenta de Token Asociada del usuario puede no existir. El SDK pre-añade automáticamente una instrucción `AssociatedTokenAccount::create` cuando detecta un ATA faltante, lo que cuesta una pequeña cantidad de alquiler. Si tu billetera es baja en SOL, esto fallará silenciosamente. Verifica y financia antes de reintentar.

### 3. `poolInfo` anticuado

`poolInfo` es una instantánea almacenada en caché. Si el estado del pool ha cambiado desde que lo obtuviste (un trade grande movió el precio, por ejemplo), el `minAmountOut` del swap puede ser calculado contra el estado antiguo y caer por debajo del monto de salida en cadena, revirtiendo. Re-obtén `poolInfo` inmediatamente antes de construir transacciones de alto valor, o usa el `computeAmountOut` del SDK que re-consulta las reservas.

### 4. Tarifas de prioridad

El SDK no añade precios de unidad de cálculo por defecto. En ventanas de alto volumen (lanzamientos de nuevos pools, eventos de monedas meme) esto significa que tu transacción compite con muchas otras y puede no llegar. Suministra un `computeBudgetConfig` explícito:

```ts theme={null}
const { execute } = await raydium.cpmm.swap({
  poolInfo,
  inputAmount: new BN(...),
  swapResult: ...,
  slippage: 0.005,
  txVersion: TxVersion.V0,
  computeBudgetConfig: {
    units: 250_000,          // límite de CU
    microLamports: 50_000,   // tarifa de prioridad por CU
  },
});
```

Consulta [`integration-guides/priority-fee-tuning`](/es/integration-guides/priority-fee-tuning) para orientación sobre dimensionamiento.

### 5. La tolerancia de slippage debe coincidir con el tipo de pool

CPMM y AMM v4 utilizan matemática CPMM (bajo impacto en trades normales). CLMM es por partes (el impacto salta en cruces de tick). Si copias una tolerancia de slippage de 0.5% de un ejemplo CPMM en un swap CLMM que cruza varios ticks, la transacción probablemente revierta. El `computeAmountOut` del SDK devuelve `priceImpact`; dimensiona tu tolerancia por encima de eso.

### 6. `BN` vs `number`

Todos los campos de cantidad en el SDK son instancias de `BN` de `bn.js` — nunca `number` de JavaScript. Convertir valores de cantidad vía `.toNumber()` trunca silenciosamente en `2^53`; para cualquier valor por encima de \~9 cuatrillones (no poco común en mints de 9 decimales), esto produce el resultado incorrecto. Mantén todo en `BN` hasta la renderización final de la interfaz de usuario.

## Política de versionado

* `@raydium-io/raydium-sdk-v2` es el único SDK que Raydium mantiene. Toda la documentación, demostraciones y orientación de integración lo apuntan.
* Un paquete v1 más antiguo (`@raydium-io/raydium-sdk`) existe en npm por razones históricas. El mantenimiento terminó después de que CPMM y LaunchLab se lanzaran (v1 nunca ganó soporte para ninguno de los dos), y no ha habido lanzamientos v1 desde 2024. Trata v1 como fin de vida: no lo uses para código nuevo, y migra cualquier integración v1 restante a v2.
* El SDK v2 es pre-1.0. Los cambios que rompen la compatibilidad entre versiones menores 0.x son posibles; fija la versión que hayas verificado y revisa las notas de lanzamiento de GitHub al actualizar.

## Actualizar

Cuando actualices entre versiones menores del SDK:

1. Vuelve a verificar el tipo de retorno de cada llamada que realiza cambios — los cambios de forma (p. ej. `extInfo`) ocurren frecuentemente.
2. Regenera las firmas de obtención de `poolInfo` — un campo puede haber sido renombrado.
3. Vuelve a verificar tu manejo de slippage; el SDK ha alternado entre comportamientos de vinculación automática e opcional en versiones anteriores.
4. Si usas `raydium.trade` (enrutamiento), vuelve a verificar la forma de la ruta — es la parte más inestable de la superficie.

## Obtener ayuda

Para preguntas sobre SDK y API:

* **Problemas de GitHub** — presenta en [github.com/raydium-io/raydium-sdk-V2/issues](https://github.com/raydium-io/raydium-sdk-V2/issues) para bugs y solicitudes de características. El equipo de Raydium monitorea activamente.
* **Discord** — canal `#dev-support` en [discord.gg/raydium](https://discord.gg/raydium) para ayuda sincrónica.
* **Telegram** — chat de desarrolladores enlazado desde [raydium.io](https://raydium.io) (evita grupos de Telegram no verificados).

Para problemas de seguridad, **no** publiques en canales públicos — consulta [`security/disclosure`](/es/security/disclosure).

## Enlaces relacionados

* [`sdk-api/rest-api`](/es/sdk-api/rest-api) — el complemento HTTP del SDK.
* [`sdk-api/trade-api`](/es/sdk-api/trade-api) — transacciones de swap construidas en servidor.
* [`sdk-api/anchor-idl`](/es/sdk-api/anchor-idl) — regenerando clientes directamente desde IDLs de programa.
* [`sdk-api/python-integration`](/es/sdk-api/python-integration) — equivalente en Python vía `solana-py`.
* [`integration-guides/priority-fee-tuning`](/es/integration-guides/priority-fee-tuning) — dimensionando `computeBudgetConfig`.

Fuentes:

* [Código fuente de Raydium SDK v2](https://github.com/raydium-io/raydium-sdk-V2)
* Notas de lanzamiento del SDK de Raydium.