# RPC blockchain et MCP de documentation pour les agents IA

> Source: https://docs.blockvectra.com/fr/guides/ai-agents/

Commencez par le [point de terminaison MCP de documentation](https://docs.blockvectra.com/mcp) sans clé pour découvrir les méthodes JSON-RPC blockchain, les jeux de données de la Data API, les tarifs et la documentation. Les agents IA sont des utilisateurs de premier rang : les développeurs et les agents IA utilisent les mêmes API, règles, limites et tarifs.

1. **Découvrir** : utilisez le MCP de documentation, `llms.txt`, OpenAPI et le JSON public pour choisir une chaîne et une méthode. Les appels RPC sans clé sont limités aux `public.methods` de la chaîne.
2. **Ouvrir un compte via HTTP** : suivez le [guide d'inscription programmatique](https://docs.blockvectra.com/en/guides/programmatic-signup/) pour vous connecter avec une signature de portefeuille et créer une API key. L'outil MCP `how_to_get_api_key` renvoie les instructions pour ce flux HTTP distinct.
3. **Appeler les API de données** : conservez la clé dans `BLOCKVECTRA_API_KEY` et utilisez-la pour les requêtes RPC ou Data API authentifiées. Pour les outils MCP avec clé, configurez l'en-tête `x-api-key` du client ; les opérations autorisées pour chaque outil sont répertoriées ci-dessous.

## 1. Contexte lisible par machine et spécifications

BlockVectra publie des fichiers destinés aux agents LLM et aux outils de développement :

### Index llms.txt

Suivant la convention [llmstxt.org](https://llmstxt.org), ces fichiers fournissent aux agents un résumé structuré du site et de ses points de terminaison :

* **Index du site principal** : [llms.txt du site principal](https://blockvectra.com/llms.txt) — aperçu du site principal, des chaînes prises en charge, des tarifs et des API publiques.
* **Index de la documentation** : [llms.txt de la documentation](https://docs.blockvectra.com/llms.txt) — catalogue de chaque page de documentation avec son titre et sa description.

### Fichier de documentation complet (`llms-full.txt`)

* **Documentation complète** : [llms-full.txt](https://docs.blockvectra.com/llms-full.txt) — le texte intégral de chaque page de documentation en anglais dans un unique fichier Markdown en texte brut, adapté au chargement dans le prompt système d'un agent ou à l'ingestion dans un pipeline de génération augmentée de récupération (RAG).

### Spécifications OpenAPI 3.1 téléchargeables

Le site de documentation sert des fichiers YAML OpenAPI 3.1 qui peuvent être importés directement dans des frameworks d'agents, des générateurs d'outils ou des clients API :

* **Spécification de l'API JSON-RPC** : [/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml) — méthodes prises en charge, politique des méthodes par chaîne, réponses d'erreur et comptage des Compute Units.
* **Spécification de la Data API** : [/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml) — définitions des points de terminaison REST pour les blocs indexés, transactions, transferts, soldes, détenteurs et jeux de données associés.
* **Spécification de la Push API** : [/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml) — gestion des abonnements HTTP, adresses de portefeuille surveillées, événements webhook, signatures et rejeu.

Pour l'activité des adresses de portefeuille, suivez le [guide de la Push API et des Webhooks blockchain](https://docs.blockvectra.com/fr/guides/webhook-push/). Pour les notifications de paiement ERC-20 USDT / USDC, utilisez l'[exemple de récepteur de paiement](https://docs.blockvectra.com/fr/guides/stablecoin-payments/#receive-payments-with-webhooks). Les développeurs et les agents IA créent et gèrent les abonnements via la Push API HTTP avec `x-api-key` ; le MCP de documentation permet de découvrir et de lire ces guides.

Pour le versionnement des chemins, les règles de rétrocompatibilité et les recommandations pour les agents et les auteurs de SDK, consultez [Versionnement et compatibilité des API](https://docs.blockvectra.com/fr/api/versioning/). Pour des recettes prêtes à l'emploi sur les frameworks populaires (ElizaOS, viem, wagmi, Coinbase AgentKit), consultez les [Recettes pour frameworks d'agents](https://docs.blockvectra.com/fr/guides/agent-frameworks/).

### Serveur Model Context Protocol (MCP)

BlockVectra expose un serveur MCP sans état et sans clé via Streamable HTTP :

* **Point de terminaison** : [Point de terminaison MCP](https://docs.blockvectra.com/mcp) (HTTP POST recevant du JSON-RPC 2.0 ; GET renvoie 405)
* **Transport** : MCP Streamable HTTP (sans état, aucune API key requise)

#### Outils disponibles

1. `read_doc(path, lang?)` : renvoie le contenu Markdown brut de n'importe quelle page de documentation depuis `/md/{lang}/{path}.md`. Accepte les chemins relatifs internes (par ex. `quickstart`, `guides/ai-agents`, `api/json-rpc`, `chains`).
2. `search_docs(query, lang?, limit?)` : recherche dans les pages de documentation par titres, chemins et résumés.
3. `list_chains()` : lit les réseaux blockchain pris en charge, les paramètres statiques et les politiques de méthodes depuis `GET /v1/chains`.
4. `get_status()` : lit l'état de préparation du service en direct, l'état des réseaux, les dernières hauteurs de bloc et le retard de synchronisation depuis `GET /v1/status`.
5. `get_pricing()` : lit les pondérations des Compute Units (CU), les paramètres du forfait gratuit et les limites de clé par défaut depuis `GET /v1/plans`.
6. `estimate_usage(lines?, method?, calls_per_day?)` : estime les Compute Units (CU), le coût brut au tarif public et le coût net après déduction du quota gratuit de cycle pour une ou plusieurs méthodes (prend en charge le format multiligne `lines: [{method, calls_per_day}]` ou `method` et `calls_per_day` uniques). Indique également les limites de débit par clé depuis `key_defaults` et suggère le nombre d'API keys nécessaires lorsque le trafic dépasse les limites d'une seule clé.
7. `how_to_get_api_key(lang?)` : renvoie les étapes d'obtention d'une API key et les formats d'authentification des requêtes pour JSON-RPC et la Data API.
8. `get_method_info(method, chain?)` : renvoie la disponibilité sur les chaînes, la pondération en Compute Units (CU), le prix par million d'appels et le lien de documentation pour une méthode. La disponibilité JSON-RPC suit `methods.allow` et `deny` dans `GET /v1/chains` ; la couverture des jeux de données de la Data API suit `data_features` dans `GET /v1/status`, avec `data: true` dans le catalogue des chaînes.
9. `explain_error(reason?, code?, http_status?)` : recherche les explications d'erreur, les conséquences sur la facturation, la possibilité de nouvel essai et les actions de récupération à partir du catalogue d'erreurs.
10. `list_docs(lang?)` : liste toutes les pages de documentation avec leurs chemins relatifs et leurs titres depuis l'index de documentation.
11. `rpc_call(chain, method, params?)` : exécute un appel JSON-RPC 2.0 en lecture seule sur une chaîne prise en charge avec votre API key (`readOnlyHint: true`). Les méthodes d'écriture (telles que `eth_sendRawTransaction`) sont rejetées ; utilisez `send_raw_transaction` à la place. Nécessite l'en-tête `x-api-key` dans la configuration du client MCP pour un accès complet, ou utilise le point de terminaison public sans clé s'il est disponible.
12. `data_api_get(chain, path, query?)` : émet une requête GET vers la Data API pour une chaîne et un chemin pris en charge avec votre API key (`readOnlyHint: true`). Nécessite l'en-tête `x-api-key` dans la configuration du client MCP.
13. `get_account()` : interroge le solde du compte, les Compute Units (CU), les limites de débit et les paramètres de clé depuis `GET /v1/account` avec votre API key (`readOnlyHint: true`). Nécessite l'en-tête `x-api-key` dans la configuration du client MCP.
14. `get_deposit_address()` : interroge l'adresse de dépôt on-chain dédiée, les réseaux ouverts et les tokens depuis `GET /v1/topup/deposit-address` avec votre API key (`readOnlyHint: true`). Transférez uniquement vers les réseaux et tokens listés. Nécessite l'en-tête `x-api-key` dans la configuration du client MCP.
15. `send_raw_transaction(chain, raw_tx)` : diffuse une transaction brute signée vers une chaîne prise en charge via `eth_sendRawTransaction` (`destructiveHint: true`). Nécessite l'en-tête `x-api-key` dans la configuration du client MCP pour un accès complet, ou utilise le point de terminaison public sans clé s'il est autorisé sur la chaîne.

#### Outils avec clé

Les outils avec clé nécessitent une API key pour exécuter des requêtes on-chain, des transactions, des requêtes Data API ou des opérations de compte.

**Sécurité de l'API key** :

* **Lecture stricte depuis les en-têtes** : L'API key est lue uniquement à partir des en-têtes de requête HTTP du client MCP (`x-api-key: rgw_...` ou `Authorization: Bearer rgw_...`).
* **Ne jamais inclure de clés dans le chat** : Ne transmettez jamais d'API keys ou de clés privées dans les arguments d'outils et ne les collez pas dans le chat. Les arguments d'outils et l'historique du chat entrent dans les journaux de conversation et les contextes ; la transmission de clés dans les arguments sera rejetée.

S'ils sont appelés sans en-tête d'API key, ces outils renvoient `isError: true` et orientent l'agent vers `how_to_get_api_key` et le guide d'inscription programmatique.

### Connexion depuis les clients MCP

Vous pouvez vous connecter au serveur MCP de documentation BlockVectra à l'adresse `https://docs.blockvectra.com/mcp` à travers les environnements et frameworks de développement courants.

Commencez sans API key. Connectez-vous au point de terminaison MCP, appelez list\_chains, puis lisez quickstart avec read\_doc. Ajoutez une API key dans les en-têtes HTTP de votre client lorsque vous avez besoin de la Data API ou des outils de compte. L'accès RPC sans clé suit la politique de méthodes publiques de chaque chaîne.

L'en-tête `x-api-key` est facultatif. Sans API key, les clients peuvent utiliser tous les outils de documentation en lecture seule (`read_doc`, `search_docs`, `list_docs`), la découverte des chaînes (`list_chains`), le statut en direct (`get_status`), l'estimation des tarifs (`get_pricing`, `estimate_usage`), les explications d'erreurs (`explain_error`) et les méthodes autorisées sur les points de terminaison publics. Lorsque vous utilisez des outils avec clé (`rpc_call` sur des méthodes restreintes, `send_raw_transaction`, `data_api_get`, `get_account` et `get_deposit_address`), configurez l'en-tête `x-api-key` avec votre API key.

#### Claude Code

Connectez-vous au serveur MCP à l'aide de la CLI :

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp
```

Pour inclure une API key facultative pour les outils authentifiés, transmettez l'option `--header` (ou `-H`) :

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

Documentation officielle : [Documentation MCP Claude Code](https://code.claude.com/docs/en/mcp).

#### Cursor

Ajoutez le serveur à la configuration MCP de Cursor :

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cursor prend également en charge l'installation en un clic via des liens profonds (deep links) à l'aide de la configuration encodée en base64 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (représentant `{"url":"https://docs.blockvectra.com/mcp"}`) :

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9
```

Lorsque vous avez besoin d'outils authentifiés (Data API ou gestion de compte), ajoutez l'objet `headers` avec votre API key :

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Documentation officielle : [Documentation MCP Cursor](https://cursor.com/docs/context/mcp) et [Liens d'installation Cursor](https://cursor.com/docs/context/mcp/install-links).

#### VS Code

Dans VS Code, configurez le serveur dans `.vscode/mcp.json` sous la clé de premier niveau `servers` avec `type: "http"` :

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Lorsque vous avez besoin d'outils authentifiés, ajoutez l'objet `headers` :

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Lors du stockage d'identifiants sensibles, VS Code prend en charge le référencement de variables d'entrée ou de fichiers d'environnement au lieu de figer les clés en dur. Vous pouvez également ajouter des serveurs à l'aide de l'action de la palette de commandes `MCP: Add Server`.

Documentation officielle : [Documentation des serveurs MCP VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) et [Référence de configuration MCP VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

#### Codex

Ajoutez le serveur à l'aide de la CLI OpenAI Codex :

```bash
codex mcp add blockvectra --url https://docs.blockvectra.com/mcp
```

Dans `config.toml`, configurez l'URL du serveur :

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
```

Lorsque vous avez besoin d'outils authentifiés, configurez les en-têtes de requête dans `config.toml` :

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

Vous pouvez également mapper l'en-tête depuis une variable d'environnement :

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }
```

Documentation officielle : [Documentation MCP OpenAI Codex CLI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

#### Gemini CLI

Dans la configuration de la CLI Gemini, ajoutez le serveur sous `mcpServers` à l'aide de `httpUrl` pour le Streamable HTTP :

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Lorsque vous avez besoin d'outils authentifiés, ajoutez l'objet `headers` avec votre API key :

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Documentation officielle : [Documentation du serveur MCP Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

#### OpenAI Responses API

Lors de l'appel à l'API OpenAI Responses, transmettez le serveur MCP dans le tableau `tools` avec `type: "mcp"` :

```bash
OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'
```

Lorsque vous avez besoin d'outils authentifiés, incluez le champ `headers` dans la définition de l'outil :

```json
{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}
```

Documentation officielle : [Guide des outils MCP OpenAI](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) et [Référence de l'API OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/create).

#### Windsurf

Dans Windsurf, configurez le serveur sous `mcpServers` à l'aide du champ `serverUrl` :

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Lorsque vous avez besoin d'outils authentifiés, ajoutez l'objet `headers` avec votre API key :

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Windsurf prend également en charge le référencement de variables d'environnement, par exemple `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`.

Documentation officielle : [Documentation MCP Windsurf](https://docs.devin.ai/desktop/cascade/mcp).

#### Claude Desktop et claude.ai

Les connecteurs personnalisés sont configurés via l'interface utilisateur :

* **claude.ai** : Accédez à **Personnaliser** > **Connecteurs**, cliquez sur **+ Ajouter**, sélectionnez **Ajouter un connecteur personnalisé**, et saisissez l'URL :
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop** : Ouvrez le menu des paramètres du compte et configurez les connecteurs personnalisés via l'interface des connecteurs.

La connexion à l'URL permet à Claude de rechercher dans les guides, de lire la documentation Markdown, d'inspecter les chaînes prises en charge, de vérifier l'état du réseau et de calculer des estimations de tarifs sans identifiants.

Documentation officielle : [Guide des connecteurs personnalisés Claude](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

## 2. Points de terminaison JSON publics (sans clé requise)

Un agent peut inspecter les chaînes disponibles, l'état en direct et les paramètres de forfait avant d'envoyer toute requête comptabilisée. Aucun de ces points de terminaison ne nécessite d'API key :

* `GET /v1/status` et `GET /v1/chains` ne nécessitent aucune authentification et ne sont pas facturés.
* `GET /v1/plans` est public et sans authentification.

Tous trois transmettent `Access-Control-Allow-Origin: *`.

### État du service (`GET /v1/status`)

Renvoie l'état opérationnel du service et le statut de synchronisation de chaque chaîne publique :

```bash
curl -s "https://api.blockvectra.com/v1/status"
```

Champs de la réponse :

* `checked_at` : moment où l'instantané a été généré (RFC 3339 / ISO 8601 UTC).
* `gateway.status` : état de fonctionnement du service. `ok` signifie que le service est prêt ; `degraded` signifie que les requêtes payantes sont rejetées jusqu'à son rétablissement. Cette valeur est indépendante de l'état des nœuds d'une chaîne particulière.
* `chains[]` : les chaînes proposées au public :
  * `chain` : slug de la chaîne (par ex. `robinhood_mainnet`).
  * `name` : nom d'affichage lisible par l'humain.
  * `chain_id` : chain ID EIP-155 (entier décimal).
  * `jsonrpc` : indique si le JSON-RPC est disponible.
  * `data` : indique si la Data API est disponible.
  * `data_features` : fonctionnalités de la Data API disponibles pour cette chaîne (un tableau vide lorsque `data` est `false`).
  * `data_status` : état de fonctionnement de la Data API (`ok`, `syncing` ou `unavailable` ; présent uniquement lorsque `data` est `true`).
  * `status` : état des nœuds de la chaîne (`ok` ou `unavailable`).
  * `head` : informations sur le dernier bloc — `block` (dernière hauteur de bloc), `time` (horodatage du bloc) et `lag_seconds` (retard du bloc par rapport à l'heure actuelle) — ou `null` si inconnu.

Exemple de réponse :

```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
      }
    }
  ]
}
```

### Paramètres des chaînes (`GET /v1/chains`)

Renvoie les paramètres statiques de chaque chaîne publique et la politique des méthodes :

```bash
curl -s "https://api.blockvectra.com/v1/chains"
```

Champs de la réponse :

* `chains[]` : chaînes publiques et leurs paramètres statiques :
  * `chain` : slug de la chaîne.
  * `name` : nom d'affichage lisible par l'humain.
  * `chain_id` : chain ID EIP-155.
  * `jsonrpc` : indique si le JSON-RPC est disponible.
  * `data` : indique si la Data API est disponible.
  * `ws` : indique si les connexions WebSocket sont prises en charge.
  * `subscriptions` : types d'abonnements WebSocket pris en charge (par ex. `newHeads`, `logs`).
  * `methods` : politique des méthodes :
    * `allow` : noms des méthodes autorisées (par ex. `eth_call`, `debug_traceTransaction`).
    * `deny` : méthodes refusées ou modèles avec caractère générique en préfixe (par ex. `eth_newFilter`). Les méthodes refusées ont la priorité sur les méthodes autorisées.
  * `max_logs_block_range` : étendue maximale de blocs autorisée dans une seule requête `eth_getLogs`.
  * `state_window_blocks` : fenêtre d'état historique en blocs ; `null` lorsque l'historique complet est disponible.
  * `info` : données d'extension publiques par chaîne (réservé ; actuellement un objet vide `{}`).
  * `public` : configuration du point de terminaison public sans authentification (ou `null`) :
    * `url` : URL de base pour les requêtes publiques.
    * `methods` : méthodes autorisées sur le point de terminaison public.
    * `rate_limit` : limites de débit (`per_ip_rps`, `burst`, `batch_max`).
    * `history_blocks` : historique de blocs accessible sur le point de terminaison public.
    * `send_raw_rate_limit` : limites de débit pour la diffusion de transactions via `eth_sendRawTransaction`.

Exemple de réponse :

```json
{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "ws": true,
      "subscriptions": [
        "newHeads",
        "logs"
      ],
      "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,
      "info": {},
      "public": {
        "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public",
        "methods": [
          "eth_chainId",
          "net_version",
          "eth_blockNumber",
          "eth_call"
        ],
        "rate_limit": {
          "per_ip_rps": 3,
          "burst": 20,
          "batch_max": 10
        },
        "history_blocks": 128,
        "send_raw_rate_limit": {
          "per_ip_rps": 1,
          "burst": 3
        }
      }
    }
  ]
}
```

### Forfaits et pondérations des méthodes (`GET /v1/plans`)

Les paramètres de forfait sont servis à l'adresse `GET https://console-api.blockvectra.com/v1/plans`. Un agent peut interroger ce point de terminaison au moment de l'exécution pour lire les limites actives du forfait gratuit et la pondération en Compute Units (CU) de chaque méthode :

* `free` : paramètres du forfait gratuit — `signup_units` (allocation à l'inscription, en unités), `monthly_units` (seuil de recharge de cycle, en unités), `window_days` (durée du cycle d'utilisation en jours) et `max_calls_per_sec` (plafond d'appels par seconde du forfait gratuit).
* `pricing` : paramètres des forfaits payants — `units_per_usd` (unités par dollar US), `cu_per_unit` (CU par unité) et `min_topup_usd` (montant minimum de recharge en USD).
* `method_weights` : pondérations en CU par appel, chacune sous la forme `{ "method": string, "cu_weight": number }`. `method` spécifie le nom ou le modèle de la méthode JSON-RPC, les pondérations par défaut pour les méthodes non répertoriées, ou une opération de la Data API telle que `data.<op>`. Les pondérations sont définies par méthode et ne sont pas différenciées par chaîne.

## 3. Authentification et sécurité des clés

Les agents qui émettent des appels RPC doivent respecter ces règles :

* **Authentification** : transmettez l'API key de l'une des trois manières suivantes. Dans le chemin : `POST /v1/{chain}/{api_key}` — la forme utilisant le chemin prend uniquement en compte la clé présente dans le chemin et ignore les deux en-têtes. Dans l'en-tête `x-api-key` : `POST /v1/{chain}` avec `x-api-key: $BLOCKVECTRA_API_KEY`. Dans l'en-tête `Authorization` : `POST /v1/{chain}` avec `Authorization: Bearer $BLOCKVECTRA_API_KEY`. Lorsque les deux en-têtes sont présents, un en-tête `x-api-key` non vide a la priorité ; Bearer n'est utilisé que lorsque `x-api-key` est absent ou vide. La même clé fonctionne sur toutes les chaînes prises en charge et sur la Data API (qui accepte la clé uniquement dans l'en-tête `x-api-key`).
* **Sécurité de la clé** : conservez les API keys dans des variables d'environnement côté serveur (par exemple `BLOCKVECTRA_API_KEY`) ou dans un gestionnaire de secrets. N'intégrez jamais de clé dans du code de navigateur ou dans un bundle côté client. Les points de terminaison renvoient bien `Access-Control-Allow-Origin: *`, mais ils sont destinés à être appelés par des services back-end plutôt que depuis le navigateur.
* **Comptage et mises à niveau** : l'utilisation est mesurée en Compute Units (CU) : chaque méthode consomme des CU selon sa pondération, et le solde, les réserves de CU ainsi que les limites de débit du forfait gratuit sont partagés entre toutes les chaînes. Après une recharge payante, le plafond d'appels par seconde du forfait gratuit ne s'applique plus ; chaque clé conserve une limite de débit en CU et une capacité de burst. Les crédits gratuits non utilisés restent dans vos crédits et peuvent toujours être utilisés. Consultez la [page des tarifs](https://blockvectra.com/fr/pricing/) pour plus de détails.

> **Pas encore d'API key ?**
>
> Si vous possédez un portefeuille Ethereum : suivez le [guide d'inscription programmatique](https://docs.blockvectra.com/fr/guides/programmatic-signup/) pour vous inscrire et créer une clé API à l'aide d'une signature de portefeuille Ethereum, sans navigateur. L'identité d'un agent réside dans son portefeuille : si un jeton de session ou une clé est perdu, [réauthentifiez-vous avec le même portefeuille pour le récupérer](https://docs.blockvectra.com/fr/guides/programmatic-signup/#lost-your-session-or-api-key). Si vous ne possédez pas de portefeuille : demandez à l'utilisateur de se connecter sur [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F), de créer une clé et de la définir comme variable d'environnement `BLOCKVECTRA_API_KEY`. Ne demandez pas à l'utilisateur de coller la clé dans le chat.


### Consulter le solde (`GET /v1/account`)

Un agent peut vérifier le solde actuel de sa clé, les limites de CU et les paramètres de clé directement, sans consommer de Compute Units (CU). Pour le format de la requête, les limites de débit et les définitions complètes des champs de réponse, consultez [Consulter le solde : GET /v1/account](https://docs.blockvectra.com/fr/guides/billing-rules/#query-balance-get-v1account).

## 4. Flux de travail de sélection de chaîne pour les agents

Avant d'émettre des appels, un agent peut suivre les étapes suivantes :

1. **Vérifier la chaîne et la politique de ses méthodes** : appelez `GET /v1/chains`, confirmez que la chaîne ciblée existe et comporte `jsonrpc: true`, et que la méthode que vous prévoyez d'appeler est autorisée par `methods.allow` et non refusée par `methods.deny` (le refus l'emporte).
2. **Vérifier l'état en direct** : appelez `GET /v1/status` et confirmez que `gateway.status` est `ok` et que le `status` de la chaîne ciblée est `ok` ; utilisez `head.lag_seconds` pour décider si les données de la chaîne sont suffisamment récentes pour votre cas d'usage. Lorsqu'un nœud de chaîne n'est pas synchronisé, chaque méthode sauf `eth_chainId` renvoie l'erreur JSON-RPC `-32010` (HTTP 200, non facturé), afin que l'agent puisse attendre et réessayer ou choisir une autre chaîne.
3. **Envoyer la requête** : `POST /v1/{chain}` avec l'en-tête `x-api-key` et un corps JSON-RPC standard.

## 5. Exemple minimal fonctionnel

L'exemple ci-dessous lit `/v1/chains` pour choisir une chaîne autorisant `eth_blockNumber`, vérifie `/v1/status`, puis appelle `eth_blockNumber` une fois.

**cURL**

```bash
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. List public chains and their method policy
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Check the service and per-chain status
curl -s "https://api.blockvectra.com/v1/status"

# 3. Call eth_blockNumber on the chain you selected (e.g. robinhood_mainnet)
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H "x-bv-meter: 1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```


  **TypeScript**

```typescript
const apiKey = process.env.BLOCKVECTRA_API_KEY;

if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY");
}

type ChainFacts = {
  chain: string;
  jsonrpc: boolean;
  methods: { allow: string[]; deny: string[] };
};

function matches(pattern: string, method: string): boolean {
  if (pattern === "*") return true;
  if (pattern.endsWith("*")) return method.startsWith(pattern.slice(0, -1));
  return pattern === method;
}

// 1. Récupérer le catalogue public des chaînes
const chainsRes = await fetch("https://api.blockvectra.com/v1/chains");
const { chains } = (await chainsRes.json()) as { chains: ChainFacts[] };

// 2. Sélectionner une chaîne qui dessert le JSON-RPC et autorise eth_blockNumber
const selected = chains.find(
  (chain) =>
    chain.jsonrpc &&
    !chain.methods.deny.some((pattern) => matches(pattern, "eth_blockNumber")) &&
    chain.methods.allow.some((pattern) => matches(pattern, "eth_blockNumber")),
);

if (!selected) {
  throw new Error("No chain found that allows eth_blockNumber");
}

// 3. Vérifier que le service et la chaîne sélectionnée sont opérationnels
const statusRes = await fetch("https://api.blockvectra.com/v1/status");
const status = await statusRes.json();
const chainStatus = status.chains?.find(
  (chain: { chain: string }) => chain.chain === selected.chain,
);

if (status.gateway?.status !== "ok" || chainStatus?.status !== "ok") {
  throw new Error(`Chain ${selected.chain} is currently unavailable`);
}

// 4. Appeler eth_blockNumber sur la chaîne sélectionnée
const defaultEndpoint = "https://api.blockvectra.com/v1/robinhood_mainnet";
const rpcUrl = `${defaultEndpoint.slice(0, defaultEndpoint.lastIndexOf("/"))}/${selected.chain}`;
const rpcRes = await fetch(rpcUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-bv-meter": "1",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});

console.log("Response:", await rpcRes.json());
```


  **Python**

```python
import os
import requests

api_key = os.environ["BLOCKVECTRA_API_KEY"]


def matches(pattern: str, method: str) -> bool:
    if pattern == "*":
        return True
    if pattern.endswith("*"):
        return method.startswith(pattern[:-1])
    return pattern == method


# 1. Récupérer le catalogue public des chaînes
chains = requests.get("https://api.blockvectra.com/v1/chains").json()["chains"]

# 2. Sélectionner une chaîne qui dessert le JSON-RPC et autorise eth_blockNumber
selected = next(
    (
        chain
        for chain in chains
        if chain["jsonrpc"]
        and not any(matches(p, "eth_blockNumber") for p in chain["methods"]["deny"])
        and any(matches(p, "eth_blockNumber") for p in chain["methods"]["allow"])
    ),
    None,
)

if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

# 3. Vérifier que le service et la chaîne sélectionnée sont opérationnels
status = requests.get("https://api.blockvectra.com/v1/status").json()
chain_status = next(
    (c for c in status["chains"] if c["chain"] == selected["chain"]),
    None,
)

if (
    status["gateway"]["status"] != "ok"
    or chain_status is None
    or chain_status["status"] != "ok"
):
    raise RuntimeError(f"Chain {selected['chain']} is currently unavailable")

# 4. Appeler eth_blockNumber sur la chaîne sélectionnée
default_endpoint = "https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_url = f"{default_endpoint.rsplit('/', 1)[0]}/{selected['chain']}"
rpc_response = requests.post(
    rpc_url,
    headers={
        "Content-Type": "application/json",
        "x-api-key": api_key,
        "x-bv-meter": "1",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
).json()

print("Response:", rpc_response)
```


Un appel réussi renvoie un objet de réponse JSON-RPC standard :

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

Pour inspecter les frais de CU par requête et les unités de solde restantes dans les en-têtes de réponse, incluez `x-bv-meter: 1`. Pour le comportement des en-têtes et les cas d'erreur, consultez [En-têtes de réponse de tarification et de solde](https://docs.blockvectra.com/fr/guides/billing-rules/#http-status-codes-and-billing-rules).

## Prochaines étapes

* [Parcourir le répertoire des jeux de données](https://blockvectra.com/fr/data/) pour voir chaque jeu de données indexé par BlockVectra.
* [Consulter le forfait gratuit et les tarifs](https://blockvectra.com/fr/pricing/#free) pour vérifier ce que comprend votre compte.
* [Suivre le guide d'inscription programmatique](https://docs.blockvectra.com/en/guides/programmatic-signup/) pour vous inscrire et créer une API key avec une signature de portefeuille, ou [se connecter à la console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) pour créer une clé.