JSON-RPC-Blockchain-Nodes: Leitfaden für PHP, Python & JS
So funktioniert JSON-RPC 2.0 mit Blockchain-Nodes: Anfrage- und Antwortformat, Fehlercodes und Batching, mit Beispielen in PHP, Python und JavaScript.
Geprüft von Maurice Sobiera
JSON-RPC ist ein Protokoll für Remote Procedure Calls, das Anfragen und Antworten als JSON kodiert. Ein Ethereum-Node stellt es über HTTP oder WebSocket bereit. Ein Client kann so Blöcke und Salden lesen oder signierte Transaktionen senden, indem er ein kleines JSON-Objekt schickt. Das Protokoll ist versioniert und spezifiziert. Deshalb funktioniert dieselbe Code-Form mit den meisten EVM-Nodes.
Dieser Artikel zeigt das Anfrage- und Antwortformat, die Fehlercodes, Batching und je ein funktionierendes Beispiel in PHP, Python und JavaScript.
Was ist JSON-RPC?
JSON-RPC 2.0 ist ein zustandsloses Protokoll, das in der JSON-RPC-2.0-Spezifikation definiert ist. Der Client sendet ein Anfrageobjekt. Der Server antwortet mit einem Antwortobjekt mit derselben id.
Eine Anfrage hat vier Bestandteile:
| Bestandteil | Bedeutung |
|---|---|
jsonrpc | Der String "2.0" |
method | Der Name der aufzurufenden Methode, zum Beispiel eth_blockNumber |
params | Ein Array oder Objekt mit den Argumenten. Kann entfallen, wenn die Methode keine nimmt |
id | Ein String, eine Zahl oder null. Die Antwort trägt denselben Wert |
Eine Antwort enthält entweder ein result- oder ein error-Feld, nie beides. Eine Anfrage ohne id ist eine Benachrichtigung (Notification). Der Server darf darauf nicht antworten.
Wie senden Sie eine JSON-RPC-Anfrage an einen Node?
Senden Sie eine HTTP-POST-Anfrage mit dem Header Content-Type: application/json und dem Anfrageobjekt als Body. Der HTTP-Endpunkt eines Nodes liegt bei Ethereum-Clients wie Geth meist auf Port 8545. WebSocket-Verbindungen funktionieren genauso, halten aber eine Verbindung dauerhaft offen.
Die Methodennamen und Parameter legt die Blockchain fest, nicht JSON-RPC. Für Ethereum listet sie die JSON-RPC-API-Referenz auf ethereum.org. eth_blockNumber nimmt keine Parameter und gibt die aktuelle Blocknummer als hexadezimal kodierte Größe zurück.
Anfrage:
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}Antwort:
{"jsonrpc": "2.0", "id": 1, "result": "0x4b7"}Mengenangaben sind Hex-Strings mit dem Präfix 0x und ohne führende Nullen. Das Ergebnis 0x4b7 ist Block 1207.
Beispielcode in PHP, Python und JavaScript
Alle drei Beispiele senden die Anfrage von oben an einen lokalen Node und geben die Antwort aus. Sie verwenden POST, weil JSON-RPC über HTTP kein GET nutzt.
PHP mit der curl-Erweiterung:
<?php$request = json_encode([ 'jsonrpc' => '2.0', 'method' => 'eth_blockNumber', 'params' => [], 'id' => 1,]);
$curl = curl_init('http://localhost:8545');curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
$response = json_decode(curl_exec($curl), true);curl_close($curl);
echo hexdec($response['result']); // block number as an integerPython mit der Bibliothek requests:
import requests
payload = {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}response = requests.post("http://localhost:8545", json=payload, timeout=10)body = response.json()
print(int(body["result"], 16)) # block number as an integerJavaScript mit fetch:
const response = await fetch('http://localhost:8545', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', method: 'eth_blockNumber', params: [], id: 1, }),});const body = await response.json();console.log(parseInt(body.result, 16)); // block number as an integerWie lesen Sie einen Saldo aus?
Rufen Sie eth_getBalance mit einer Adresse und einem Block-Parameter auf. Der Block-Parameter kann eine hexadezimale Blocknummer oder ein Tag wie "latest", "safe" oder "finalized" sein. Das Ergebnis ist der Saldo in Wei als Hex-Größe.
{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"], "id": 2}Bei Zahlungssystemen ist das Tag wichtig. "latest" kann noch reorganisiert werden, "finalized" nicht. Verwenden Sie "finalized", wenn Sie eine Einzahlung gutschreiben, und "latest" nur zur Anzeige.
Was bedeuten die Fehlercodes?
Schlägt ein Aufruf fehl, enthält die Antwort ein error-Objekt mit einem numerischen code und einer message. Die Spezifikation reserviert diese Codes:
| Code | Name | Typische Ursache |
|---|---|---|
| -32700 | Parse-Fehler | Der Body ist kein gültiges JSON |
| -32600 | Ungültige Anfrage | Das JSON ist kein gültiges Anfrageobjekt |
| -32601 | Methode nicht gefunden | Falscher Methodenname, oder der Node stellt diesen Namensraum nicht bereit |
| -32602 | Ungültige Parameter | Falsche Anzahl oder falscher Typ der Parameter |
| -32603 | Interner Fehler | Der Node ist bei der Verarbeitung des Aufrufs fehlgeschlagen |
Prüfen Sie immer auf error, bevor Sie result lesen. JSON-RPC transportiert Fehler im Antwort-Body. Prüfen Sie den Body deshalb unabhängig vom HTTP-Statuscode.
Können Sie mehrere Aufrufe in einer Anfrage senden?
Ja. Ein Batch ist ein JSON-Array aus Anfrageobjekten. Der Server antwortet mit einem Array aus Antworten. Die Antworten können in beliebiger Reihenfolge kommen. Ordnen Sie sie deshalb über die id zu.
[ {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}, {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2}]Batching spart Netzwerkumläufe. Node-Betreiber können die Batch-Größe begrenzen. Prüfen Sie deshalb das Limit des Endpunkts, den Sie nutzen.
Wann sollten Sie eine API statt eines Nodes nutzen?
Ein eigener Node gibt Ihnen direkten JSON-RPC-Zugriff, aber Sie müssen ihn pflegen. Für Wallet-Erstellung, Token-Transfers und Einzahlungsbenachrichtigungen bietet Chaingateway stattdessen eine REST-API. Ihre Endpunkte listet die OpenAPI-Datei. Was der Betrieb eines Nodes umfasst, zeigt So richten Sie einen Tron-Node ein.
Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.