Une seule clé, plusieurs chaînes : adapter un exemple à une autre chaîne

1. Une seule clé sur toutes les chaînes prises en charge

La même API key fonctionne sur toutes les chaînes prises en charge pour JSON-RPC, ainsi que pour la Data API sur les chaînes où elle est disponible. Les clés appartiennent à votre compte et ne sont pas liées à une chaîne spécifique ; il n'est pas nécessaire de générer des API keys distinctes pour chaque réseau.

Les crédits et les limites de débit sont partagés entre tous les réseaux et entre l'API JSON-RPC et la Data API ; ils ne sont pas répartis par réseau. Pour les règles de facturation détaillées, consultez la page Tarifs.

• Solde mutualisé : les recharges payantes et les crédits gratuits s'appliquent à toutes les chaînes. Les appels sur n'importe quelle chaîne sont déduits du même solde de compte.
• Limites de débit mutualisées : les taux de recharge en Compute Units (CU) et les capacités de rafale (burst) s'appliquent sur l'ensemble des chaînes pour une clé donnée. Les limites d'appels par seconde du Forfait gratuit sont mutualisées entre toutes les chaînes prises en charge plutôt que réparties par chaîne.
• Évolution vers le forfait payant : après une recharge, vous n'êtes plus limité par le plafond d'appels par seconde du Forfait gratuit ; chaque clé reste soumise aux limites de débit et de rafale en CU, comme décrit dans la documentation JSON-RPC.

2. Structure des URL et paramètre {chain}

Chaque requête ciblée sur une chaîne spécifie son réseau de destination dans le chemin de l'URL à l'aide de {chain}. Le paramètre {chain} est l'identifiant slug en minuscules de la chaîne (par exemple robinhood_mainnet).

GET /v1/chains renvoie un indicateur jsonrpc et data pour chaque chaîne. Adressez une chaîne avec les URL JSON-RPC lorsqu'elle dessert JSON-RPC, et avec GET /v1/data/{chain}/… lorsque son indicateur data est à true (la Data API ne dessert que ces chaînes).

Astuce : lorsque vous transmettez votre clé via les en-têtes de requête, formatez l'URL pour qu'elle se termine par le nom de la chaîne, sans barre oblique finale. JSON-RPC est servi exclusivement à /v1/{chain} et /v1/{chain}/{api_key}. Les requêtes comportant une barre oblique finale (comme /v1/{chain}/) ou dépourvues de segment de chaîne renvoient HTTP 404 avec un corps vide. Les requêtes vers un {chain} inconnu renvoient HTTP 404 avec error.data.reason: "unknown_chain" (non facturé).

3. Découverte programmatique des chaînes et fonctionnalités

Les chaînes prises en charge et leurs fonctionnalités sont fournies de manière dynamique. Ne codez pas en dur une liste statique de chaînes dans votre application. Découvrez plutôt les réseaux disponibles et leurs capacités au moment de l'exécution :

Découvrir les informations statiques via GET /v1/chains

Ce point de terminaison public est accessible sans authentification et n'est pas facturé, renvoyant toutes les chaînes publiquement disponibles :

GET /v1/chains

Exemple de réponse :

{
  "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
    }
  ]
}

Description des champs :

• chain : identifiant slug de la chaîne (utilisé pour {chain} dans les URL)
• name : nom d'affichage lisible
• chain_id : ID de chaîne EIP-155 (entier décimal)
• jsonrpc : indique si JSON-RPC est activé
• data : indique si la Data API est activée
• methods : politique des méthodes JSON-RPC pour la chaîne, incluant allow (méthodes autorisées) et deny (méthodes explicitement refusées)
• max_logs_block_range : plage maximale de blocs autorisée dans une seule requête eth_getLogs
• state_window_blocks : taille de la fenêtre d'état historique en blocs ; null en l'absence de restriction

Vérifier l'état opérationnel via GET /v1/status

Ce point de terminaison public est sans authentification et non facturé, renvoyant l'état de préparation du service et les informations de tête de chaîne :

GET /v1/status

Exemple de réponse :

{
  "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
      }
    }
  ]
}

Description des champs :

• gateway.status : état du service (ok ou degraded)
• chains[].data_features : fonctionnalités fournies par la Data API pour cette chaîne
• chains[].status : état opérationnel du nœud (ok ou unavailable)
• chains[].head : tête du dernier bloc (block, time, lag_seconds)

4. Différences par chaîne à garder à l'esprit

Lors du passage d'une chaîne à l'autre, examinez les champs renvoyés par GET /v1/chains :

1. Autorisation des méthodes et politique (methods.allow / methods.deny) : les méthodes JSON-RPC disponibles varient d'un réseau à l'autre selon leur politique de méthode. La demande d'une méthode refusée renvoie HTTP 200 avec le code d'erreur JSON-RPC -32601 (method not available, non facturé).
2. Plage de blocs pour les logs (max_logs_block_range) : les intervalles maximaux de blocs pour les requêtes eth_getLogs diffèrent selon la chaîne. Dépasser la limite de la chaîne renvoie HTTP 200 avec le code d'erreur JSON-RPC -32602 (eth_getLogs block range too large, non facturé).
3. Fenêtre de rétention de l'état (state_window_blocks) : les chaînes conservant tout l'historique renvoient null. Sur les chaînes avec élagage d'état (pruning), les requêtes d'état historique en dehors de la fenêtre renvoient HTTP 200 avec le code d'erreur JSON-RPC -32011 (historical state is not available beyond the most recent <N> blocks, non facturé).
4. Fonctionnalités et couverture de la Data API (data / data_features) : les chaînes fournissant un jeu de données sont répertoriées sur la page Chaînes prises en charge. L'interrogation d'un jeu de données non pris en charge par une chaîne, ou d'un bloc antérieur à sa couverture indexée, renvoie HTTP 422 (error.code no_coverage, non facturé). Lorsque le service est temporairement indisponible — par exemple lorsqu'une chaîne est saturée —, les requêtes renvoient HTTP 503 avec un en-tête Retry-After (non facturé).

5. Exemples de code

Modèle de démarrage complet : blockvectra/multichain-viem

Exactement le même code fonctionne sur différentes chaînes en mettant à jour la variable de chaîne (ou en la lisant depuis GET /v1/chains), en interrogeant eth_blockNumber via JSON-RPC et la fraîcheur des données via la Data API :

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"

Exemples de réponses

Réponse réussie à l'appel JSON-RPC eth_blockNumber (facturée au poids en CU de la méthode) :

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

Réponse réussie à la requête Data API GET /v1/data/{chain}/status/freshness (facturée en CU, seules les réponses 2xx réussies sont facturées) :

{
  "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"
  }
}

Prochaines étapes

• Parcourir le catalogue des jeux de données pour découvrir chaque jeu de données indexé par BlockVectra.
• Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
• Se connecter à la console pour créer une API key.