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 escollos que atrapan a cada nuevo integrador.

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 →

Banner de versión. Esta página documenta @raydium-io/raydium-sdk-v2@0.2.64-alpha, la versión fija que lleva cada demostración de código en este sitio. El SDK es pre-1.0 y la superficie de tipos ha evolucionado entre versiones — fija tu versión.

La versión se actualizó desde 0.2.42-alpha el 2026-09-09 junto con las actualizaciones del programa: 0.2.64-alpha es la versión actual del SDK. El repositorio raydium-sdk-V2-demo al que enlazan las páginas de demostraciones de código instala 0.2.62-alpha, así que fija cualquiera de ellas si estás siguiendo una demostración al pie de la letra. Las demostraciones en estas páginas fueron ejecutadas por última vez contra 0.2.42-alpha (2026-04); sus firmas de llamada fueron re-verificadas contra la fuente 0.2.64-alpha el 2026-09-09, pero trata cualquier discrepancia como un error de documentación y abre un issue.

​

Instalar

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. Cadena de herramientas mínima: Node 18+, TypeScript 5.0+, moduleResolution: "bundler" o "node16".

​

Inicializar

El punto de entrada es Raydium.load:

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 API de detección de características del SDK al inicio
  blockhashCommitment: "confirmed",
});

Raydium.load es asincrónico porque obtiene una pequeña carga útil /config desde api-v3.raydium.io al inicio (listando cuentas AmmConfig actuales, niveles de comisión, 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:

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      // Ayudantes: 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, con trade y token como utilidades de apoyo.)

​

Constructores de transacciones

Cada función mutante devuelve un constructor en lugar de ejecutarse inmediatamente:

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 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 arreglos de instrucciones sin procesar. Úsalos cuando construyas transacciones multi-programa compuestas.
• extInfo — extras específicos del producto. Por ejemplo, createPool devuelve extInfo.poolId; createLaunchpad devuelve el PDA del nuevo estado de lanzamiento.

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

​

¿Por qué constructores asincrónico?

Casi cada constructor obtiene internamente el estado en cadena: información del pool (para cotizaciones), propiedad del programa de tokens (para enrutamiento Token-2022 vs SPL), exención de renta de cuenta (para creación de ATA), etc. El SDK almacena en caché agresivamente pero la primera llamada para un nuevo pool implica viajes de ida y vuelta de RPC. Mantén una instancia raydium de larga duración para evitar re-obtener.

​

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

La fachada CLMM ganó superficies para las nuevas características de comisión dinámica, comisión de un solo lado y órdenes limitadas:

• raydium.clmm.createCustomizablePool — superconjunto de createPool que acepta collectFeeOn, enableDynamicFee y dynamicFeeConfigId. Úsalo para cualquier nuevo pool que necesite los nuevos controles; el createPool clásico continúa funcionando para pools con comisión predeterminada.
• raydium.clmm.openLimitOrder — abre una orden limitada de un solo tick en un pool que las admita. Toma poolInfo, poolKeys, limitOrderConfig (desde /main/clmm-limit-order-config), inputMint, inputAmount y el tick objetivo.
• raydium.clmm.increaseLimitOrder / decreaseLimitOrder — ajusta la porción no completada de una orden existente. Disminuir revierte en una orden completamente completada con InvalidOrderPhase.
• raydium.clmm.settleLimitOrder / settleAllLimitOrder — barre la salida completada al ATA del propietario. Tanto el propietario de la orden como el guardián limit_order_admin del pool pueden llamarlas.
• raydium.clmm.closeLimitOrder / closeAllLimitOrder — cierra órdenes completamente liquidadas para recuperar renta.
• raydium.api.getClmmDynamicConfigs() / getClmmLimitOrderConfigs() — ayudantes REST que acceden a los nuevos puntos finales /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 no cambió, así que la mayoría de usuarios nunca ven el cambio de nombre.

Los tutoriales de TypeScript de principio a fin viven en products/clmm/code-demos.

​

Escollos comunes

​

1. Desajuste de clúster

La configuración de inicio del SDK es específica del clúster. Mezclar cluster: "mainnet" con una Connection de devnet causa enrutamiento silencioso incorrecto: el SDK cotiza 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 renta. Si tu billetera tiene poco SOL esto fallará silenciosamente. Verifica y financia antes de reintentar.

​

3. poolInfo obsoleto

poolInfo es una instantánea en caché. Si el estado del pool ha cambiado desde que lo obtuviste (un gran trade movió el precio, digamos), el minAmountOut del swap puede calcularse contra el estado antiguo y caer por debajo de la cantidad 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. Comisiones de prioridad

El SDK no añade precios de unidades de cómputo 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. Proporciona un computeBudgetConfig explícito:

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,   // Comisión de prioridad por CU
  },
});

Consulta 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 son matemáticas CPMM (bajo impacto en trades normales). CLMM es por tramos (el impacto salta en cruces de ticks). Si copias una tolerancia de slippage del 0.5% de un ejemplo CPMM en un swap CLMM que cruza varios ticks, la transacción probablemente revertirá. El computeAmountOut del SDK devuelve priceImpact; dimensiona tu tolerancia por encima de él.

​

6. BN vs number

Todos los campos de cantidad en el SDK son instancias BN de bn.js — nunca JavaScript number. Convertir valores de cantidad a través de .toNumber() trunca silenciosamente en 2^53; para cualquier valor por encima de ~9 cuatrillones (no es raro en mints de 9 decimales), esto produce el resultado incorrecto. Mantén todo en BN hasta el renderizado final de la UI.

​

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 enviaran (v1 nunca ganó soporte para ninguno de los dos), y no ha habido versiones 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 de ruptura entre versiones menores 0.x son posibles; fija la versión que hayas verificado y consulta las notas de lanzamiento de GitHub al actualizar.

​

Actualizar

Al actualizar entre versiones menores del SDK:

1. Re-verifica el tipo de retorno de cada llamada mutante — los cambios de forma (p. ej. extInfo) llegan frecuentemente.
2. Regenera las firmas de obtención de poolInfo — un campo puede haber sido renombrado.
3. Re-verifica tu manejo de slippage; el SDK ha alternado entre comportamientos de límite automático y límite opcional entre versiones.
4. Si usas raydium.trade (enrutamiento), re-verifica la forma de la ruta — es la parte más inestable de la superficie.

​

Obtener ayuda

Para preguntas sobre SDK y API:

• Issues de GitHub — presenta en 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 para ayuda sincrónica.
• Telegram — chat de desarrolladores enlazado desde raydium.io (evita grupos de Telegram no verificados).

Para problemas de seguridad, no publiques en canales públicos — consulta security/disclosure.

​

Referencias

• sdk-api/rest-api — el complemento HTTP del SDK.
• sdk-api/trade-api — transacciones de swap construidas por servidor.
• sdk-api/anchor-idl — regenerando clientes directamente desde IDLs de programa.
• sdk-api/python-integration — equivalente en Python a través de solana-py.
• integration-guides/priority-fee-tuning — dimensionando computeBudgetConfig.

Fuentes:

• Fuente de Raydium SDK v2
• Notas de lanzamiento de Raydium SDK.