> ## 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 TypeScript > @raydium-io/raydium-sdk-v2 de ponta a ponta — instalação, as quatro fachadas de módulo, construção de transações e as armadilhas que pegam cada novo integrador. **Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.** [Ver versão em inglês →](/sdk-api/typescript-sdk) ## Instalação ```bash theme={null} 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`: ```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, // 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: ```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 // 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: ```ts theme={null} 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`](/pt/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: ```ts theme={null} 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`](/pt/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: * **GitHub issues** — arquivo em [github.com/raydium-io/raydium-sdk-V2/issues](https://github.com/raydium-io/raydium-sdk-V2/issues) para bugs e solicitações de recursos. A equipe Raydium monitora ativamente. * **Discord** — canal `#dev-support` em [discord.gg/raydium](https://discord.gg/raydium) para ajuda síncrona. * **Telegram** — chat do desenvolvedor vinculado de [raydium.io](https://raydium.io) (evite grupos Telegram não verificados). Para problemas de segurança, **não** poste em canais públicos — veja [`security/disclosure`](/pt/security/disclosure). ## Apontadores * [`sdk-api/rest-api`](/pt/sdk-api/rest-api) — o complemento HTTP do SDK. * [`sdk-api/trade-api`](/pt/sdk-api/trade-api) — transações de swap construídas pelo servidor. * [`sdk-api/anchor-idl`](/pt/sdk-api/anchor-idl) — regenerando clientes diretamente de IDLs de programa. * [`sdk-api/python-integration`](/pt/sdk-api/python-integration) — equivalente Python via `solana-py`. * [`integration-guides/priority-fee-tuning`](/pt/integration-guides/priority-fee-tuning) — dimensionando `computeBudgetConfig`. Fontes: * [Código-fonte do Raydium SDK v2](https://github.com/raydium-io/raydium-sdk-V2) * Notas de lançamento do Raydium SDK.