HyperEVM-RPC-Ratenlimits und Log-Backfill

Direkte Antwort

Der standardmäßige offizielle öffentliche HyperEVM-RPC erlaubt 50 Blöcke pro eth_getLogs-Abfrage (Quelle: offizielle JSON-RPC-Dokumentation von Hyperliquid). Auf BlockVectra decken authentifizierte eth_getLogs-Anfragen bis zu 1,000 Blöcke pro Abfrage ab (hyperevm_mainnet.max_logs_block_range aus GET /v1/chains), einschließlich beider Endpunkte. Eine breitere Spanne gibt HTTP 200, JSON-RPC -32602 und logs_range_too_large mit retryable: false zurück (siehe den Fehlerkatalog); teilen Sie in [from, min(from + max − 1, end)] auf, speichern Sie Ihren Cursor und rücken Sie nach erfolgreichem Abschluss auf das Ende plus eins vor, um Durchläufe fortzusetzen. Das Ratenlimit pro IP des offiziellen öffentlichen RPCs und die Key-Limits von BlockVectra werden separat unter Ratenlimits des offiziellen öffentlichen RPCs und 429 sowie in den Dienstparametern unten beschrieben.

• Erster Schritt: Lesen Sie den neuesten Block ohne API key aus mit dem unten stehenden curl-Befehl.
• Abgeschlossen, wenn: Das Backfill-Skript fromBlock, toBlock und ein result-Array für jedes Segment in Ihrem gewählten Fenster ausgibt; ein leeres Array bedeutet, dass in diesem Segment keine passenden Logs vorliegen.

Chain-Parameter und Zugriffsoptionen.

Aufgaben, die dieser Leitfaden abdeckt

• HyperEVM-RPC testen mit einer öffentlichen Leseoperation über viem oder ethers, bevor authentifizierte Methoden ausgewählt werden.
• Begrenztes Log-Fenster nachholen innerhalb des HyperEVM-eth_getLogs-Limits, mit Wiederholungsentscheidungen basierend auf dem zurückgegebenen Fehler.
• Adressaktivität auslesen über indexierte Transaktionen und Transfers mit einem Key, unter Prüfung der zurückgegebenen Abdeckungs- und Aktualitäts-Metadaten.

Dreistufige Aufgabe: Begrenztes HyperEVM-Log-Fenster nachholen

Lesen Sie den neuesten Block ohne Key aus, erstellen Sie einen Key und rufen Sie anschließend Event-Logs für einen Contract über ein begrenztes Blockfenster ab.

Wählen Sie den benötigten Contract und das Blockfenster aus. Diese Aufgabe deckt dieses begrenzte Fenster ab; sie garantiert keinen vollständigen Contract-Verlauf.

1. Den neuesten Block ohne API key auslesen

curl -sS "https://api.blockvectra.com/v1/hyperevm_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Das JSON-RPC-result ist die neueste Blocknummer in Hexadezimalform. Dies ist die von GET /v1/chains veröffentlichte HyperEVM-public.url. Die public.methods des öffentlichen Endpunkts enthalten kein eth_getLogs; Schritt 3 erfordert einen Key.

2. Einen API key erstellen

3. Logs mit Ihrem Key nachholen

Vollständige Starter-Vorlage: blockvectra/hyperevm-backfill

Speichern Sie das folgende Skript als hyperevm-task.ts. Es läuft unter Node.js 24 oder höher ohne zusätzliche Pakete. Setzen Sie BLOCKVECTRA_API_KEY auf Ihren gespeicherten Key und LOG_ADDRESS auf die emittierende Contract-Adresse, die Sie prüfen möchten; behalten Sie den Key auf Ihrem Server oder in einem lokalen Terminal.

export BLOCKVECTRA_API_KEY='replace-with-your-key'
export LOG_ADDRESS='replace-with-contract-address'
node hyperevm-task.ts

Standardmäßig ruft das Skript die neuesten max_logs_block_range-Blöcke ab (oder weniger nahe dem Genesis-Block). Es liest dieses Limit zur Laufzeit aus /v1/chains aus. Um ein anderes begrenztes Fenster auszuwählen, setzen Sie vor der Ausführung sowohl FROM_BLOCK als auch TO_BLOCK auf dezimale oder hexadezimale 0x-Blocknummern. Größere Fenster werden in aufeinanderfolgende Segmente unterteilt, von denen jedes höchstens dem veröffentlichten Limit entspricht.

const apiKey = process.env.BLOCKVECTRA_API_KEY;
const address = process.env.LOG_ADDRESS;
if (!apiKey || apiKey === "replace-with-your-key") throw new Error("Set BLOCKVECTRA_API_KEY");
if (!address || !/^0x[0-9a-f]{40}$/i.test(address)) throw new Error("Set LOG_ADDRESS to a contract address");

const fromBlock = process.env.FROM_BLOCK;
const toBlock = process.env.TO_BLOCK;
if ((fromBlock !== undefined || toBlock !== undefined) && (!fromBlock || !toBlock)) {
  throw new Error("Set both FROM_BLOCK and TO_BLOCK");
}

const chainsUrl = "https://api.blockvectra.com/v1/chains";
const rpcUrl = new URL("./hyperevm_mainnet", chainsUrl).href;
async function readJson(url: string) {
  const response = await fetch(url, { signal: AbortSignal.timeout(15_000) });
  if (!response.ok) throw new Error(`Metadata HTTP ${response.status}`);
  return response.json();
}
const catalog = await readJson(chainsUrl);
const chain = catalog.chains.find((item: { chain: string }) => item.chain === "hyperevm_mainnet");
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");
}
if (!chain.methods.allow.includes("eth_getLogs") || chain.methods.deny.includes("eth_getLogs")) {
  throw new Error("eth_getLogs is unavailable on this chain");
}
const maxRange = BigInt(chain.max_logs_block_range);
const plans = await readJson("https://console-api.blockvectra.com/v1/plans");
function weight(method: string): bigint {
  const row = plans.method_weights.find((item: { method: string }) => item.method === method);
  if (!row || !Number.isSafeInteger(row.cu_weight) || row.cu_weight <= 0) {
    throw new Error(`Missing or invalid CU weight for ${method}`);
  }
  return BigInt(row.cu_weight);
}
const headWeight = weight("eth_blockNumber");
const logsWeight = weight("eth_getLogs");

type RpcBody = {
  result?: unknown;
  error?: { code: number; data?: { retryable?: boolean } };
};
async function rpc(method: string, params: unknown[]): Promise<unknown> {
  for (let attempt = 0; attempt < 4; attempt++) {
    const response = await fetch(rpcUrl, {
      method: "POST",
      redirect: "error",
      headers: { "Content-Type": "application/json", "x-api-key": apiKey! },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
      signal: AbortSignal.timeout(15_000),
    });
    const body = await response.json() as RpcBody;
    if (response.ok && !body.error && body.result !== undefined) return body.result;
    if (body.error?.data?.retryable !== true || attempt === 3) {
      throw new Error(`RPC failed: HTTP ${response.status}, code ${body.error?.code ?? "unknown"}`);
    }
    const retryAfter = response.headers.get("Retry-After");
    const delay = retryAfter === null ? 0 : /^\d+$/.test(retryAfter)
      ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
    if (delay > 30_000) throw new Error("Retry-After exceeds 30 seconds; rerun later");
    const backoff = 1000 * 2 ** attempt + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, Number.isFinite(delay) ? delay : 0)));
  }
  throw new Error("Retry limit reached");
}
function block(value: string): bigint {
  if (!/^(0x[0-9a-f]+|[0-9]+)$/i.test(value)) throw new Error("Invalid block number");
  return BigInt(value);
}
const head = await rpc("eth_blockNumber", []);
if (typeof head !== "string" || !/^0x[0-9a-f]+$/i.test(head)) throw new Error("Invalid chain head");
const latest = block(head);
const end = toBlock ? block(toBlock) : latest;
const start = fromBlock ? block(fromBlock)
  : end >= maxRange - 1n ? end - maxRange + 1n : 0n;
if (start > end || end > latest) throw new Error("Require 0 <= FROM_BLOCK <= TO_BLOCK <= latest");
const chunks = (end - start + maxRange) / maxRange;
console.error(`Window ${start}..${end}; chunks=${chunks}; estimated CU=${headWeight + chunks * logsWeight}`);

const hex = (value: bigint) => `0x${value.toString(16)}`;
for (let from = start; from <= end; from += maxRange) {
  const to = from + maxRange - 1n < end ? from + maxRange - 1n : end;
  const result = await rpc("eth_getLogs", [{ address, fromBlock: hex(from), toBlock: hex(to) }]);
  if (!Array.isArray(result)) throw new Error("Expected eth_getLogs result array");
  console.log(JSON.stringify({ fromBlock: hex(from), toBlock: hex(to), result }));
}

Anfragen laufen sequenziell. Ein JSON-RPC-Fehler wird nur wiederholt, wenn error.data.retryable true ist, mit höchstens vier Versuchen pro Anfrage, exponentiellem Backoff und Jitter sowie Unterstützung für Retry-After-Sekunden oder ein HTTP-Datum. Eine Wartezeit von mehr als 30 Sekunden stoppt das Skript, damit Sie es später erneut ausführen können. Netzwerkfehler, Timeouts, fehlerhafte Antworten und nicht wiederholbare Fehler führen zum sofortigen Abbruch; das Skript beendet sich erfolglos, anstatt einen vollständigen Backfill zu melden.

Jede Standardausgabezeile enthält fromBlock, toBlock und das result-Array eines Segments. result: [] bedeutet, dass in diesem Segment keine übereinstimmenden Logs vorliegen. Lesen Sie diese Felder in jedem Log aus:

Der neueste Block ist keine Finalitätsmarkierung. Wenn Sie ein stabiles historisches Fenster benötigen, wählen Sie einen bestätigten TO_BLOCK Ihrer Anwendung und berücksichtigen Sie Chain-Reorganisationen.

Für ein Fenster von B = TO_BLOCK − FROM_BLOCK + 1 Blöcken und das veröffentlichte Limit L beträgt die Segmentanzahl N = ceil(B / L). Lesen Sie method_weights[].cu_weight für eth_getLogs und eth_blockNumber aus GET /v1/plans aus. Das Skript gibt eine Schätzung auf der Standardfehlerausgabe aus: N × weight(eth_getLogs) + weight(eth_blockNumber), einschließlich der authentifizierten Head-Abfrage. Dies schließt zusätzliche Aufrufe und etwaige abrechenbare Wiederholungsversuche aus; siehe Abrechnungsregeln für die Abrechnung. CU hängt von den Aufrufen ab, nicht von der Anzahl der zurückgegebenen Logs.

Event-Zustellung: Verwenden Sie das unten beschriebene segmentierte HTTP-Polling oder senden Sie Events überwachter Adressen mit Webhook-Push an einen HTTPS-Empfänger. GET /v1/push/chains listet unterstützte Chains und Bestätigungseinstellungen auf; authentifizieren Sie sich mit x-api-key. Webhook-Signaturen, Deduplizierung und Replay werden in jenem Leitfaden behandelt. Webhook-Push ist unabhängig von WebSocket-Abonnements (ws und subscriptions in /v1/chains).

Verbindung mit viem oder ethers herstellen

Entwickler und KI-Agenten können dieselben serverseitigen Einstellungen verwenden. Nutzen Sie Node.js 24 oder höher, viem 2 oder ethers 6 und beginnen Sie mit öffentlichen Leseoperationen. Setzen Sie BLOCKVECTRA_API_KEY sicher in der Umgebung für authentifizierte Methoden. Halten Sie Keys und RPC-URLs, die Keys enthalten, von Browser-Code, Logs und der Versionskontrolle fern.

Speichern Sie dies als network.mjs. Es liest chain_id und Methodenrichtlinien aus GET /v1/chains aus. Für schlüssellose Leseoperationen nutzen Sie die public.url des Katalogs und nur die in public.methods aufgeführten Methoden; öffentliche HTTP-Verfügbarkeit impliziert keinen WebSocket-Zugriff.

const chainSlug = process.env.BLOCKVECTRA_CHAIN ?? 'hyperevm_mainnet';
const key = process.env.BLOCKVECTRA_API_KEY;
const catalogUrl = 'https://api.blockvectra.com/v1/chains';
const response = await fetch(catalogUrl, { signal: AbortSignal.timeout(15_000) });
if (!response.ok) throw new Error(`Chains HTTP ${response.status}`);
const catalog = await response.json();
export const chainInfo = catalog.chains.find(item => item.chain === chainSlug);
if (!chainInfo || !Number.isSafeInteger(chainInfo.chain_id) || chainInfo.chain_id <= 0) {
  throw new Error('Missing chain or chain_id');
}
export function allows(method) {
  const matches = pattern => pattern.endsWith('*')
    ? method.startsWith(pattern.slice(0, -1)) : pattern === method;
  if (!key) return (chainInfo.public?.methods ?? []).some(matches);
  return (chainInfo.methods?.allow ?? []).some(matches)
    && !(chainInfo.methods?.deny ?? []).some(matches);
}
if (!allows('eth_chainId')) throw new Error('eth_chainId is unavailable');
export const rpcUrl = key
  ? new URL(`./${chainSlug}/${encodeURIComponent(key)}`, catalogUrl).href
  : chainInfo.public?.url;
if (!rpcUrl) throw new Error('Public RPC is unavailable; set BLOCKVECTRA_API_KEY');

Speichern Sie als viem-client.mjs, installieren Sie es mit npm install viem@2 und führen Sie dann node viem-client.mjs aus.

import { createPublicClient, defineChain, http } from 'viem';
import { chainInfo, rpcUrl } from './network.mjs';

export const chain = defineChain({
  id: chainInfo.chain_id,
  name: chainInfo.name,
  nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 },
  rpcUrls: { default: { http: [rpcUrl] } },
});
export const client = createPublicClient({ chain, transport: http(rpcUrl) });
if (await client.getChainId() !== chain.id) throw new Error('RPC chain ID mismatch');
console.error(await client.getBlockNumber());

Für ethers speichern Sie als ethers-client.mjs, installieren Sie es mit npm install ethers@6 und führen Sie dann node ethers-client.mjs aus.

import { JsonRpcProvider } from 'ethers';
import { chainInfo, rpcUrl } from './network.mjs';

const provider = new JsonRpcProvider(rpcUrl, chainInfo.chain_id, { batchMaxCount: 1 });
const network = await provider.getNetwork();
if (network.chainId !== BigInt(chainInfo.chain_id)) throw new Error('RPC chain ID mismatch');
console.log(await provider.getBlockNumber());
provider.destroy();

Deploy mit Foundry oder Hardhat

Der aktuelle Katalog für hyperevm_mainnet weist ws=false auf und listet eth_sendRawTransaction nicht in methods.allow. Verwenden Sie BlockVectra für Leseoperationen; das Deployment erfordert einen RPC, der Broadcasting unterstützt. Setzen Sie DEPLOY_RPC_URL auf die authentifizierte HTTP-URL dieses Providers. Gehen Sie nicht davon aus, dass er die Methoden- oder Log-Bereichslimits von BlockVectra teilt. Prüfen Sie die gewählte Chain-ID vor dem Signieren.

: "${DEPLOY_RPC_URL:?Set a broadcasting RPC URL}"
export RPC_URL="$DEPLOY_RPC_URL"
export CHAIN_ID="$(node --input-type=module -e "import { chainInfo } from './network.mjs'; console.log(chainInfo.chain_id)")"

Fahren Sie mit dem gemeinsamen Foundry- oder Hardhat-Deployment-Tutorial fort. Statten Sie den Deployer mit EVM-HYPE aus und prüfen Sie die unten aufgeführten Dual-Block-Anforderungen vor einem großen Deployment.

HYPE, Small Blocks und große Deployments

Der offizielle Netzwerk-Leitfaden von HyperEVM weist HYPE als Gas mit 18 Dezimalstellen aus (abgerufen: 2026-10-07). Stellen Sie sicher, dass der Deployer HYPE auf HyperEVM hält; ein HyperCore-Guthaben allein ist kein EVM-Gas-Guthaben. Befolgen Sie beim Übertragen von Mitteln die verlinkten Anweisungen für native Transfers.

Der Dual-Block-Leitfaden beschreibt schnelle Small Blocks und langsamere Big Blocks für größere Transaktionen (abgerufen: 2026-10-07). Schätzen Sie das Deployment-Gas zuerst ab. Für Deployments, die das Small-Block-Budget überschreiten, muss der Deployer ein bestehender HyperCore-Benutzer sein und die Core-Aktion {"type":"evmUserModify","usingBigBlocks":true} signieren; das alleinige Setzen eines höheren Transaktions-Gaslimits wählt keine Big Blocks aus. Setzen Sie anschließend usingBigBlocks=false zurück, um zu Small Blocks zurückzukehren.

Auf einem Provider, der dies unterstützt, nutzen Sie eth_usingBigBlocks, um den Adressmodus zu prüfen, und eth_bigBlockGasPrice für die Basisgebühr von Big Blocks. Die offizielle JSON-RPC-Referenz dokumentiert diese Methoden (abgerufen: 2026-10-07). Prüfen Sie die Methoden des gewählten Providers; verwenden Sie /v1/chains für BlockVectra. Das minimale Deployment oben zielt auf einen kleinen Contract ab und ändert den Core-Kontomodus nicht.

HyperCore- und HyperEVM-Daten

EVM-RPC liefert Contracts, Receipts und Logs. HyperCore-Handelsdaten und -Aktionen nutzen die Core-API. Contracts können den Core-State über Precompiles lesen und Aktionen über CoreWriter senden; nutzen Sie den offiziellen Interaktionsleitfaden bei der Integration dieser Pfade (abgerufen: 2026-10-07). EVM-Logs ersetzen keine Orderbuch- oder Positionsabfragen von HyperCore.

HyperEVM-Systemtransaktionen (wie etwa Transfers von HyperCore zu HyperEVM) sind in Standard-eth_getBlockByNumber-Antworten nicht enthalten und werden vom offiziellen RPC separat über eth_getSystemTxsByBlockNumber und eth_getSystemTxsByBlockHash bereitgestellt (siehe die offizielle JSON-RPC-Dokumentation, abgerufen: 2026-10-07). Die HyperEVM-Block-, Transaktions- und Data-API-Daten von BlockVectra enthalten derzeit keine Systemtransaktionen; verwenden Sie diese beiden offiziellen RPC-Methoden direkt, wenn Sie Daten zu Systemtransaktionen benötigen.

Offiziellen Fehler 10055 behandeln

Der offizielle HyperEVM-Leitfaden definiert 10055 als Core/EVM-Grenzfehler, einschließlich Nonce-, Unzureichende-Mittel-, Duplikat-Hash- und Zu-niedrige-Ersatzgebühr-Fehler (abgerufen: 2026-10-07). Prüfen Sie die Meldung des Broadcasting-RPCs, bevor Sie über die Behebung entscheiden:

• Nonce: Vergleichen Sie eth_getTransactionCount mit Ihren ausstehenden Transaktionen; serialisieren Sie Übermittlungen von einem Deployer und gleichen Sie dessen nächste Nonce ab.
• Mittel: Prüfen Sie das EVM-HYPE-Guthaben des Deployers gegen Betrag plus Gaskosten.
• Duplizierter Hash: Schlagen Sie die vorhandene Transaktion und das Receipt nach, bevor Sie eine weitere Transaktion einreichen.
• Ersatzgebühr: Überprüfen Sie die bestehende Nonce und Gebühr und wenden Sie dann die Ersetzungsrichtlinie des Broadcasters an; das Wiederholen derselben Bytes erhöht die Gebühr nicht.

10055 allein rechtfertigt keine blinden Wiederholungsversuche. Lesen Sie Fehler und deren Wiederherstellungshinweise separat in der BlockVectra-Fehlerreferenz.

Ratenlimits des offiziellen öffentlichen RPCs und 429

Hyperliquids offizielle Ratenlimit-Dokumentation gibt maximal 100 EVM-JSON-RPC-Anfragen pro Minute pro IP für rpc.hyperliquid.xyz/evm an. Ihre JSON-RPC-Dokumentation begrenzt eth_getLogs zudem auf 50 Blöcke pro Abfrage und bis zu 4 Topics. Abgerufen: 2026-10-07.

Pausieren Sie bei HTTP 429 Anfragen und beachten Sie zuerst Retry-After (Sekunden oder ein HTTP-Datum). Falls nicht vorhanden, nutzen Sie exponentiellen Backoff mit Jitter und einer begrenzten Anzahl von Versuchen, wobei Sie dasselbe unvollendete Segment wiederholen. Verringern Sie die Parallelität und Polling-Häufigkeit und unterteilen Sie Log-Abfragen in Segmente innerhalb des Limits des Endpunkts. Segmentierung allein hebt Ratenlimits nicht auf; Clients, die sich eine IP teilen, müssen ihre Anfragerate koordinieren.

Für den authentifizierten Endpunkt von BlockVectra lesen Sie max_logs_block_range, methods.allow und methods.deny für hyperevm_mainnet aus GET /v1/chains aus, anstatt die Blockspanne oder das Anfragen-pro-Minute-Limit des offiziellen öffentlichen RPCs anzuwenden. Die Anfragerate unterliegt separat cu_per_sec, burst_cu des Keys und dem Aufruflimit des kostenlosen Tarifs (siehe nächster Abschnitt). Prüfen Sie bei 429 error.data.reason und retryable; request_exceeds_burst erfordert kleinere Anfragen anstelle unveränderter Wiederholungen mit Backoff.

BlockVectra-Parameter und Serviceregeln

BlockVectra bedient HyperEVM Mainnet über JSON-RPC und REST-Data-API-Endpunkte:

1. Chain-Parameter und Log-Limits: Aus GET /v1/chains für hyperevm_mainnet:
   • Chain-Bezeichner (Slug): hyperevm_mainnet, Chain-ID 999.
   • max_logs_block_range: Geregelt durch das Feld max_logs_block_range aus GET /v1/chains. Eine einzelne eth_getLogs-Anfrage darf höchstens diese Anzahl von Blöcken umfassen (toBlock − fromBlock + 1). Ein Überschreiten dieser Spanne gibt HTTP 200 mit dem JSON-RPC-Fehlercode -32602 zurück (eth_getLogs block range too large: max <N> blocks), der nicht abgerechnet wird.
   • state_window_blocks: Geregelt durch das Feld state_window_blocks aus GET /v1/chains. State-Leseaufrufe (wie eth_call und eth_getBalance) unterliegen dem durch dieses Feld deklarierten Aufbewahrungsfenster (wenn null, bleibt der vollständige State ohne rollierendes Fensterlimit erhalten).
   • Methodenrichtlinie: Geregelt durch methods.allow und methods.deny. Standard-EVM-Methoden (eth_blockNumber, eth_getLogs, eth_call, eth_getBalance, eth_getBlockByNumber, eth_getTransactionReceipt usw.) sind zulässig; Filter- und Abonnementmethoden (eth_subscribe, eth_unsubscribe, eth_newFilter, eth_newBlockFilter) werden abgelehnt und geben -32601 zurück (nicht abgerechnet).
2. Ratenlimits im kostenlosen Tarif und Upgrades: Aus GET /v1/plans:
   • free.max_calls_per_sec: bis zu 25 Aufrufe pro Sekunde, geteilt über alle Schlüssel des Kontos, alle Chains und die Data API.
   • Standard-Key-Limits: Jeder API key verfügt über einen CU-Bucket (cu_per_sec-Wiederauffüllung, burst_cu-Kapazität — Standardwerte sind 400 CU/s und Burst 1,600 CU). Methoden werden nach Compute Unit (CU)-Gewichten abgerechnet.
   • Limits hochstufen: Nach einer Aufladung wird das kontoweite Limit für Aufrufe pro Sekunde aufgehoben; jeder Key unterliegt weiterhin den Raten- und Burst-Limits für Compute Units (CU). Aktuelle Tarife und Abrechnungseinheiten finden Sie auf der Preisseite.

Historische Logs nachholen: Segmentiertes eth_getLogs und Wiederholungslogik

Beim Abfragen historischer Logs müssen breite Intervalle in zusammenhängende Segmente unterteilt werden, die durch max_logs_block_range der Ziel-Chain begrenzt sind. Wiederholungsstrategien von Clients sollten das Feld retryable in Fehlerantworten prüfen.

Auswertung von retryable in Fehlerantworten

Auf BlockVectra enthalten JSON-RPC-Fehlerobjekte ein error.data-Payload mit reason, docs_url und retryable (boolean):

• retryable: true: Vorübergehende Zustände, einschließlich Dienstüberlastung (overloaded), Aufrufe-pro-Sekunde-Limit des kostenlosen Tarifs (free_plan_call_limit), Node-Synchronisation (node_syncing) oder nicht verfügbarer Upstream (upstream_unavailable). Clients sollten den Retry-After-Header beachten, sofern vorhanden, oder exponentiellen Backoff mit Jitter anwenden.
• retryable: false: Nicht-vorübergehende Fehler, wie etwa Überschreiten des Blockspannenlimits (-32602 / logs_range_too_large), ungültige Parameter (invalid_params), fehlender API key (missing_api_key) oder Überschreiten der Burst-Kapazität (-32022 / request_exceeds_burst). Wiederholungsversuche ohne Anpassung der Parameter sind nicht erfolgreich.

Unten sehen Sie die Antwort, die zurückgegeben wird, wenn ein API key weggelassen wird:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32024,
    "message": "missing API key: send it in the request path (/v1/{chain}/<api_key>) or in the x-api-key header",
    "data": {
      "reason": "missing_api_key",
      "docs_url": "https://docs.blockvectra.com/en/errors/#missing_api_key",
      "retryable": false
    }
  }
}

Data-API-Endpunkte anstelle von umfangreichem getLogs-Scanning nutzen

Wenn eine Anwendung den Transaktionsverlauf oder Token-Bewegungen für eine bestimmte Adresse verfolgt, erfordert das Scannen über eth_getLogs das Ausgeben sequenzieller, durch max_logs_block_range begrenzter segmentierter Abfragen sowie das Parsen von Roh-Transfer-Event-Logs.

Die BlockVectra Data API bietet vorindexierte REST-Endpunkte für hyperevm_mainnet, die Fenster von bis zu 100.000 Blöcken mit cursorbasierter Paginierung unterstützen:

1. Adresstransaktionen: GET /v1/data/hyperevm_mainnet/addresses/{address}/transactions
   • Parameter: from_block (erforderlich), to_block (erforderlich), direction (optional: from, to, any, Standard any), clamp (optionaler boolescher String, Standard false; bei true werden Fenster, die 100.000 Blöcke überschreiten oder höher als as_of_block sind, abgeschnitten, anstatt 409 zurückzugeben), limit (optional, max. 500), cursor (Paginierungs-Token).
2. Adress-Token-Transfers: GET /v1/data/hyperevm_mainnet/addresses/{address}/transfers
   • Parameter: standard (erforderlich: erc20 oder erc721; erc1155 kann nicht nach Adresse abgefragt werden und gibt 422 no_coverage zurück), token (optionaler Token-Contract-Filter), from_block (erforderlich), to_block (erforderlich), direction (optional: in, out, any), clamp (optional), limit, cursor.

Antwortstruktur

Antworten verwenden standardmäßige Envelope-Schemas:

• data: Array von Datensätzen. Transaktionen enthalten hash, block_number, block_timestamp, from, to, value, tx_index, gas_limit, gas_used und status. Transfers enthalten token, standard, from, to, block_number, block_timestamp, tx_hash, tx_index und log_index (amount für ERC-20, token_id für ERC-721).
• next_cursor: Opaque Paginierungs-Token, das zurückgegeben wird, wenn nachfolgende Datensätze existieren (fehlt auf der letzten Seite vollständig, nicht null).
• meta: Metadaten mit chain, chain_slug, chain_external_id, as_of_block, safe_block, finalized_block, coverage (full oder partial) und refreshed_at.

Codebeispiel: Data-API-Abfragen

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. Query address transaction history (clamp=true prevents 409 errors)
curl -s "https://api.blockvectra.com/v1/data/hyperevm_mainnet/addresses/0x2222222222222222222222222222222222222222/transactions?from_block=0&to_block=50000&clamp=true" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

# 2. Query address ERC-20 token transfers
curl -s "https://api.blockvectra.com/v1/data/hyperevm_mainnet/addresses/0x2222222222222222222222222222222222222222/transfers?standard=erc20&from_block=0&to_block=50000&clamp=true" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Echtzeit-Tracking: Polling neuer Blöcke

Bei einem HTTP-Transport verfolgen Sie Blöcke über Polling und rufen Event-Logs in aufeinanderfolgenden Segmenten innerhalb von max_logs_block_range ab. Wählen Sie WebSocket nur, wenn /v1/chains ws=true und den erforderlichen subscriptions-Eintrag meldet. Für die Zustellung an einen HTTPS-Empfänger nutzen Sie Webhook-Push.

Um den deployten Hello-Contract zu testen, setzen Sie LOG_ADDRESS auf dessen Adresse. Senden Sie ping() über den Broadcasting-RPC und holen Sie anschließend den Block des Receipts mit dem Backfill-Skript auf dieser Seite nach. Setzen Sie für neue Events ab dem zuletzt abgeschlossenen Segment fort.

cast send "$CONTRACT_ADDRESS" "ping()" --rpc-url "$DEPLOY_RPC_URL" \
  --private-key "$DEPLOYER_PRIVATE_KEY"

Polling-Ablauf

1. Führen Sie regelmäßige leichtgewichtige Aufrufe an eth_blockNumber aus, um den neuesten Chain-Head zu prüfen.
2. Vergleichen Sie die zurückgegebene Blocknummer mit dem zuvor verarbeiteten lastSeenBlock.
3. Wenn currentBlock > lastSeenBlock, teilen Sie [lastSeenBlock + 1, currentBlock] in Segmente von höchstens max_logs_block_range auf. Persistieren Sie lastSeenBlock erst nach erfolgreicher Verarbeitung jedes Segments; bei einem Fehler wiederholen Sie das unvollendete Segment. Deduplizieren Sie nach (blockHash, transactionHash, logIndex) und spielen Sie nach einer Wiederverbindung eine Überlappung erneut ab, um Reorganisationen abzugleichen.
4. viems watchBlockNumber oder watchBlocks implementiert HTTP-Polling unter einem HTTP-Transport nativ und ermöglicht Anpassungen über den Parameter pollingInterval (wie z. B. 1000 ms).

Event-Logs in begrenzten Segmenten pollen

Speichern Sie als poll-logs.mjs neben network.mjs und viem-client.mjs. Setzen Sie BLOCKVECTRA_API_KEY, LOG_ADDRESS und FROM_BLOCK, und führen Sie dann node poll-logs.mjs aus. Dieses endliche Beispiel fragt den Head 12-mal im Abstand von fünf Sekunden ab und ruft jeden neuen Bereich in sequenziellen Segmenten ab. Ein Fehler stoppt das Skript, bevor das fehlgeschlagene Segment weitergerückt wird.

import { isAddress } from 'viem';
import { client } from './viem-client.mjs';
import { chainInfo, allows } from './network.mjs';

const address = process.env.LOG_ADDRESS;
const start = process.env.FROM_BLOCK;
if (!address || !isAddress(address)) throw new Error('Set LOG_ADDRESS');
if (!/^(0x[0-9a-f]+|[0-9]+)$/i.test(start ?? '')) throw new Error('Set FROM_BLOCK');
if (!allows('eth_getLogs')) throw new Error('eth_getLogs requires an available keyed endpoint');
if (!Number.isSafeInteger(chainInfo.max_logs_block_range) || chainInfo.max_logs_block_range <= 0) {
  throw new Error('Invalid max_logs_block_range');
}
const max = BigInt(chainInfo.max_logs_block_range);
let from = BigInt(start);
for (let poll = 0; poll < 12; poll++) {
  const head = await client.getBlockNumber();
  while (from <= head) {
    const to = from + max - 1n < head ? from + max - 1n : head;
    const logs = await client.getLogs({ address, fromBlock: from, toBlock: to });
    console.log(JSON.stringify({ from: from.toString(), to: to.toString(), logs },
      (_, value) => typeof value === 'bigint' ? value.toString() : value));
    from = to + 1n;
  }
  if (poll < 11) await new Promise(resolve => setTimeout(resolve, 5_000));
}

Jede Ausgabe erfasst ein abgeschlossenes Segment. Um fortzufahren, setzen Sie FROM_BLOCK auf dessen to + 1; dauerhafte Consumer müssen Events und Cursor gemeinsam speichern, deduplizieren und Reorganisationen wie oben beschrieben abgleichen. Wenden Sie bei 429 oder anderen wiederholbaren Fehlern die Hinweise zum begrenzten Backoff auf dasselbe unvollendete Segment an.

Verwandte Leitfäden

• Öffentliche RPC-URL, unterstützte Methoden und aktuelle Limits finden Sie auf der HyperEVM-Chain-Seite.
• Vollständige Regeln zu eth_getLogs-Spannen und Segmentierungsalgorithmen finden Sie unter eth_getLogs-Blockbereichslimits und segmentierte Abfragen.
• Für den Vergleich von eth_getLogs mit Transfers der Data API, das Verständnis von as_of_block-Grenzen und safe_block- / finalized_block-Markierungen siehe eth_getLogs und indexierte Transfers: Abdeckung und Finalität.
• Einzelheiten zur CU-Messung, nicht abgerechneten Fehlern und Wiederholungen finden Sie unter Was nicht abgerechnet wird: Fehlercodes und Abrechnungsregeln.

Nächste Schritte

• Datensatzverzeichnis durchsuchen, um alle von BlockVectra indexierten Datensätze zu sehen.
• Kostenlosen Tarif und Preise ansehen, um zu prüfen, was Ihr Konto beinhaltet.
• In der Konsole anmelden, um einen API key zu erstellen.