> ## 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 completo — instalação, as quatro fachadas de módulos, construção de transações e as armadilhas que pegam todo 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)
**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`](https://github.com/raydium-io/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](https://github.com/raydium-io/raydium-docs-v1/issues/new).
## Instalar
```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ínimo: Node 18+, TypeScript 5.0+, `moduleResolution: "bundler"` ou `"node16"`.
## Inicializar
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 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:
```ts theme={null}
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:
```ts theme={null}
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/` 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`](/pt/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:
```ts theme={null}
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`](/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 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:
1. Re-verifique o tipo de retorno de toda chamada mutante — mudanças de forma (ex. `extInfo`) chegam frequentemente.
2. Regenere assinaturas de busca de `poolInfo` — um campo pode ter sido renomeado.
3. Re-verifique seu tratamento de slippage; o SDK mudou entre comportamentos de auto-bound e opt-in bound entre releases.
4. 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](https://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](https://discord.gg/raydium) para ajuda síncrona.
* **Telegram** — chat de 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).
## Referências
* [`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 em Python via `solana-py`.
* [`integration-guides/priority-fee-tuning`](/pt/integration-guides/priority-fee-tuning) — dimensionando `computeBudgetConfig`.
Fontes:
* [Fonte do Raydium SDK v2](https://github.com/raydium-io/raydium-sdk-V2)
* Notas de release do Raydium SDK.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.