Executar um dApp Ethereum em produção sem um provedor de nós confiável é um caminho curto para problemas urgentes. Nós Geth auto-hospedados atrasam, perdem reorganizações e engasgam no momento em que seu aplicativo ganha tração. A API da Alchemy resolve isso, fornecendo uma camada de nó reforçada, além de um conjunto de APIs aprimoradas que a especificação JSON-RPC original nunca definiu, como obter todos os NFTs em uma carteira com uma única chamada, em vez de escanear cada bloco desde o gênese.
Este guia aborda toda a superfície da API da Alchemy: criação de um aplicativo, autenticação, chamada de métodos JSON-RPC padrão, uso de endpoints aprimorados, assinatura de transações pendentes via WebSocket e envio de contas inteligentes com patrocínio de gás através do Account Kit. Você verá exemplos em curl e Node para cada fluxo principal, e entenderá como as unidades de computação (CU) se relacionam com sua fatura mensal antes de lançar seu produto.
Se você está avaliando a infraestrutura de carteira e web3 de forma mais ampla, o Apidog ajuda você a testar todos os endpoints em um só lugar. Veja também nosso guia sobre a melhor API de carteira de criptomoedas para uma visão de mercado mais ampla antes de se comprometer com um provedor.
EM RESUMO
- A Alchemy cobre Ethereum, Polygon, Arbitrum, Optimism, Base, Solana, zkSync, Starknet e mais, tudo a partir de um único painel.
- Cada aplicativo recebe endpoints HTTPS e WebSocket para JSON-RPC padrão, além de APIs aprimoradas como
alchemy_getAssetTransfers,alchemy_getTokenBalancesegetNFTs. - O SDK da Alchemy para JavaScript (
alchemy-sdk) envolve o ethers.js e adiciona assistentes tipados para cada endpoint aprimorado. - O Account Kit disponibiliza contas inteligentes ERC-4337 com patrocínio de gás, chaves de sessão e autenticação por passkey através do Gas Manager.
- O uso é medido em unidades de computação; a camada gratuita oferece 300M CU por mês, a Growth é de 400M CU mais excedente, a Scale é personalizada.
- Os limites de taxa são por aplicativo e por método; solicitações em lote e o retrocesso integrado do SDK mantêm você dentro dos limites de aceleração.
O que é a API da Alchemy?
A Alchemy é uma plataforma de desenvolvedores web3 que opera nós blockchain gerenciados e sobrepõe um motor de indexação de dados. Você obtém três coisas que não consegue construir facilmente por conta própria: nós JSON-RPC de alta disponibilidade em mais de 40 cadeias, APIs aprimoradas que pré-indexam transferências e metadados de NFT, e uma pilha de abstração de conta (Account Kit) para uma UX sem gás.
Enquanto a Infura oferece principalmente acesso bruto ao nó, a Alchemy adiciona a camada de indexação. Buscar todas as transferências ERC-20 para um endereço leva uma única chamada alchemy_getAssetTransfers; a mesma consulta em um nó simples significa iterar por cada bloco. É por isso que a maioria das carteiras de produção, painéis DeFi e mercados de NFT usam a Alchemy para caminhos com muita leitura.
Autenticação e configuração
Crie uma conta no painel da Alchemy e clique em Criar novo aplicativo. Escolha uma cadeia (Ethereum Mainnet, Polygon, Base, etc.) e uma rede (mainnet ou uma testnet como Sepolia). Cada aplicativo recebe uma chave de API exclusiva que forma o último segmento do seu URL.
Seu endpoint HTTPS se parece com:
https://eth-mainnet.g.alchemy.com/v2/SUA_CHAVE_API
Seu endpoint WebSocket:
wss://eth-mainnet.g.alchemy.com/v2/SUA_CHAVE_API
Trate a chave de API como um segredo. Coloque-a em uma variável de ambiente, nunca em código do lado do cliente. Para dApps de navegador, use listas de permissão (restrições de referenciador) no painel da Alchemy para que uma chave vazada não possa esgotar sua cota de um domínio de invasor.
Instale o SDK:
npm install alchemy-sdk
Então inicialize um 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 sobre HTTPS
Qualquer método JSON-RPC padrão do Ethereum funciona. Aqui está eth_getBalance com 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 como uma string hexadecimal. O mesmo padrão funciona para eth_call, eth_sendRawTransaction, eth_getLogs e todos os outros métodos padrão.
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 intervalo de blocos. Uma chamada substitui milhares de consultas eth_getLogs.
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
Obter todos os tokens que uma carteira possui, sem saber os endereços de contrato de antemão, leva uma única chamada:
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, use o espaço de nomes NFT:
const nfts = await alchemy.nft.getNftsForOwner(
"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
);
console.log(`Owns ${nfts.totalCount} NFTs`);
API de Assinatura sobre WebSocket
A API de Assinatura envia atualizações em vez de fazer você consultar. Assine transações pendentes ou 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)
);
É assim que bots de mempool, observadores MEV e UIs de portfólio em tempo real se mantêm atualizados sem gastar CU em pesquisas de eth_blockNumber.
Account Kit e Gas Manager
O Account Kit é a pilha de contas inteligentes da Alchemy. Ele oferece um SDK React, uma implementação de conta de contrato inteligente (Light Account e Modular Account) e o Gas Manager para patrocinar operações de usuário. Os usuários se cadastram com uma passkey ou e-mail, recebem uma carteira inteligente e nunca precisam tocar em uma frase semente ou token de gás.
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 que combinam contas inteligentes com carteiras incorporadas, consulte nosso guia para a API da Privy, que complementa bem o Account Kit para dApps de consumidor.
Erros comuns e limites de taxa
A Alchemy mede o uso em unidades de computação (CU). Cada método tem um custo em CU: eth_call é 26 CU, eth_getLogs é 75, alchemy_getAssetTransfers é 150 e eth_getBlockByNumber é 16. A camada gratuita oferece 300M CU por mês e um limite de taxa de transferência por segundo.
Os erros que você verá com mais frequência:
- 429 Muitas Solicitações: você atingiu o limite de CU por segundo. Retroceda e tente novamente; o SDK lida com isso automaticamente.
- 403 Proibido: a lista de permissão da sua chave de API não corresponde ao referenciador, ou a chave está desativada.
- -32600 Solicitação Inválida: corpo JSON-RPC malformado. Verifique o nome do método e o array de parâmetros.
- -32000 execução revertida: a chamada do contrato foi revertida. Decodifique a razão da reversão com
eth_calle uma ferramenta de simulação.
As solicitações em lote são suas amigas. Envie até 1000 chamadas JSON-RPC em um único POST HTTP, o que amortiza a sobrecarga da rede e muitas vezes custa menos CU totais. Para fluxos de trabalho de teste mais amplos, o artigo teste de API sem Postman em 2026 aborda como gerenciar chamadas JSON-RPC em lote em uma coleção.
Preços da Alchemy
A Alchemy possui quatro camadas públicas:
- Gratuita: 300M CU por mês, 1 aplicativo, suporte da comunidade. Boa para protótipos e pequenos projetos pessoais.
- Growth: $49/mês de base, 400M CU incluídos, excedente cobrado por CU, análises avançadas.
- Scale: $289/mês, 1.5B CU, taxa de transferência dedicada, suporte prioritário.
- Empresarial: preços personalizados, SLAs, nós privados, engenharia de soluções dedicada.
As CUs são redefinidas mensalmente. Se você exceder no Growth ou Scale, paga pelo excedente; na camada Gratuita, as solicitações começarão a falhar com 429 até o próximo ciclo. Monitore o uso diariamente no painel durante o primeiro mês para poder dimensionar a camada certa.
Testando a API da Alchemy com Apidog
Depurar JSON-RPC manualmente é doloroso. Cada solicitação é um POST com um array de parâmetros aninhado, as respostas são codificadas em hexadecimal, e as assinaturas WebSocket são difíceis de inspecionar em um terminal simples. O Apidog oferece um espaço de trabalho unificado para tráfego REST, GraphQL e WebSocket, para que você possa atingir os endpoints HTTPS da Alchemy, abrir um WebSocket para wss://eth-mainnet.g.alchemy.com/v2/... e observar as assinaturas de transações pendentes transmitindo lado a lado.
Salve sua chave de API como uma variável de ambiente no Apidog e reutilize-a em coleções para mainnet, Sepolia, Polygon e Base. Crie asserções de script nos campos de resposta para detectar regressões quando a Alchemy lançar novos endpoints aprimorados. Baixe o Apidog e importe a especificação OpenAPI da Alchemy para estruturar sua coleção em menos de um minuto.
Perguntas Frequentes
A Alchemy é gratuita para uso em produção? Sim, dentro do limite de 300M CU por mês. Muitos dApps pequenos permanecem na camada Gratuita indefinidamente. Uma vez que você ultrapasse esse teto ou precise de maior taxa de transferência, a Growth por $49 é o próximo passo usual.
A Alchemy suporta Solana? Sim. A Alchemy suporta Solana mainnet e devnet com métodos RPC padrão de Solana, além de endpoints aprimorados para dados de tokens e NFT. Crie um aplicativo Solana no painel para obter um endpoint dedicado.
Posso usar a API da Alchemy sem o SDK? Absolutamente. Todos os endpoints são acessíveis via HTTPS com curl, fetch, ou qualquer cliente HTTP. O SDK é um invólucro de conveniência; ele adiciona assistentes tipados, tentativas automáticas e reconexão WebSocket, mas é opcional.
Qual a diferença entre a Alchemy e as APIs de desenvolvedor da MetaMask? A MetaMask foca na UX da carteira e assinatura; a Alchemy foca na infraestrutura de nós e dados. Elas resolvem problemas diferentes. Consulte nosso guia para a API da MetaMask para o lado da carteira.
Como rotacionar uma chave de API da Alchemy? Crie um novo aplicativo no painel, atualize seu ambiente, implante e depois exclua o aplicativo antigo. Não há rotação no local, então planeje uma breve janela de sobreposição.
O Account Kit funciona em qualquer cadeia EVM? O Account Kit suporta Ethereum, Optimism, Arbitrum, Base, Polygon e suas testnets. As políticas de patrocínio do Gas Manager são específicas da cadeia, então configure-as por rede.