SDK TypeScript

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

Banner de versão. Esta página documenta @raydium-io/raydium-sdk-v2@0.2.64-alpha, a versão fixada que todos os exemplos de código neste site usam. O SDK está em pré-1.0 e a superfície de tipos evoluiu entre releases — fixe sua versão.A versão foi atualizada de 0.2.42-alpha em 2026-09-09 junto com as atualizações de programa: 0.2.64-alpha é o release atual do SDK. O repositório raydium-sdk-V2-demo que as páginas de exemplos de código vinculam instala 0.2.62-alpha, então fixe qualquer um se estiver seguindo um demo verbatim. Os demos nessas páginas foram executados pela última vez contra 0.2.42-alpha (2026-04); suas assinaturas de chamada foram re-verificadas contra a fonte 0.2.64-alpha em 2026-09-09, mas trate qualquer discrepância como um bug de documentação e abra uma issue.

Instalar

npm install @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
# ou
pnpm add @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token

O SDK é escrito em TypeScript e fornece .d.ts junto com seu artefato JS. Toolchain mínimo: Node 18+, TypeScript 5.0+, moduleResolution: "bundler" ou "node16".

Inicializar

O ponto de entrada é 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,    // pula a chamada de API de detecção de recursos do SDK na inicialização
  blockhashCommitment: "confirmed",
});

Raydium.load é assíncrono porque, por padrão, carrega a lista de tokens (raydium.token.load()) de api-v3.raydium.io. Passe disableLoadToken: true para pular essa busca. A verificação de disponibilidade de features é uma chamada separada a /v3/main/AvailabilityCheckAPI e já é pulada a menos que você passe explicitamente disableFeatureCheck: false. As configurações de taxa não são buscadas no momento do load — elas vêm sob demanda de raydium.api.getCpmmConfigs() / getClmmConfigs() no primeiro uso.

As fachadas de módulos

Uma vez carregado, o objeto raydium expõe dez fachadas de módulos mais um cliente de API:

raydium.cpmm       // Pools CPMM: createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // Pools CLMM: createPool, openPositionFromBase, increasePositionFromBase,
                   //             decreaseLiquidity, harvestAllRewards, swap, limit orders, ...
raydium.liquidity  // Pools AMM v4: computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // Farm v3/v5/v6: deposit, withdraw, harvestAllRewards, create,
                   //                restartReward(s), addNewRewardToken(s)
raydium.launchpad  // LaunchLab: createLaunchpad, buyToken, buyTokenExactOut, sellToken,
                   //            claimCreatorFee, curve-rule and platform-config builders, ...
raydium.tradeV2    // Roteamento multi-pool: descoberta de rotas, compute, route-execution
raydium.marketV2   // Criação de mercado OpenBook (legado)
raydium.utils1216  // Helpers pontuais de reivindicação histórica
raydium.token      // Lista de tokens + metadados: load(), getTokenInfo()
raydium.account    // Contas de token da carteira, busca e criação de ATA
raydium.api        // O cliente REST (fetchPoolById, getCpmmConfigs, fetchLaunchConfigs, ...)

Construtores de transações

Toda função mutante retorna um builder em vez de executar imediatamente:

import { Percent } from "@raydium-io/raydium-sdk-v2";

const { execute, builder, transaction, instructionTypes, signers, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    inputAmount,              // BN — one side, not a pair
    baseIn: true,
    slippage: new Percent(1, 100),   // a Percent, not a number
    txVersion: TxVersion.V0,
  });

Campos retornados:

execute — uma função de conveniência que assina + envia. Equivalente a builder.execute.
builder — a instância TxBuilder com todas as instruções e signatários acumulados. builder.build() retorna um TxBuildData cujo transaction é uma única Transaction legada; builder.buildV0() retorna um TxV0BuildData com uma única VersionedTransaction. Apenas buildMultiTx / buildMultiTxV0 produzem um array.
transaction — a Transaction / VersionedTransaction construída.
instructionTypes / signers — os rótulos de instrução acumulados e o conjunto de signatários.
extInfo — extras específicos do produto. Por exemplo, cpmm.createPool retorna extInfo.address.{poolId, lpMint, vaultA, vaultB}; launchpad.createLaunchpad retorna extInfo.address (um LaunchpadPoolInfo mais poolId).

Não existe campo innerTransactions no tipo de retorno — desestruturá-lo é um erro de TypeScript. Builders cujo tipo de retorno é MakeMultiTxData (por exemplo clmm.harvestAllRewards, farm.harvestAllRewards, tradeV2.swap, launchpad.createLaunchpad) expõem transactions em vez disso, e o execute deles requer { sequentially: boolean } e resolve para { txIds } em vez de { txId }.

txVersion controla o formato de transação legado vs V0. V0 (tabelas de lookup de endereço) é a recomendação padrão — permite que swaps maiores caibam em uma única transação.

Por que builders assíncronos?

Quase todo builder busca internamente o estado on-chain: informações de pool (para quotes), propriedade do programa de token (para roteamento Token-2022 vs SPL), aluguel de isenção de conta (para criação de ATA), etc. O SDK faz cache agressivamente, mas a primeira chamada para um novo pool envolve round-trips de RPC. Mantenha uma instância raydium de longa duração para evitar re-buscar.

Adições do módulo CLMM (release mais recente)

A fachada CLMM ganhou superfícies para os novos recursos de taxa dinâmica, taxa de um lado e ordem limitada:

raydium.clmm.createCustomizablePool — superconjunto de createPool que aceita collectFeeOn e dynamicFeeConfig (a PublicKey da conta de configuração). Fornecer dynamicFeeConfig é o que habilita as taxas dinâmicas; não existe sinalizador enableDynamicFee separado nem dynamicFeeConfigId. O createPool clássico continua funcionando para pools com taxa padrão.
raydium.clmm.openLimitOrder — abra uma ordem limitada de um único tick. Leva poolInfo, baseIn (direção), orderTick, amount e, opcionalmente, tickArrayBitmap, noneIndex, ownerInfo. Use o helper exportado getOrderTick({ baseIn, mintADecimal, mintBDecimal, tickSpacing, price }) para quantizar o tick.
raydium.clmm.increaseLimitOrder / decreaseLimitOrder — ajuste a porção não preenchida de uma ordem existente. Ambos levam { poolInfo, limitOrder, amount }; decreaseLimitOrder adiciona um slippage opcional. Diminuir reverte em uma ordem totalmente preenchida com InvalidOrderPhase.
raydium.clmm.settleLimitOrder / settleAllLimitOrder — varre a saída preenchida para o ATA do proprietário. settleLimitOrder leva apenas { limitOrder } — sem poolInfo. Tanto o proprietário da ordem quanto o keeper limit_order_admin do programa podem chamá-lo.
raydium.clmm.closeLimitOrder / closeAllLimitOrder — feche ordens totalmente liquidadas para recuperar aluguel.
raydium.api.getClmmDynamicConfigs() — helper REST que acessa o novo endpoint /main/clmm-dynamic-config. (Não existe helper nem endpoint de configuração de ordem limitada: as ordens limitadas são indexadas por tick, não por uma conta de configuração por pool.)

O pacote não declara exports de subcaminho, portanto @raydium-io/raydium-sdk-v2/<anything> não resolve em nenhuma grafia — importe tudo do barrel de nível superior. (Internamente, src/raydium/clmm/utils/ foi renomeado para src/raydium/clmm/libraries/, mas isso nunca foi um ponto de entrada público.) Passo a passo completo em TypeScript vivem em products/clmm/code-demos.

Armadilhas comuns

1. Incompatibilidade de cluster

A configuração de inicialização do SDK é específica do cluster. Misturar cluster: "mainnet" com uma Connection devnet causa roteamento silencioso incorreto: o SDK faz quotes contra AmmConfig mainnet mas envia para devnet. Sempre passe ambos.

2. Esquecer de pré-criar ATAs

Na primeira interação com um mint, a Conta de Token Associada do usuário pode não existir. O SDK pré-anexa automaticamente uma instrução AssociatedTokenAccount::create quando detecta um ATA ausente, o que custa uma pequena quantidade de aluguel. Se sua carteira está com pouco SOL, isso falhará silenciosamente. Verifique e financie antes de tentar novamente.

3. `poolInfo` obsoleto

poolInfo é um snapshot em cache. Se o estado do pool mudou desde que você o buscou (um grande trade moveu o preço, digamos), o minAmountOut do swap pode ser computado contra o estado antigo e cair abaixo do amount-out on-chain, revertendo. Re-busque poolInfo imediatamente antes de construir transações de alto valor, ou use computeAmountOut do SDK que re-consulta as reservas.

4. Taxas de prioridade

O SDK não adiciona preços de unidade de computação por padrão. Em janelas de alto volume (lançamentos de novo pool, eventos de meme-coin), isso significa que sua transação compete com muitas outras e pode não chegar. Forneça um computeBudgetConfig explícito:

const { execute } = await raydium.cpmm.swap({
  poolInfo,
  baseIn,                    // required: which side inputAmount is denominated in
  inputAmount: new BN(...),
  swapResult: ...,           // required: from CurveCalculator.swapBaseInput/Output
  slippage: 0.005,
  txVersion: TxVersion.V0,
  computeBudgetConfig: {
    units: 250_000,          // Limite de CU
    microLamports: 50_000,   // Taxa de prioridade por CU
  },
});

Veja integration-guides/priority-fee-tuning para orientação de dimensionamento.

5. A tolerância de slippage deve corresponder ao tipo de pool

CPMM e AMM v4 são matemática CPMM (baixo impacto em trades normais). CLMM é por partes (impacto salta em cruzamentos de tick). Se você copiar uma tolerância de slippage de 0,5% de um exemplo CPMM para um swap CLMM que cruza vários ticks, a transação provavelmente reverterá. O computeAmountOut do SDK retorna priceImpact; dimensione sua tolerância acima dele.

6. `BN` vs `number`

Todos os campos de quantidade no SDK são instâncias BN de bn.js — nunca JavaScript number. Converter valores de quantidade via .toNumber() trunca silenciosamente em 2^53; para qualquer valor acima de ~9 quadrilhões (não incomum em mints de 9 casas decimais), isso produz o resultado errado. Mantenha tudo em BN até a renderização final da UI.

Política de versionamento

@raydium-io/raydium-sdk-v2 é o único SDK que Raydium mantém. Todos os docs, demos e orientação de integração o direcionam.
Um pacote v1 mais antigo (@raydium-io/raydium-sdk) existe no npm por razões históricas. A manutenção terminou após CPMM e LaunchLab serem lançados (v1 nunca ganhou suporte para nenhum dos dois), e não houve releases v1 desde 2024. Trate v1 como fim de vida: não o use para novo código e migre qualquer integração v1 restante para v2.
SDK v2 está em pré-1.0. Mudanças quebradas entre releases menores 0.x são possíveis; fixe a versão que você verificou e verifique as notas de release do GitHub ao atualizar.

Atualizando

Ao atualizar entre versões menores do SDK:

Re-verifique o tipo de retorno de toda chamada mutante — mudanças de forma (ex. extInfo) chegam frequentemente.
Regenere assinaturas de busca de poolInfo — um campo pode ter sido renomeado.
Re-verifique seu tratamento de slippage; o SDK mudou entre comportamentos de auto-bound e opt-in bound entre releases.
Se você usar raydium.tradeV2 (roteamento), re-verifique a forma da rota — é a parte mais instável da superfície. Note que a fachada foi renomeada de trade para tradeV2; o nome antigo não existe mais.

Obtendo ajuda

Para perguntas sobre SDK e API:

GitHub issues — arquivo em github.com/raydium-io/raydium-sdk-V2/issues para bugs e solicitações de recursos. O time Raydium monitora ativamente.
Discord — canal #dev-support em discord.gg/raydium para ajuda síncrona.
Telegram — chat de desenvolvedor vinculado de raydium.io (evite grupos Telegram não verificados).

Para problemas de segurança, não poste em canais públicos — veja security/disclosure.

Referências

sdk-api/rest-api — o complemento HTTP do SDK.
sdk-api/trade-api — transações de swap construídas pelo servidor.
sdk-api/anchor-idl — regenerando clientes diretamente de IDLs de programa.
sdk-api/python-integration — equivalente em Python via solana-py.
integration-guides/priority-fee-tuning — dimensionando computeBudgetConfig.

Fontes:

Fonte do Raydium SDK v2
Notas de release do Raydium SDK.

Solana fundamentals

Quick start

SDK & API

Integration guides

Instalar

Inicializar

As fachadas de módulos

Construtores de transações

Por que builders assíncronos?

Adições do módulo CLMM (release mais recente)

Armadilhas comuns

1. Incompatibilidade de cluster

2. Esquecer de pré-criar ATAs

3. `poolInfo` obsoleto

4. Taxas de prioridade

5. A tolerância de slippage deve corresponder ao tipo de pool

6. `BN` vs `number`

Política de versionamento

Atualizando

Obtendo ajuda

Referências

​Instalar

​Inicializar

​As fachadas de módulos

​Construtores de transações

​Por que builders assíncronos?

​Adições do módulo CLMM (release mais recente)

​Armadilhas comuns

​1. Incompatibilidade de cluster

​2. Esquecer de pré-criar ATAs

​3. poolInfo obsoleto

​4. Taxas de prioridade

​5. A tolerância de slippage deve corresponder ao tipo de pool

​6. BN vs number

​Política de versionamento

​Atualizando

​Obtendo ajuda

​Referências

Instalar

Inicializar

As fachadas de módulos

Construtores de transações

Por que builders assíncronos?

Adições do módulo CLMM (release mais recente)

Armadilhas comuns

1. Incompatibilidade de cluster

2. Esquecer de pré-criar ATAs

3. `poolInfo` obsoleto

4. Taxas de prioridade

5. A tolerância de slippage deve corresponder ao tipo de pool

6. `BN` vs `number`

Política de versionamento

Atualizando

Obtendo ajuda

Referências