Saltar para o conteúdo principal

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.

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

​
Instalação

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ínima: Node 18+, TypeScript 5.0+, moduleResolution: "bundler" ou "node16".

​
Inicialização

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 da API de detecção de recursos na inicialização do SDK
  blockhashCommitment: "confirmed",
});
Raydium.load é assíncrono porque busca um pequeno payload /config de api-v3.raydium.io na inicialização (listando contas AmmConfig atuais, tiers de taxa, etc.). Defina disableFeatureCheck: true em ambientes offline; você terá de fornecer esses valores manualmente para alguns construtores.

​
As quatro fachadas de módulo

Uma vez carregado, o objeto raydium expõe quatro fachadas de módulo, uma por superfície de produto: 
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      // Roteamento multi-pool: quotes, route-execution (beta em 0.2.41)
raydium.token      // Auxiliares: obter lista de tokens, metadados, criação de ATA
(Sim, cinco fachadas no total — “quatro” é a forma como Raydium as agrupa publicamente, com trade e token como utilitários de suporte.)

​
Construtores de transações

Toda função mutável retorna um construtor em vez de executar imediatamente: 
const { execute, builder, transaction, innerTransactions, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    amountInA,
    amountInB,
    slippage: 0.005,
    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 assinantes acumulados. Chame .build() para obter um VersionedTransaction[]; útil quando você precisa injetar suas próprias instruções ou assinar com assinantes externos.
  • transaction / innerTransactions — os arrays brutos de instruções. Use ao construir transações compostas multi-programa.
  • extInfo — extras específicos do produto. Por exemplo, createPool retorna extInfo.poolId; createLaunchpad retorna o novo PDA de estado de lançamento.
txVersion controla o formato de transação legado vs V0. V0 (tabelas de pesquisa de endereços) é a recomendação padrão — permite que swaps maiores caibam em uma única transação.

​
Por que construtores assincronos?

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

​
Adições do módulo CLMM (versão 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, enableDynamicFee e dynamicFeeConfigId. Use isto para qualquer novo pool que necessite dos novos controles; o createPool clássico continua funcionando para pools com taxa padrão.
  • raydium.clmm.openLimitOrder — abre uma ordem limitada de um único tick em um pool que as suporta. Toma poolInfo, poolKeys, limitOrderConfig (de /main/clmm-limit-order-config), inputMint, inputAmount e o tick alvo.
  • raydium.clmm.increaseLimitOrder / decreaseLimitOrder — ajusta a porção não preenchida de uma ordem existente. Diminuir reverte em uma ordem totalmente preenchida com InvalidOrderPhase.
  • raydium.clmm.settleLimitOrder / settleAllLimitOrder — varre saída preenchida para o ATA do proprietário. Tanto o proprietário da ordem quanto o guardião limit_order_admin do pool podem chamá-los.
  • raydium.clmm.closeLimitOrder / closeAllLimitOrder — fecha ordens totalmente liquidadas para recuperar aluguel.
  • raydium.api.getClmmDynamicConfigs() / getClmmLimitOrderConfigs() — auxiliares REST que acessam os novos endpoints /main/clmm-dynamic-config e /main/clmm-limit-order-config.
Uma pequena reorganização também moveu utils/ para libraries/. Código que importava de @raydium-io/raydium-sdk-v2/utils/... deve passar para @raydium-io/raydium-sdk-v2/libraries/.... O barrel do pacote de nível superior permanece inalterado, então a maioria dos usuários nunca vê a renomeação. Walkthroughs TypeScript de ponta a ponta vivem em products/clmm/code-demos.

​
Armadilhas comuns

​
1. Incompatibilidade de cluster

A configuração de inicialização do SDK é específica de cluster. Misturar cluster: "mainnet" com uma Connection de devnet causa roteamento silencioso incorreto: o SDK cotiza contra AmmConfig de 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 prepende automaticamente uma instrução AssociatedTokenAccount::create quando detecta um ATA ausente, que custa uma pequena quantidade de aluguel. Se sua carteira está com pouco SOL, isto 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 ficar abaixo do amount-out on-chain, revertendo. Re-busque poolInfo imediatamente antes de construir transações de alto valor, ou use o computeAmountOut do SDK que re-consulta as reservas.

​
4. Taxas de prioridade

O SDK não adiciona preços de unidades de computação por padrão. Em janelas de alto volume (lançamentos de novo pool, eventos de moeda meme) isto 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,
  inputAmount: new BN(...),
  swapResult: ...,
  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 é provável que reverta. 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 number de JavaScript. Converter valores de quantidade via .toNumber() trunca silenciosamente em 2^53; para qualquer valor acima de ~9 quatrilhões (não incomum em mints de 9 decimais), isto produz o resultado errado. Mantenha tudo em BN até a renderização final da IU.

​
Política de versionamento

  • @raydium-io/raydium-sdk-v2 é o único SDK que Raydium mantém. Toda documentação, demonstrações e orientação de integração a 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 enviados (v1 nunca ganhou suporte para nenhum dos dois), e não houve lançamentos v1 desde 2024. Trate v1 como fim de vida: não o use para código novo, e migre qualquer integração v1 restante para v2.
  • O SDK v2 é pré-1.0. Mudanças significativas entre versões menores 0.x são possíveis; fixe a versão que você verificou contra e verifique as notas de lançamento do GitHub ao atualizar.

​
Atualização

Ao atualizar entre versões menores do SDK:
  1. Re-verifique o tipo de retorno de cada chamada mutável — mudanças de forma (por exemplo, extInfo) desembarcam frequentemente.
  2. Regenere assinaturas de busca de poolInfo — um campo pode ter sido renomeado.
  3. Re-verifique sua manipulação de slippage; o SDK mudou entre comportamentos de ligação automática e ligação opt-in em lançamentos.
  4. Se você usar raydium.trade (roteamento), re-verifique a forma da rota — é a parte mais instável da superfície.

​
Obtendo ajuda

Para perguntas sobre SDK e API: Para problemas de segurança, não poste em canais públicos — veja security/disclosure.

​
Apontadores

Fontes: