Como Usar a API Alchemy: Guia Completo para Desenvolvedores Web3

Executar um dApp Ethereum em produção sem um provedor de nós confiável é praticamente um convite para problemas. Nós Geth auto-hospedados frequentemente atrasam, perdem reorganizações e apresentam gargalos assim que seu aplicativo começa a ganhar tração. A API da Alchemy resolve esse cenário, oferecendo uma camada de nó robusta e um conjunto de APIs aprimoradas, incluindo endpoints que não existem na especificação JSON-RPC original — por exemplo, buscar todos os NFTs de uma carteira em uma única chamada, sem precisar escanear cada bloco desde o gênese.

Experimente o Apidog hoje

Este guia é focado em implementação: criação de apps, autenticação, uso de métodos JSON-RPC padrão, endpoints aprimorados, assinaturas WebSocket e envio de contas inteligentes patrocinadas via Account Kit. Todos os fluxos trazem exemplos práticos em curl e Node.js. Ao final, você também entende como as unidades de computação (CU) impactam sua fatura e uso operacional.

Para testes mais amplos de infraestrutura de carteira e web3, o Apidog permite testar todos os endpoints em um ambiente centralizado. Veja também nosso guia sobre a melhor API de carteira de criptomoedas para comparar alternativas antes de escolher um provedor.

EM RESUMO

• Alchemy cobre Ethereum, Polygon, Arbitrum, Optimism, Base, Solana, zkSync, Starknet e outras redes, tudo em um único painel.
• Cada app recebe endpoints HTTPS e WebSocket para JSON-RPC padrão, além de APIs aprimoradas como alchemy_getAssetTransfers, alchemy_getTokenBalances e getNFTs.
• O SDK JavaScript (alchemy-sdk) adiciona helpers tipados para cada endpoint aprimorado, com base no ethers.js.
• O Account Kit oferece contas inteligentes ERC-4337 com patrocínio de gás, chaves de sessão e autenticação por passkey via Gas Manager.
• O uso é medido em unidades de computação (CU): camada gratuita com 300M CU/mês, Growth 400M+ CU, Scale personalizado.
• Limites de taxa são por app e por método; batch requests e o retrocesso integrado do SDK ajudam a não exceder limites.

O que é a API da Alchemy?

A Alchemy é uma plataforma para desenvolvedores web3 que oferece nós blockchain gerenciados, combinados com um mecanismo de indexação de dados. Você ganha três vantagens principais:

1. Nós JSON-RPC de alta disponibilidade em mais de 40 blockchains.
2. APIs aprimoradas que pré-indexam transferências e metadados de NFT, facilitando queries complexas.
3. Uma stack de abstração de conta (Account Kit) para UX sem gás.

Diferente da Infura (acesso bruto ao nó), a Alchemy adiciona indexação de alto nível. Por exemplo, buscar todas as transferências ERC-20 para um endereço requer só uma chamada alchemy_getAssetTransfers — enquanto em um nó padrão, você teria que iterar bloco a bloco. Isso explica porque a maioria das carteiras, dashboards DeFi e marketplaces de NFT preferem Alchemy para consultas intensas.

Autenticação e configuração

1. Crie uma conta no painel da Alchemy.
2. Clique em Criar novo aplicativo.
3. Escolha a blockchain (Ethereum, Polygon, Base etc.) e rede (mainnet ou testnet como Sepolia).
4. Cada app recebe uma chave de API exclusiva (coloque em variáveis de ambiente, nunca no client-side).

Exemplo de endpoint:

https://eth-mainnet.g.alchemy.com/v2/SUA_CHAVE_API
wss://eth-mainnet.g.alchemy.com/v2/SUA_CHAVE_API

Dicas rápidas:

• Trate a chave de API como segredo. Use variáveis de ambiente.
• Para dApps web, configure restrições de referer no painel para evitar abuso em caso de vazamento.

Instale o SDK:

npm install alchemy-sdk

Inicialize o cliente:

import { Alchemy, Network } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

const block = await alchemy.core.getBlockNumber();
console.log("Latest block:", block);

Endpoints principais

JSON-RPC padrão via HTTPS

Qualquer método JSON-RPC padrão do Ethereum está disponível. Exemplo com eth_getBalance via curl:

curl https://eth-mainnet.g.alchemy.com/v2/SUA_CHAVE_API \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBalance",
    "params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"],
    "id":1
  }'

A resposta retorna o saldo em wei (hexadecimal). O mesmo padrão vale para eth_call, eth_sendRawTransaction, eth_getLogs etc.

API aprimorada: getAssetTransfers

alchemy_getAssetTransfers retorna todas as transferências (ETH, ERC-20, ERC-721, ERC-1155, internas e externas) para um endereço em um range de blocos. Use assim:

import { Alchemy, Network, AssetTransfersCategory } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

const transfers = await alchemy.core.getAssetTransfers({
  fromBlock: "0x0",
  toAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  category: [
    AssetTransfersCategory.EXTERNAL,
    AssetTransfersCategory.ERC20,
    AssetTransfersCategory.ERC721,
  ],
  maxCount: 100,
});

for (const t of transfers.transfers) {
  console.log(`${t.asset} ${t.value} from ${t.from} to ${t.to}`);
}

API aprimorada: getTokenBalances e getNFTs

Para obter todos os tokens de uma carteira (sem saber contratos de antemão):

const balances = await alchemy.core.getTokenBalances(
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
);

for (const token of balances.tokenBalances) {
  const meta = await alchemy.core.getTokenMetadata(token.contractAddress);
  console.log(`${meta.symbol}: ${token.tokenBalance}`);
}

Para NFTs:

const nfts = await alchemy.nft.getNftsForOwner(
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
);
console.log(`Owns ${nfts.totalCount} NFTs`);

API de assinatura via WebSocket

Assine atualizações em tempo real (transações pendentes, atividade de endereço):

import { Alchemy, Network, AlchemySubscription } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET,
});

alchemy.ws.on(
  {
    method: AlchemySubscription.PENDING_TRANSACTIONS,
    toAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  },
  (tx) => console.log("Pending USDC tx:", tx.hash)
);

Ideal para bots de mempool, MEV e dashboards em tempo real sem gastar CU consultando eth_blockNumber.

Account Kit e Gas Manager

Account Kit entrega contas inteligentes prontas para produção:

• SDK React
• Implementação de contas (Light/Modular Account)
• Gas Manager para patrocinar transações

Usuários podem criar carteiras usando passkey ou e-mail, sem seed phrase ou tokens de gás. Exemplo de uso:

import { createLightAccountClient } from "@account-kit/smart-contracts";
import { alchemy, sepolia } from "@account-kit/infra";

const client = createLightAccountClient({
  transport: alchemy({ apiKey: process.env.ALCHEMY_API_KEY }),
  chain: sepolia,
  signer: yourSigner,
});

const { hash } = await client.sendUserOperation({
  uo: { target: "0x...", data: "0x", value: 0n },
});

Para fluxos de integração com carteiras embutidas, consulte nosso guia da API Privy.

Erros comuns e limites de taxa

Uso é medido em CU (unidades de computação):

• eth_call: 26 CU
• eth_getLogs: 75 CU
• alchemy_getAssetTransfers: 150 CU
• eth_getBlockByNumber: 16 CU

Camada gratuita: 300M CU/mês, limites de throughput por segundo.

Erros frequentes:

• 429 Muitas Solicitações: atingiu o limite de CU/segundo. Use backoff; o SDK já trata isso.
• 403 Proibido: lista de permissão errada ou chave desativada.
• -32600 Solicitação Inválida: JSON-RPC malformado.
• -32000 execução revertida: chamada revertida; use eth_call + ferramenta de simulação para decodificar o erro.

Dica: Use batch requests (até 1000 chamadas JSON-RPC em um POST HTTP). Isso reduz overhead de rede e pode economizar CU. Veja como testar APIs sem Postman para estratégias de batch.

Preços da Alchemy

• Gratuita: 300M CU/mês, 1 app, suporte comunidade.
• Growth: $49/mês, 400M CU, excedente cobrado por CU, analytics avançado.
• Scale: $289/mês, 1.5B CU, throughput dedicado, suporte prioritário.
• Enterprise: preço customizado, SLAs, nós privados, suporte dedicado.

CU são resetadas mensalmente. No Growth/Scale, excedente é cobrado. Na Gratuita, solicitações retornam 429 após o limite. Monitore uso no painel no primeiro mês para ajustar sua camada.

Testando a API da Alchemy com Apidog

Testar JSON-RPC manualmente é trabalhoso: POSTs com parâmetros aninhados, respostas em hexadecimal, assinaturas WebSocket complexas. O Apidog resolve isso unificando REST, GraphQL e WebSocket num só workspace. Você pode:

• Testar endpoints HTTPS da Alchemy rapidamente.
• Abrir WebSockets para <wss://eth-mainnet.g.alchemy.com/v2/...> e monitorar assinaturas em tempo real.
• Salvar sua chave de API como variável de ambiente e reutilizá-la em coleções para mainnet, Sepolia, Polygon, Base, etc.
• Criar asserções automatizadas nas respostas para detectar regressões.
• Baixe o Apidog e importe a OpenAPI da Alchemy para ter sua coleção pronta em menos de um minuto.

Perguntas Frequentes

A Alchemy é gratuita para produção?

Sim, até o limite de 300M CU/mês. Muitos dApps pequenos permanecem na camada gratuita. Se ultrapassar, o plano Growth por $49/mês é o próximo passo.

A Alchemy suporta Solana?

Sim, com RPC padrão e endpoints aprimorados para tokens/NFT. Crie um app Solana no painel para obter endpoint específico.

Posso usar a API da Alchemy sem SDK?

Sim. Todos os endpoints funcionam via HTTPS com curl, fetch ou qualquer HTTP client. O SDK é opcional e só adiciona conveniência (helpers tipados, auto-retry, reconexão WebSocket).

Diferença entre Alchemy e API da MetaMask?

MetaMask foca em UX de carteira e assinatura. Alchemy entrega infraestrutura de nós e dados. Veja nosso guia da API MetaMask para detalhes de carteira.

Como rotacionar uma chave de API da Alchemy?

Crie um novo app no painel, atualize seu ambiente, faça deploy, exclua o app antigo. Não existe rotação in-place — planeje uma janela de transição.

O Account Kit funciona em qualquer chain EVM?

Sim, cobre Ethereum, Optimism, Arbitrum, Base, Polygon e testnets. Políticas de patrocínio do Gas Manager são específicas por rede/cadeia. Configure conforme sua necessidade.