Blockchain-API-Schnellstart und API-Keys
Die Chaingateway-API ist eine REST-API, die Wallets erstellt, Transaktionen sendet, Guthaben liest und Webhooks für mehrere Blockchains über HTTPS und JSON liefert. Für den Aufruf benötigen Sie ein Konto, einen API-Token und einen HTTP-Client. Diese Anleitung behandelt alle drei und endet mit einer ersten Anfrage, die eine Ethereum-Adresse erstellt.
Wie erstelle ich ein Konto und einen API-Key?
Abschnitt betitelt „Wie erstelle ich ein Konto und einen API-Key?“Registrieren Sie ein Konto, öffnen Sie die API-Key-Seite und erstellen Sie einen Token. Ein neues Konto startet mit einer 7-tägigen kostenlosen Testphase, zum Einstieg ist keine Karte nötig. Erstellen Sie Ihr Konto unter Chaingateway-Konto oder melden Sie sich an und öffnen Sie dann die API-Key-Seite.
Geben Sie dem Token einen Namen und klicken Sie auf „+ Create Token“. Der neue Token erscheint in der Liste. Bewahren Sie ihn an einem sicheren Ort auf und geben Sie ihn nicht weiter. Wer den Token besitzt, kann die API mit Ihrem Konto aufrufen. Halten Sie ihn deshalb aus der Versionsverwaltung heraus und laden Sie ihn aus einer Umgebungsvariablen oder einer .env-Datei.
Welchen HTTP-Client sollte ich verwenden?
Abschnitt betitelt „Welchen HTTP-Client sollte ich verwenden?“Jeder Client, der HTTPS-Anfragen senden kann, funktioniert. Die API-Referenz erzeugt Beispiele für viele weitere Sprachen als diese Seite. Die Beispiele hier verwenden diese Clients:
- curl für Shell-Skripte
- Requests für Python
- Axios für JavaScript und Node.js
- Guzzle für PHP oder den Laravel-HTTP-Client
Was bedeuten die REST-Methoden hier?
Abschnitt betitelt „Was bedeuten die REST-Methoden hier?“Die API folgt der HTTP-Methodensemantik aus RFC 9110. Ressourcen wie addresses, transactions und webhooks liegen unter /api/v2/{chain}/, und die Methode bestimmt, was mit der Ressource geschieht. Antworten sind JSON.
| Methode | Bedeutung | Beispiel in dieser API |
|---|---|---|
GET | Eine Ressource oder eine Liste lesen | GET /api/v2/ethereum/addresses listet Ihre Adressen auf |
POST | Eine Ressource erstellen oder eine Aktion auslösen | POST /api/v2/ethereum/addresses erstellt eine Adresse |
PUT | Die Felder einer bestehenden Ressource ersetzen | PUT /api/v2/ethereum/webhooks/{id} aktualisiert einen Webhook |
DELETE | Eine Ressource entfernen | DELETE /api/v2/ethereum/addresses/{address} löscht eine Adresse |
Eine Adresse lässt sich nicht bearbeiten, weil ihre Schlüssel sie definieren, daher gibt es für Adressen kein PUT und kein PATCH. Das Passwort eines gespeicherten Schlüssels ist die Ausnahme und ändert sich über POST /api/v2/{chain}/addresses/{address}.
Welche Header braucht jede Anfrage?
Abschnitt betitelt „Welche Header braucht jede Anfrage?“Senden Sie drei Header: Authorization, Accept und, wenn die Anfrage einen Body hat, Content-Type. Ein optionaler vierter Header, X-Network, wählt das Testnetz.
Authorization: Bearer YOUR_API_TOKENüberträgt Ihren Token als Bearer-Token, wie in RFC 6750 definiert. Eine Anfrage ohne gültigen Token erhält HTTP 401 und den Body{"message":"Unauthenticated."}.Accept: application/jsonfordert eine JSON-Antwort an.Content-Type: application/jsonteilt dem Server mit, dass der Request-Body JSON ist. Die API akzeptiert auch formularkodierte Bodys, die Beispiele verwenden aber JSON.X-Network: testnetführt die Anfrage im Testnetz aus. Lassen Sie den Header weg oder senden Siemainnet, um das Hauptnetz zu nutzen. Die Netzwerktabelle listet die Netzwerke hinter jedem Wert auf.
Wie sende ich meine erste Anfrage?
Abschnitt betitelt „Wie sende ich meine erste Anfrage?“Erstellen Sie eine Ethereum-Adresse mit einer POST-Anfrage. Der Body ist ein JSON-Objekt mit einem Feld, password. Es schützt den privaten Schlüssel, den Chaingateway für diese Adresse speichert, und Sie brauchen es erneut, sobald Sie von der Adresse eine Transaktion senden. Wallet-Verwaltung erklärt, was geschieht, wenn Sie es weglassen.
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "password": "choose-a-strong-password"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"payload = {"password": "choose-a-strong-password"}headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json", "Content-Type": "application/json",}response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json', 'Content-Type': 'application/json', }, data: { password: 'choose-a-strong-password' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'json' => ['password' => 'choose-a-strong-password'], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();Ein erfolgreicher Aufruf liefert Status 201. Die OpenAPI-Datei schreibt den Schlüssel des Adressfelds adderess, lesen Sie ihn daher unter diesem Namen:
{ "status": 201, "ok": true, "message": "Address created", "data": { "adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8" }}Zum Lesen von Daten verwenden Sie GET, das keinen Request-Body hat. Der nächste Aufruf listet die Adressen auf, die Sie erstellt und nicht gelöscht haben.
curl --request GET \ --url https://app.chaingateway.io/api/v2/ethereum/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Accept: application/json'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"headers = {"Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json"}response = requests.get(url, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'GET', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('GET', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();Wie führe ich denselben Aufruf in einem Testnet aus?
Abschnitt betitelt „Wie führe ich denselben Aufruf in einem Testnet aus?“Fügen Sie den Header X-Network: testnet hinzu und behalten Sie alles andere bei. Die Adresse wird dann auf Sepolia erstellt, und Test-Coins haben keinen Marktwert. Nutzen Sie das Testnet, bis Ihre Integration die Erfolgs- und Fehlerantworten korrekt verarbeitet. Später auf das Hauptnetz zu wechseln bedeutet, den Header zu entfernen oder auf mainnet zu setzen.
Wie sieht eine Fehlerantwort aus?
Abschnitt betitelt „Wie sieht eine Fehlerantwort aus?“Fehler verwenden denselben JSON-Umschlag wie erfolgreiche Aufrufe, mit ok auf false. Die OpenAPI-Datei dokumentiert die Statuscodes 200, 201, 400, 401, 404 und 422. Ein Validierungsfehler listet die abgelehnten Felder auf:
{ "status": 422, "ok": false, "message": "Data validation failed", "errors": { "password": ["The password field is required."] }}Blockchain-Fehler kommen auf dieselbe Weise an. Eine Transaktion ohne ausreichendes Guthaben für Gas liefert 422 mit der Meldung des Nodes, und ein falsches Wallet-Passwort liefert 401 mit Wrong password provided. Protokollieren Sie bei jedem fehlgeschlagenen Aufruf message und errors, denn sie nennen meist das Feld oder die Ursache.
Quellen
Abschnitt betitelt „Quellen“- RFC 9110, HTTP Semantics definiert die oben verwendeten Methoden und Statuscodes.
- RFC 6750, Bearer Token Usage definiert den Header
Authorization: Bearer. - RFC 8259, JSON definiert das Format von Request- und Response-Bodys.
- Die OpenAPI-Datei der API listet jeden Endpunkt, jeden Parameter und jede Beispielantwort auf.