Como Usar a API Solana: Guia Completo para Desenvolvedores

E se você pudesse construir aplicativos blockchain que processam 65.000 transações por segundo com finalidade de 400 milissegundos? A API do Solana torna isso possível, oferecendo uma interface JSON-RPC que permite consultar contas, enviar transações e assinar atualizações em tempo real sem precisar gerenciar a infraestrutura de validadores por conta própria.

O desenvolvimento tradicional de blockchain força você a escolher entre velocidade e descentralização. Os 15 TPS do Ethereum criam gargalos durante o congestionamento da rede. As soluções de Camada 2 adicionam complexidade. Solana elimina essa troca através de seu consenso de prova de histórico (Proof of History) combinado com prova de participação (Proof of Stake), entregando desempenho de Web2 com garantias de Web3. Você constrói aplicativos que parecem instantâneos, mantendo a resistência à censura.

Sumário:

• Compreendendo a Arquitetura do Solana
• Configurando Seu Ambiente de Desenvolvimento
• Métodos Principais da API RPC
• Construindo Transações com Web3.js
• Melhores Práticas de Segurança
• Conclusão

Compreendendo a Arquitetura do Solana

Solana utiliza uma arquitetura única centrada na Solana Program Library (SPL) e um runtime de alta vazão. Compreender esses fundamentos ajuda você a escrever chamadas de API eficientes.

Prova de Histórico (PoH)

PoH cria um carimbo de tempo criptográfico para cada transação antes do consenso. Isso elimina a necessidade de os nós concordarem sobre o tempo, reduzindo drasticamente a latência. Quando você envia uma transação via API, ela é carimbada imediatamente e entra na fila do líder para processamento.

Contas e Programas

Diferente do modelo baseado em contas do Ethereum com armazenamento de código, Solana separa o código (programas) dos dados (contas). Os programas são stateless (sem estado) — eles contêm apenas lógica executável. As contas armazenam dados e especificam qual programa as possui. Essa arquitetura permite o processamento paralelo de transações, já que contas não sobrepostas podem ser executadas simultaneamente.

Cada conta tem um endereço único de 32 bytes derivado de uma chave pública Ed25519. As contas pagam aluguel em lamports (1 SOL = 10^9 lamports) para permanecerem on-chain. Contas isentas de aluguel — aquelas que possuem pelo menos 2 anos de aluguel — persistem indefinidamente sem decaimento.

Níveis de Compromisso

Solana oferece três níveis de confirmação:

• Processed (Processado): Transação processada pelo líder atual, mas não confirmada. Resposta mais rápida, menor certeza.
• Confirmed (Confirmado): Transação confirmada pelo cluster. Aproximadamente 5-10 segundos em média.
• Finalized (Finalizado): Transação enraizada e não pode ser revertida. Aproximadamente 12-15 segundos.

Especifique os níveis de compromisso nas chamadas de API para equilibrar velocidade e garantias de finalidade.

Configurando Seu Ambiente de Desenvolvimento

Você precisa de três componentes: a CLI do Solana para gerenciamento de chaves e implantação, um endpoint RPC para acesso ao blockchain e o SDK JavaScript para integração de aplicativos.

Instalando a CLI do Solana

Instale a ferramenta CLI oficial:

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

Verifique a instalação:

solana --version

Configure seu ambiente para Devnet (teste) ou Mainnet (produção):

# Para desenvolvimento
solana config set --url https://api.devnet.solana.com

# Para produção
solana config set --url https://api.mainnet-beta.solana.com

Criando uma Carteira

Gere um novo par de chaves para assinar transações:

solana-keygen new --outfile ~/.config/solana/id.json

A CLI exibe seu endereço público e uma frase semente de 12 palavras. Armazene a frase semente com segurança — ela recupera sua carteira. O arquivo JSON contém sua chave privada; proteja-o com permissões de arquivo (chmod 600).

Verifique seu saldo:

solana balance

Abasteça sua carteira Devnet com SOL gratuito:

solana airdrop 2

Airdrops na Devnet fornecem 2 SOL por solicitação, limitado a uma solicitação a cada 10 segundos. A Mainnet exige a compra de SOL através de exchanges.

Escolhendo um Provedor RPC

Embora Solana forneça endpoints RPC públicos, aplicações de produção precisam de infraestrutura dedicada. As opções incluem:

• Helius: https://mainnet.helius-rpc.com/?api-key=SUA_CHAVE
• QuickNode: https://solana-mainnet.g.alchemy.com/v2/SUA_CHAVE
• Chainstack: Nós dedicados de nível empresarial

Os níveis gratuitos geralmente permitem 100.000 requisições por mês. Os planos pagos oferecem limites mais altos, conexões staked para o envio de transações e APIs de taxas de prioridade.

Instalando o Web3.js

O SDK JavaScript do Solana possui duas versões principais. A Versão 2.0 representa uma reescrita completa com padrões de programação funcional, tree-shakability e zero dependências.

Instale a versão 2.0:

npm install @solana/web3.js@2 @solana-program/system @solana-program/compute-budget

Para compatibilidade com a versão 1.x:

npm install @solana/web3.js

DicaApidogSolana

Métodos Principais da API RPC do Solana

A API JSON-RPC do Solana fornece endpoints HTTP para consultas e endpoints WebSocket para assinaturas. Todas as requisições seguem a especificação JSON-RPC 2.0.

Operações de Conta

Obtenha informações e saldo da conta:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAccountInfo",
    "params": [
      "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
      {"encoding": "base58"}
    ]
  }'

Busque múltiplas contas de forma eficiente:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMultipleAccounts",
    "params": [
      [
        "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
        "4fYNw3dojWGPgVMtUU7ziPwq1r2VMGrhCrKZC9EQTbkV"
      ],
      {"encoding": "base64"}
    ]
  }'

Consultas de Bloco e Transação

Obtenha o blockhash mais recente para construção de transações:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLatestBlockhash",
    "params": [{"commitment": "confirmed"}]
  }'

Consulte o status da transação:

curl https://api.devnet.solana.com \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSignatureStatuses",
    "params": [
      [
        "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpEz7CmGVZxhEHppBrGK"
      ],
      {"searchTransactionHistory": true}
    ]
  }'

Assinaturas WebSocket

Monitore mudanças de conta em tempo real:

import { createSolanaRpcSubscriptions } from "@solana/web3.js";

const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);

const abortController = new AbortController();

await rpcSubscriptions.accountNotifications(
  "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36zEGQp",
  { commitment: "confirmed" },
  (notification) => {
    console.log("Account changed:", notification);
  },
  { abortSignal: abortController.signal }
);

// Pare de escutar após 60 segundos
setTimeout(() => abortController.abort(), 60000);

Conexões WebSocket exigem pings periódicos a cada 30-60 segundos para permanecerem ativas. Implemente a lógica de reconexão para aplicações de produção.

Dica ProfissionalApidogSolana

Construindo Transações com Web3.js

As transações do Solana consistem em uma ou mais instruções que visam programas específicos. Cada instrução especifica o programa, as contas com as quais interage e os dados serializados.

Criando uma Transação de Transferência

Transfira SOL entre contas usando o SDK versão 2.0:

import {
  airdropFactory,
  createKeyPairSignerFromBytes,
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  generateKeyPairSigner,
  lamports,
  sendAndConfirmTransactionFactory,
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getSignatureFromTransaction,
} from "@solana/web3.js";
import { getTransferSolInstruction } from "@solana-program/system";

const LAMPORTS_PER_SOL = BigInt(1_000_000_000);

// Configurar conexões RPC
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const rpcSubscriptions = createSolanaRpcSubscriptions("wss://api.devnet.solana.com");
const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });

// Gerar remetente e destinatário
const sender = await generateKeyPairSigner();
const recipient = await generateKeyPairSigner();

// Financiar remetente com airdrop
await airdropFactory({ rpc, rpcSubscriptions })({
  recipientAddress: sender.address,
  lamports: lamports(2n * LAMPORTS_PER_SOL),
  commitment: "confirmed",
});

// Obter o blockhash mais recente
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// Construir transação usando pipe
const transactionMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (msg) => setTransactionMessageFeePayer(sender.address, msg),
  (msg) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg),
  (msg) => appendTransactionMessageInstruction(
    getTransferSolInstruction({
      amount: lamports(LAMPORTS_PER_SOL / BigInt(2)),
      destination: recipient.address,
      source: sender,
    }),
    msg
  )
);

// Assinar e enviar
const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
console.log("Transação assinada");

await sendAndConfirmTransaction(signedTransaction, {
  commitment: "confirmed",
  maxRetries: 0n,
  skipPreflight: true,
});

console.log("Confirmado:", getSignatureFromTransaction(signedTransaction));

A função pipe cria uma cadeia funcional onde cada passo transforma a mensagem da transação. Este padrão elimina o estado mutável e torna a construção da transação declarativa.

Otimizando com Taxas de Prioridade

Durante o congestionamento da rede, as taxas de prioridade garantem a inclusão da transação. Busque as taxas recomendadas da API da Helius:

import { getBase64EncodedWireTransaction } from "@solana/web3.js";

const base64Transaction = getBase64EncodedWireTransaction(signedTransaction);

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=SUA_CHAVE", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "priority-fee-request",
    method: "getPriorityFeeEstimate",
    params: [{
      transaction: base64Transaction,
      options: { recommended: true }
    }]
  })
});

const { result } = await response.json();
const priorityFee = result.priorityFeeEstimate;

// Adicionar instrução de taxa de prioridade
import { getSetComputeUnitPriceInstruction } from "@solana-program/compute-budget";

const optimizedMessage = pipe(
  transactionMessage,
  (msg) => appendTransactionMessageInstruction(
    getSetComputeUnitPriceInstruction({ microLamports: priorityFee }),
    msg
  )
);

As taxas de prioridade são especificadas em micro-lamports por unidade de computação. Taxas mais altas aumentam a prioridade da transação durante o congestionamento.

Tratamento de Erros

Solana retorna códigos de erro específicos para falhas comuns:

import { isSolanaError, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE } from "@solana/web3.js";

try {
  await sendAndConfirmTransaction(signedTransaction);
} catch (error) {
  if (isSolanaError(error)) {
    switch (error.contextErrorCode) {
      case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE:
        console.error("Pré-vôo falhou:", error.message);
        break;
      default:
        console.error("Erro Solana:", error);
    }
  }
}

Erros comuns incluem fundos insuficientes (0x1), blockhash inválido (expirado) e conta em uso (conflitos de transação).

Melhores Práticas de Segurança

O alto rendimento do Solana introduz considerações de segurança únicas. Implemente essas medidas para proteger seu aplicativo e usuários.

Gerenciamento de Chaves

Nunca cometa chaves privadas para controle de versão. Use variáveis de ambiente:

# .env
SOLANA_PRIVATE_KEY="[1,2,3,...]"

Carregue as chaves com segurança em seu aplicativo:

import { createKeyPairSignerFromBytes } from "@solana/web3.js";
import { getBase58Encoder } from "@solana/codecs";

const secretKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY);
const signer = await createKeyPairSignerFromBytes(
  new Uint8Array(secretKey)
);

Para aplicações de navegador, integre adaptadores de carteira (Phantom, Solflare) em vez de lidar diretamente com chaves privadas. Os usuários assinam transações através de sua extensão de carteira, mantendo as chaves seguras.

Simulação de Transações

Sempre simule transações antes do envio para capturar erros cedo:

const simulationResult = await rpc.simulateTransaction(signedTransaction).send();

if (simulationResult.value.err) {
  console.error("Simulação falhou:", simulationResult.value.err);
  // Lidar com o erro sem desperdiçar taxas
}

A simulação executa a transação contra o estado atual sem efetivar as alterações. Ela revela erros de lógica, contas insuficientes e violações de orçamento de computação.

Proteção Contra Replay

As transações do Solana incluem um blockhash recente que expira após aproximadamente 90 segundos. Isso impede ataques de replay — enviar a mesma transação várias vezes. Para operações idempotentes, gere dados de instrução ou contas únicas por transação.

Limitação de Taxas (Rate Limiting)

Endpoints RPC públicos implementam estrita limitação de taxas (tipicamente 100 requisições a cada 10 segundos). Implemente um backoff exponencial:

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

Para produção, use nós RPC dedicados ou planos de provedores pagos com limites mais altos.

Verificação de Programas

Antes de interagir com programas de terceiros, verifique seu código-fonte em exploradores como SolanaFM ou Solscan. Procure por selos verificados indicando que o bytecode implantado corresponde aos repositórios de código aberto. Programas não verificados podem conter lógica maliciosa que drena fundos do usuário.

Conclusão

A API do Solana entrega o desempenho que as aplicações modernas demandam — finalidade em sub-segundos, alta vazão e taxas previsíveis. Você consulta estados de conta via JSON-RPC, assina atualizações em tempo real via WebSocket e constrói transações usando o SDK Web3.js 2.0 funcional. A arquitetura baseada em contas permite a execução paralela, enquanto os níveis de compromisso permitem que você escolha sua relação segurança-velocidade.

Comece com a Devnet para experimentar sem risco financeiro. Use taxas de prioridade durante o congestionamento da Mainnet. Implemente simulação e gerenciamento de chaves adequado antes de implantar aplicativos voltados para o usuário. O ecossistema do Solana fornece as ferramentas; a lógica do seu aplicativo determina o valor.

Comece a usar o Apidog hoje — importe seus endpoints de API do Solana em segundos e comece a testar sem nenhuma configuração.