Visão Geral da API de Transações

Construtor de transações de swap no lado do servidor para Solana.

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

Ver versão em inglês →

​

O que é a API de Transações?

A API de Transações do Raydium (Route V2) é um serviço no lado do servidor que constrói transações de swap no Solana serializadas, sem exigir que clientes mantenham uma conexão RPC ou integrem todo o SDK do Raydium. Isso simplifica drasticamente a integração para:

• Frontends web que não podem executar um cliente RPC local
• Aplicações móveis com recursos limitados
• Bots de trading headless
• Agregadores e provedores de carteira

Em vez de realizar roteamento complexo de pools e construção de transações no cliente, você solicita quotes de swap e construção de transações à nossa API, depois assina e transmite o resultado usando qualquer RPC do Solana.

​

Visão Geral do Fluxo de Trabalho

A API de Transações separa as responsabilidades em duas fases:

​

1. Fase de Cálculo: Obter um Quote

Chame /compute/swap-base-in ou /compute/swap-base-out para receber o output esperado do swap (ou input necessário) com base nos estados atuais dos pools. Este endpoint é somente leitura e não requer assinatura:

GET /compute/swap-base-in?inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0

A resposta inclui:

• Quantidade de output esperada
• Quebra de rota (quais pools e fontes de liquidez são usadas)
• Impacto de preço

​

2. Fase de Transação: Construir e Assinar

Uma vez que você tenha a resposta de cálculo, passe-a (junto com carteira e configuração) para /transaction/swap-base-in ou /transaction/swap-base-out:

POST /transaction/swap-base-in
Content-Type: application/json

{
  "wallet": "YourWalletAddress",
  "swapResponse": { ...response from /compute/swap-base-in },
  "txVersion": "V0",
  "computeUnitPriceMicroLamports": "1000",
  "wrapSol": false,
  "unwrapSol": false,
  "inputAccount": "TokenAccount1...",
  "outputAccount": "TokenAccount2..."
}

A resposta contém:

• Uma transação versionada codificada em base64 pronta para assinar
• Endereços de tabelas de busca de endereço (se txVersion=V0)

Seu cliente então:

1. Decodifica a transação
2. Assina-a com a chave privada do usuário
3. Transmite via qualquer RPC do Solana
4. Aguarda confirmação

​

Endpoints de Cálculo

​

GET /compute/swap-base-in

Caso de uso: Usuário especifica o amount de entrada, computamos o output.

Parâmetros de query obrigatórios:

• inputMint – Endereço de mint do token que você está enviando
• outputMint – Endereço de mint do token que você quer
• amount – Amount de entrada em lamports (menor unidade)
• slippageBps – Slippage máximo aceitável em basis points (0–10000)
• txVersion – V0 ou LEGACY

Opcional:

• referrerBps – Se você tem uma autoridade de referenciador, basis points do output para coletar como taxa de referenciador

​

GET /compute/swap-base-out

Caso de uso: Usuário especifica o output desejado, computamos o input necessário.

Parâmetros de query obrigatórios:

• inputMint, outputMint, amount (output desejado), slippageBps, txVersion

Nota: Sem basis points de referenciador para base-out (ainda não implementado).

​

Endpoints de Transação

​

POST /transaction/swap-base-in

Constrói uma transação para um amount de entrada fixo.

Body obrigatório:

• wallet – Seu endereço de carteira para assinatura
• swapResponse – O objeto completo de resposta de cálculo
• txVersion – Versão de transação
• computeUnitPriceMicroLamports – Taxa de prioridade em micro-lamports

Opcional:

• wrapSol – Se verdadeiro, envolve SOL nativo para entrada
• unwrapSol – Se verdadeiro, desembrulha WSOL em SOL na saída
• inputAccount – Conta de token para entrada (obrigatória se não estiver envolvendo SOL)
• outputAccount – Conta de token para saída
• nonceInfo – Nonce durável para assinatura offline
• jitoInfo – Parâmetros de pacote de proteção MEV do Jito
• referrerWallet – Carteira do referenciador para coleta de taxa

​

POST /transaction/swap-base-out

Constrói uma transação para um amount de saída fixo.

Mesmos parâmetros que base-in, exceto:

• Campo referrerInfo está atualmente comentado (ainda não implementado)

​

Envelope de Resposta

Todos os endpoints retornam um envelope padrão:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "version": "V1",
  "data": { ... }
}

Em caso de erro, success é false e msg contém o código de erro (por exemplo, REQ_WALLET_ERROR, REQ_SLIPPAGE_BPS_ERROR).

​

Forma de Resposta de Transação

Uma resposta de transação bem-sucedida fica assim:

{
  "id": "...",
  "success": true,
  "version": "V1",
  "data": {
    "transaction": "AgABB...",  // Base64-encoded transaction
    "addressLookupTableAddresses": ["Address1...", "Address2..."]  // For V0 only
  }
}

​

Exemplo de Integração

Aqui está um fluxo típico em pseudocódigo:

// 1. Get quote
const quote = await fetch(
  'https://transaction-v1.raydium.io/compute/swap-base-in?' +
  'inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0'
).then(r => r.json());

// 2. Validate quote
if (!quote.success) {
  throw new Error(quote.msg);
}

// 3. Build transaction
const tx = await fetch(
  'https://transaction-v1.raydium.io/transaction/swap-base-in',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      wallet: userWalletAddress,
      swapResponse: quote,
      txVersion: 'V0',
      computeUnitPriceMicroLamports: '1000',
      inputAccount: userInputTokenAccount,
      outputAccount: userOutputTokenAccount,
    }),
  }
).then(r => r.json());

// 4. Decode and sign
const transaction = VersionedTransaction.deserialize(
  Buffer.from(tx.data.transaction, 'base64')
);
transaction.sign([userKeypair]);

// 5. Send via RPC
const rpc = new Connection('https://api.mainnet-beta.solana.com');
const sig = await rpc.sendTransaction(transaction);
await rpc.confirmTransaction(sig);

​

Parâmetros-Chave Explicados

​

txVersion

• V0: Transação Solana moderna com Address Lookup Tables (ALTs). Tamanho de serialização menor, taxas menores.
• LEGACY: Formato de transação pré-ALT. Maior, mas funciona com todos os endpoints RPC.

Escolha V0 quando possível; volte para LEGACY se seu RPC ou carteira não suportar ALTs.

​

computeUnitPriceMicroLamports

Taxa de prioridade para inclusão mais rápida em blocos. Defina como 0 para sem taxa de prioridade, ou valores mais altos (por exemplo, 1000) para competir em redes congestionadas. As unidades são micro-lamports por unidade de computação.

​

slippageBps

Tolerância de slippage máxima em basis points. 100 = 1%, 50 = 0,5%.

• Use valores menores (por exemplo, 25–50 bps) para swaps mais estáveis
• Aumente para pares voláteis ou de baixa liquidez

​

wrapSol e unwrapSol

• wrapSol: Se true, a API envolve seu SOL nativo em WSOL. Nenhum inputAccount necessário.
• unwrapSol: Se true, a API desembrulha o WSOL de saída de volta ao SOL nativo. Nenhum outputAccount necessário.

Se ambos forem false, você deve fornecer contas de token explícitas.

​

Endpoints de Rede

Rede	Mainnet	Devnet
Host	transaction-v1.raydium.io	transaction-v1-devnet.raydium.io
Protocolo	HTTPS	HTTPS

​

Códigos de Erro

Mensagens de erro comuns:

Código	Significado
REQ_SLIPPAGE_BPS_ERROR	Slippage é inválido ou fora do intervalo
REQ_INPUT_MINT_ERROR	Endereço de mint de entrada é inválido
REQ_OUTPUT_MINT_ERROR	Endereço de mint de saída é inválido
REQ_AMOUNT_ERROR	Amount não é um número válido
REQ_TX_VERSION_ERROR	txVersion deve ser V0 ou LEGACY
REQ_WALLET_ERROR	Endereço de carteira é inválido
REQ_INPUT_ACCOUT_ERROR	Conta de token de entrada faltando ou inválida
REQ_OUTPUT_ACCOUT_ERROR	Conta de token de saída faltando ou inválida
UNKNOWN_ERROR	Erro no servidor; verifique seus parâmetros de requisição

​

Veja Também

• Especificação OpenAPI
• Guia de Integração com Agregador