# Uma chave, várias redes: mudando um exemplo para outra rede

> Source: https://docs.blockvectra.com/pt-br/guides/one-key-many-chains/

## 1. One key across all supported chains

A mesma API key funciona em todas as redes compatíveis para JSON-RPC e para a Data API nas redes onde ela está disponível. As chaves pertencem à sua conta e não estão vinculadas a uma rede específica; não há necessidade de gerar API keys separadas para cada rede.

Créditos e limites de taxa são compartilhados entre todas as redes e entre a API JSON-RPC e a Data API; eles não são divididos por rede. Para regras de cobrança detalhadas, consulte a [página de preços](https://blockvectra.com/en/pricing/).

* **Saldo unificado**: recargas pagas e créditos gratuitos se aplicam a todas as redes. Chamadas em qualquer rede utilizam o mesmo saldo de conta.
* **Limites de taxa unificados**: taxas de recarga de Compute Units (CU) e capacidades de rajada se aplicam a todas as redes para uma determinada chave. Os limites de chamadas por segundo do plano gratuito são unificados entre todas as redes compatíveis, em vez de divididos por rede.
* **Caminho de upgrade**: após a recarga, você não fica mais restrito ao limite de chamadas por segundo do plano gratuito; cada chave permanece sujeita aos limites de taxa e rajada de CU, conforme descrito na [documentação de JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/#method-policy).

## 2. URL structure and the `{chain}` parameter

Cada requisição no escopo de uma rede especifica sua rede de destino no caminho da URL usando `{chain}`. O parâmetro `{chain}` é o identificador slug em letras minúsculas da rede (por exemplo, `robinhood_mainnet`).

| Service                | Authentication                   | URL template                 | Description                                                      |
| ---------------------- | -------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
| JSON-RPC               | Chave no caminho da URL          | `POST /v1/{chain}/{api_key}` | Forma mais simples, adequada para curl e clientes HTTP           |
| JSON-RPC               | Chave no cabeçalho da requisição | `POST /v1/{chain}`           | Passe a chave via cabeçalho de requisição `x-api-key: {api_key}` |
| Data API               | Rotas REST                       | `GET /v1/data/{chain}/…`     | Passe a chave via cabeçalho de requisição `x-api-key: {api_key}` |
| Lista pública de redes | Não autenticado                  | `GET /v1/chains`             | Lista pública de redes e fatos estáticos (não cobrado)           |
| Status público         | Não autenticado                  | `GET /v1/status`             | Status atual do serviço e pontas da cadeia (não cobrado)         |

`GET /v1/chains` informa uma flag `jsonrpc` e uma flag `data` para cada rede. Acesse uma rede com as URLs de JSON-RPC quando ela fornecer JSON-RPC, e com `GET /v1/data/{chain}/…` quando sua flag `data` for `true` (a Data API atende apenas a essas redes).

> **Tip**: ao passar sua chave pelos cabeçalhos da requisição, formate a URL para terminar com o nome da rede, **sem** barra final. O JSON-RPC é fornecido exclusivamente em `/v1/{chain}` e `/v1/{chain}/{api_key}`. Requisições com barra final (como `/v1/{chain}/`) ou sem o segmento da rede retornam HTTP 404 com corpo vazio. Requisições para uma `{chain}` desconhecida retornam HTTP 404 com `error.data.reason: "unknown_chain"` (não cobrado).

## 3. Programmatic chain discovery and capabilities

As redes compatíveis e seus recursos são fornecidos dinamicamente. Não fixe uma lista estática de redes no código da sua aplicação. Em vez disso, descubra redes disponíveis e seus recursos em tempo de execução:

### Discover static facts via `GET /v1/chains`

Este endpoint público não é autenticado e não é cobrado, retornando todas as redes disponíveis publicamente:

```http
GET /v1/chains
```

Example response:

```json
{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "methods": {
        "allow": ["eth_blockNumber", "eth_call", "eth_chainId", "debug_traceTransaction"],
        "deny": ["eth_newFilter", "eth_newBlockFilter", "eth_newPendingTransactionFilter", "eth_getFilterLogs", "eth_getFilterChanges", "eth_uninstallFilter", "eth_subscribe", "eth_unsubscribe"]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900
    }
  ]
}
```

Field reference:

* `chain`: slug identificador da rede (usado para `{chain}` nas URLs)
* `name`: nome de exibição legível
* `chain_id`: ID de rede EIP-155 (inteiro decimal)
* `jsonrpc`: se o JSON-RPC está ativado
* `data`: se a Data API está ativada
* `methods`: política de métodos JSON-RPC para a rede, incluindo `allow` (métodos permitidos) e `deny` (métodos explicitamente negados)
* `max_logs_block_range`: intervalo máximo de blocos permitido em uma única requisição `eth_getLogs`
* `state_window_blocks`: tamanho da janela de estado histórico em blocos; `null` quando irrestrito

### Check operational health via `GET /v1/status`

Este endpoint público não é autenticado e não é cobrado, retornando a prontidão do serviço e informações da ponta da cadeia:

```http
GET /v1/status
```

Example response:

```json
{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": ["blocks", "transactions", "address_transactions", "transfers", "token_metadata", "freshness"],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}
```

Field reference:

* `gateway.status`: status do serviço (`ok` ou `degraded`)
* `chains[].data_features`: recursos fornecidos pela Data API para esta rede
* `chains[].status`: status operacional do nó (`ok` ou `unavailable`)
* `chains[].head`: ponta do bloco mais recente (`block`, `time`, `lag_seconds`)

## 4. Per-chain differences to keep in mind

Ao alternar entre redes, revise os campos fornecidos em `GET /v1/chains`:

1. **Method allowance and policy (`methods.allow` / `methods.deny`)**: os métodos JSON-RPC disponíveis variam por rede de acordo com sua política de métodos. Solicitar um método não permitido retorna HTTP 200 com código de erro JSON-RPC `-32601` (`method not available`, não cobrado).
2. **Log block range (`max_logs_block_range`)**: intervalos máximos de blocos para consultas `eth_getLogs` diferem por rede. Exceder o limite da rede retorna HTTP 200 com código de erro JSON-RPC `-32602` (`eth_getLogs block range too large`, não cobrado).
3. **State retention window (`state_window_blocks`)**: redes de histórico completo retornam `null`. Em redes com poda de estado, consultas de estado histórico fora da janela retornam HTTP 200 com código de erro JSON-RPC `-32011` (`historical state is not available beyond the most recent <N> blocks`, não cobrado).
4. **Data API features and coverage (`data` / `data_features`)**: as redes que fornecem um conjunto de dados estão listadas na página de [Redes compatíveis](https://docs.blockvectra.com/en/chains/). Consultar um conjunto de dados que uma rede não suporta, ou um bloco anterior à sua cobertura indexada, retorna HTTP `422` (`error.code` `no_coverage`, não cobrado). Quando o serviço estiver temporariamente indisponível — por exemplo, quando uma rede estiver ocupada —, as requisições retornam HTTP `503` com um cabeçalho `Retry-After` (não cobrado).

## 5. Code examples

Modelo inicial completo: [blockvectra/multichain-viem](https://github.com/blockvectra/multichain-viem)

O mesmo código é executado em redes diferentes atualizando a variável da rede (ou lendo-a de `GET /v1/chains`), consultando `eth_blockNumber` via JSON-RPC e o frescor do conjunto de dados via Data API:

**cURL**

```bash
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# Change the chain variable to target another chain from Supported Chains
CHAIN="robinhood_mainnet"

# 1. JSON-RPC: Query eth_blockNumber (POST /v1/{chain}, key in the x-api-key header).
RPC_URL="https://api.blockvectra.com/v1/$CHAIN"
curl -s "$RPC_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 2. Data API: Query dataset freshness (GET /v1/data/{chain}/status/freshness)
curl -s "https://api.blockvectra.com/v1/data/$CHAIN/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
```


  **TypeScript**

```ts
// Change this variable to target another chain, or read it dynamically from GET /v1/chains
const chain = "robinhood_mainnet";
const apiKey = process.env.BLOCKVECTRA_API_KEY!;

// 1. JSON-RPC: Call eth_blockNumber (POST /v1/{chain})
const rpcUrl = `https://api.blockvectra.com/v1/${chain}`;
const rpcResponse = await fetch(rpcUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});
const rpcResult = await rpcResponse.json();
console.log(`[${chain}] JSON-RPC blockNumber:`, rpcResult.result);

// 2. Data API: Query freshness (GET /v1/data/{chain}/status/freshness)
const dataUrl = `https://api.blockvectra.com/v1/data/${chain}/status/freshness`;
const dataResponse = await fetch(dataUrl, {
  headers: {
    "x-api-key": apiKey,
  },
});
const dataResult = await dataResponse.json();
console.log(`[${chain}] Data API freshness:`, dataResult.data);
```


  **Python**

```python
import os
import requests

# Change this variable to target another chain, or read it dynamically from GET /v1/chains
chain = "robinhood_mainnet"
api_key = os.environ["BLOCKVECTRA_API_KEY"]

# 1. JSON-RPC: Call eth_blockNumber (POST /v1/{chain})
rpc_url = f"https://api.blockvectra.com/v1/{chain}"
headers = {
    "Content-Type": "application/json",
    "x-api-key": api_key,
}
rpc_payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": [],
}
rpc_resp = requests.post(rpc_url, json=rpc_payload, headers=headers)
print(f"[{chain}] JSON-RPC blockNumber:", rpc_resp.json().get("result"))

# 2. Data API: Query freshness (GET /v1/data/{chain}/status/freshness)
data_url = f"https://api.blockvectra.com/v1/data/{chain}/status/freshness"
data_resp = requests.get(data_url, headers={"x-api-key": api_key})
print(f"[{chain}] Data API freshness:", data_resp.json().get("data"))
```


### Example responses

Resposta bem-sucedida de `eth_blockNumber` em JSON-RPC (cobrada pelo peso de CU do método):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}
```

Resposta bem-sucedida de `GET /v1/data/{chain}/status/freshness` na Data API (cobrada em CU, apenas respostas 2xx bem-sucedidas são cobradas):

```json
{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "traces",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "coverage_from_block": 72050949,
      "coverage_to_block": 72313256,
      "coverage_complete": true,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "dex_prices",
      "category": "derived",
      "max_block_number": null,
      "max_day": "2026-09-27",
      "max_time": "2026-09-27T00:00:00Z",
      "seconds_behind": 99667,
      "blocks_behind": null,
      "days_behind": 1,
      "checked_at": "2026-09-28T03:41:10Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72313256,
    "safe_block": 72313100,
    "finalized_block": 72313000,
    "coverage": "full",
    "refreshed_at": "2026-09-28T03:41:10Z"
  }
}
```

## Next steps

* [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.