# Limite de intervalo de blocos do eth_getLogs e consultas em partes

> Source: https://docs.blockvectra.com/pt-br/guides/getlogs-block-range/

## Resposta direta

Uma requisição `eth_getLogs` é limitada pelo `max_logs_block_range` da rede de destino em [GET /v1/chains](https://api.blockvectra.com/v1/chains) (para HyperEVM, 1,000 blocos), contando `toBlock − fromBlock + 1` blocos. Ultrapassar esse limite retorna HTTP 200, JSON-RPC `-32602` e `error.data.reason: logs_range_too_large`, com `retryable: false` (consulte o [catálogo de erros](https://docs.blockvectra.com/en/errors/#logs_range_too_large)). Divida o intervalo em `[from, min(from + max − 1, end)]` e avance para o fim da parte anterior mais um após o sucesso.

Salve como `logs-minimal.mjs`, defina `BLOCKVECTRA_API_KEY`, o endereço do contrato `LOG_ADDRESS` e uma janela de blocos confirmados em `FROM_BLOCK` e `TO_BLOCK`, depois execute `node logs-minimal.mjs` com Node.js 24 ou posterior. Selecione uma rede com `CHAIN`; o padrão é `robinhood_mainnet`.

```js
const { BLOCKVECTRA_API_KEY: key, LOG_ADDRESS: address, FROM_BLOCK, TO_BLOCK } = process.env;
if (!key || !/^0x[0-9a-f]{40}$/i.test(address ?? '')) throw new Error('Set BLOCKVECTRA_API_KEY and LOG_ADDRESS');
if (![FROM_BLOCK, TO_BLOCK].every(value => /^(0x[0-9a-f]+|[0-9]+)$/i.test(value ?? ''))) {
  throw new Error('Set FROM_BLOCK and TO_BLOCK to nonnegative block numbers');
}
const start = BigInt(FROM_BLOCK), end = BigInt(TO_BLOCK);
if (start > end) throw new Error('FROM_BLOCK must not exceed TO_BLOCK');
const chainSlug = process.env.CHAIN ?? 'robinhood_mainnet';
const chainsUrl = 'https://api.blockvectra.com/v1/chains';
const catalogResponse = await fetch(chainsUrl, { signal: AbortSignal.timeout(15_000) });
if (!catalogResponse.ok) throw new Error(`Chains HTTP ${catalogResponse.status}`);
const catalog = await catalogResponse.json();
const chain = catalog.chains.find(item => item.chain === chainSlug);
if (!chain || !Number.isSafeInteger(chain.max_logs_block_range) || chain.max_logs_block_range <= 0) {
  throw new Error('Missing or invalid max_logs_block_range');
}
const matches = pattern => pattern.endsWith('*') ? 'eth_getLogs'.startsWith(pattern.slice(0, -1)) : pattern === 'eth_getLogs';
if (!chain.methods?.allow?.some(matches) || chain.methods?.deny?.some(matches)) {
  throw new Error('eth_getLogs is unavailable on this chain');
}
const max = BigInt(chain.max_logs_block_range);
const rpcUrl = new URL(`./${chainSlug}`, chainsUrl).href;
const hex = value => `0x${value.toString(16)}`;
for (let from = start; from <= end;) {
  const to = from + max - 1n < end ? from + max - 1n : end;
  const response = await fetch(rpcUrl, {
    method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
    headers: { 'Content-Type': 'application/json', 'x-api-key': key },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_getLogs',
      params: [{ address, fromBlock: hex(from), toBlock: hex(to) }] }),
  });
  const body = await response.json();
  if (!response.ok || body.error || !Array.isArray(body.result)) {
    throw new Error(`RPC HTTP ${response.status}: ${JSON.stringify(body.error ?? 'Invalid result')}`);
  }
  console.log(JSON.stringify({ fromBlock: hex(from), toBlock: hex(to), result: body.result }));
  from = to + 1n;
}
```

Cada linha de saída é uma parte concluída. Qualquer erro HTTP ou JSON-RPC interrompe o exemplo sem pular a parte com falha. Consulte abaixo as orientações de lotes e limites de taxa para tratar 429.

## Limites de intervalo de blocos do eth\_getLogs

Ao chamar o método JSON-RPC `eth_getLogs`, o intervalo de blocos de uma requisição é calculado como `toBlock − fromBlock + 1` e não pode ultrapassar o `max_logs_block_range` publicado da rede de destino.

Esse limite varia por rede. Os parâmetros por rede são publicados pelo endpoint público `GET /v1/chains` (as redes estão listadas em [Redes compatíveis](https://docs.blockvectra.com/en/chains/)). Esse endpoint não exige autenticação e não é cobrado. Ao desenvolver aplicações cliente, consulte esse endpoint dinamicamente em tempo de execução, em vez de fixar os limites de intervalo de blocos no código.

Os campos de filtro `fromBlock` e `toBlock` usam `latest` como padrão quando omitidos ou `null`.

## Limites do eth\_getLogs por rede

Estes são os valores `max_logs_block_range` de cada rede publicados por [GET /v1/chains](https://api.blockvectra.com/v1/chains). "Não publicado" não significa ilimitado. Verifique também `methods.allow` e `methods.deny` antes de chamar, com deny tendo precedência; o limite de intervalo de blocos é separado dos limites de quantidade de resultados ou duração da consulta.

| Rede | Slug da rede | max_logs_block_range (blocos) |
| --- | --- | --- |
| Arbitrum One | `arb_mainnet` | 1,000 |
| Base | `base_mainnet` | 1,000 |
| BNB Smart Chain | `bsc_mainnet` | 1,000 |
| Ethereum | `eth_mainnet` | 1,000 |
| Ethereum Sepolia | `eth_sepolia` | 1,000 |
| HyperEVM | `hyperevm_mainnet` | 1,000 |
| Polygon | `polygon_mainnet` | 1,000 |
| Robinhood Chain | `robinhood_mainnet` | 1,000 |
| Robinhood Chain Testnet | `robinhood_testnet` | 1,000 |

## Mensagens de erro comuns, na íntegra

Diferencie intervalo de blocos, quantidade de resultados e duração da consulta: o mesmo código JSON-RPC pode descrever falhas diferentes.

| Texto do erro / identificador                                                         | Fonte                                                                                                                                                              | O que fazer                                                                                                                                           |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eth_getLogs block range too large: max <N> blocks`; `-32602`; `logs_range_too_large` | [Catálogo de erros BlockVectra](https://docs.blockvectra.com/en/errors/#logs_range_too_large)                                                                                                  | `<N>` é o `max_logs_block_range` da rede; reduza o intervalo antes de reenviar. Repetir sem alterações não ajuda.                                     |
| `query block range exceeds server limit, narrow your filter: <N>`                     | [Código-fonte de eth\_getLogs do Erigon](https://github.com/erigontech/erigon/blob/9e603d74f60c21ca793a03a7ce373de19aa3fdc7/rpc/jsonrpc/eth_receipts.go#L343-L347) | `<N>` é o limite de intervalo do nó; reduza o intervalo consultado antes de reenviar.                                                                 |
| `query returns too many logs, narrow your filter: <N>`                                | [Código-fonte de eth\_getLogs do Erigon](https://github.com/erigontech/erigon/blob/9e603d74f60c21ca793a03a7ce373de19aa3fdc7/rpc/jsonrpc/eth_receipts.go#L439-L442) | `<N>` é o limite de resultados do nó; reduza o intervalo e restrinja `address` e `topics`. Mesmo um único bloco pode exigir filtros mais específicos. |

Nesses templates de mensagem, `<N>` é substituído pelo limite do endpoint. Mensagens de terceiros se referem aos próprios endpoints e limites; o texto pode variar conforme a versão do cliente. Para BlockVectra, use `/v1/chains` e `error.data.reason`.

## Ultrapassar o limite de intervalo de blocos

Quando o intervalo de blocos `toBlock − fromBlock + 1` de uma requisição ultrapassa o `max_logs_block_range` da rede, a requisição é rejeitada com HTTP 200 e um erro JSON-RPC:

* **Código de erro**: `-32602`
* **Mensagem de erro**: `eth_getLogs block range too large: max <N> blocks`
* **Status de cobrança**: sem cobrança.

### Exemplo de requisição

Esta requisição ultrapassa o limite apenas se seu intervalo de blocos for maior que o `max_logs_block_range` atual da rede de destino:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getLogs",
  "params": [
    {
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a27f1"
    }
  ]
}
```

### Exemplo de resposta

Exemplo da resposta de erro correspondente:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "eth_getLogs block range too large: max <N> blocks"
  }
}
```

Onde `<N>` é o `max_logs_block_range` da rede de destino (publicado por `GET /v1/chains`).

Em uma requisição em lote com várias chamadas, se uma chamada `eth_getLogs` ultrapassar o limite de intervalo de blocos, esse item específico retorna o erro `-32602` acima e não é cobrado.

## Fazer consultas em partes

Para consultar logs em um intervalo amplo de blocos, primeiro consulte o `max_logs_block_range` da rede de destino, divida o intervalo em partes contíguas de `[from, from + max - 1]` e envie requisições sequenciais agregando os resultados.

Os exemplos abaixo usam `robinhood_mainnet` para demonstrar consultas em partes:

**cURL**

```bash
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. Read max_logs_block_range from the public chains endpoint (unauthenticated, unbilled)
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Make a single compliant request within the chain's max_logs_block_range (toBlock - fromBlock + 1)
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getLogs",
    "params": [{
      "address": "0x1111111111111111111111111111111111111111",
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a246c"
    }]
  }'
```


  **TypeScript**

```ts
const CHAIN = "robinhood_mainnet";
const RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet";

// 1. Fetch max_logs_block_range from the public GET /v1/chains endpoint (unauthenticated, unbilled)
const chainsUrl = new URL("/v1/chains", RPC_ENDPOINT);
const chainsRes = await fetch(chainsUrl);
const { chains } = (await chainsRes.json()) as {
  chains: Array<{ chain: string; max_logs_block_range: number }>;
};

const targetChain = chains.find((c) => c.chain === CHAIN);
if (!targetChain) {
  throw new Error(`Chain ${CHAIN} not found`);
}

const maxRange = targetChain.max_logs_block_range;

// 2. Query chunks sequentially over [from, from + max - 1] and aggregate results (both endpoints inclusive)
const fromBlock = 0x45a2409;
const toBlock = 0x45a2900;

const allLogs: unknown[] = [];
let cur = fromBlock;

while (cur <= toBlock) {
  const chunkEnd = Math.min(cur + maxRange - 1, toBlock);

  const res = await fetch(RPC_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.BLOCKVECTRA_API_KEY!,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "eth_getLogs",
      params: [
        {
          address: "0x1111111111111111111111111111111111111111",
          fromBlock: "0x" + cur.toString(16),
          toBlock: "0x" + chunkEnd.toString(16),
        },
      ],
    }),
  });

  const body = (await res.json()) as {
    result?: unknown[];
    error?: { code: number; message: string };
  };

  if (body.error) {
    throw new Error(`eth_getLogs error ${body.error.code}: ${body.error.message}`);
  }

  if (body.result) {
    allLogs.push(...body.result);
  }

  cur = chunkEnd + 1;
}

console.log(`Fetched ${allLogs.length} logs across blocks`);

// npx tsx example.mts
```


  **Python**

```python
import os
from urllib.parse import urljoin
import requests

CHAIN = "robinhood_mainnet"
RPC_ENDPOINT = "https://api.blockvectra.com/v1/robinhood_mainnet"

# 1. Fetch max_logs_block_range from the public GET /v1/chains endpoint (unauthenticated, unbilled)
chains_url = urljoin(RPC_ENDPOINT, "/v1/chains")
chains_res = requests.get(chains_url)
chains_res.raise_for_status()

chains = chains_res.json().get("chains", [])
target_chain = next((c for c in chains if c["chain"] == CHAIN), None)
if not target_chain:
    raise RuntimeError(f"Chain {CHAIN} not found")

max_range = target_chain["max_logs_block_range"]

# 2. Query chunks sequentially over [from, from + max - 1] and aggregate results (both endpoints inclusive)
from_block = 0x45a2409
to_block = 0x45a2900

all_logs: list = []
cur = from_block

while cur <= to_block:
    chunk_end = min(cur + max_range - 1, to_block)

    res = requests.post(
        RPC_ENDPOINT,
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["BLOCKVECTRA_API_KEY"],
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "eth_getLogs",
            "params": [
                {
                    "address": "0x1111111111111111111111111111111111111111",
                    "fromBlock": hex(cur),
                    "toBlock": hex(chunk_end),
                }
            ],
        },
    )
    res.raise_for_status()
    body = res.json()

    if "error" in body:
        err = body["error"]
        raise RuntimeError(f"eth_getLogs error {err.get('code')}: {err.get('message')}")

    all_logs.extend(body.get("result", []))
    cur = chunk_end + 1

print(f"Fetched {len(all_logs)} logs across blocks")
```


## Considerações sobre requisições em lote

Se considerar agrupar várias consultas em partes em uma única requisição JSON-RPC em lote, observe as regras de lote e capacidade de burst:

* **Limite de tamanho do lote**: requisições em lote aceitam de 1 a 100 chamadas. Enviar mais de 100 chamadas é rejeitado com HTTP 200 e código de erro `-32600 batch too large: max 100 calls` (sem cobrança).
* **Capacidade de burst por requisição**: se a soma dos pesos de CU das chamadas em uma requisição ultrapassar a capacidade de burst da API key (`burst_cu`), a requisição é rejeitada com HTTP 429 `-32022 request cost <N> CU exceeds burst capacity <M> CU` (sem cobrança); divida-a em lotes menores.
* **Capacidade insuficiente no bucket**: se a soma dos pesos completos não ultrapassar a capacidade de burst, mas o token bucket não tiver capacidade disponível suficiente, o serviço retorna HTTP 429 com código de erro `-32005 rate limit exceeded` e `Retry-After`; consulte [O que não é cobrado: códigos de erro e regras de cobrança](https://docs.blockvectra.com/en/guides/billing-rules/) para detalhes de novas tentativas e cobrança.

Portanto, para consultas de logs em grande escala, recomenda-se consultar as partes sequencialmente; se usar lotes, mantenha a quantidade de chamadas por lote pequena o suficiente para que a soma dos pesos completos permaneça dentro da capacidade de burst.

## Guias relacionados e regras de cobrança

* Consulte a [referência do método eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) para parâmetros de filtro, valores de retorno e pesos de CU.
* Consulte a [referência do erro logs\_range\_too\_large](https://docs.blockvectra.com/en/errors/#logs_range_too_large) para detalhes do erro e ações recomendadas.
* Para comparar `eth_getLogs` com os endpoints de transferências da Data API (transferências de endereços e de tokens), incluindo diferenças de cobertura e finalidade, consulte [Dados recentes do nó e histórico indexado: quando usar eth\_getLogs e quando usar a API de transferências](https://docs.blockvectra.com/en/guides/logs-vs-transfers/).
* Para detalhes completos sobre unidades de computação (CU), liquidação por hora e respostas de erro sem cobrança, consulte [O que não é cobrado: códigos de erro e regras de cobrança](https://docs.blockvectra.com/en/guides/billing-rules/).

## Próximos passos

* [Explore o diretório de conjuntos de dados](https://blockvectra.com/en/data/) para ver todos os conjuntos de dados indexados pela BlockVectra.
* [Consulte o plano gratuito e os preços](https://blockvectra.com/en/pricing/#free) para verificar o que sua conta inclui.
* [Entre no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para criar uma API key.