Guida rapida all'API blockchain e API key
L’API Chaingateway è un’API REST che crea wallet, invia transazioni, legge i saldi e consegna webhook per diverse blockchain tramite HTTPS e JSON. Per chiamarla servono un account, un token API e un client HTTP. Questa guida copre tutti e tre e termina con una prima richiesta che crea un indirizzo Ethereum.
Come creo un account e una API key?
Sezione intitolata “Come creo un account e una API key?”Registra un account, apri la pagina delle API key e crea un token. Un nuovo account parte con una prova gratuita di 7 giorni e per iniziare non serve una carta. Crea il tuo account su account Chaingateway oppure accedi, poi apri la pagina delle API key.
Digita un nome per il token e premi ”+ Create Token”. Il nuovo token compare nell’elenco. Conservalo in un luogo sicuro e non condividerlo. Chiunque possieda il token può chiamare l’API con il tuo account, quindi tienilo fuori dal controllo di versione e caricalo da una variabile d’ambiente o da un file .env.
Quale client HTTP devo usare?
Sezione intitolata “Quale client HTTP devo usare?”Va bene qualsiasi client in grado di inviare richieste HTTPS. L’API reference genera esempi per molti più linguaggi di questa pagina. Gli esempi qui usano questi client:
- curl per gli script shell
- Requests per Python
- Axios per JavaScript e Node.js
- Guzzle per PHP, oppure il client HTTP di Laravel
Cosa significano qui i metodi REST?
Sezione intitolata “Cosa significano qui i metodi REST?”L’API segue la semantica dei metodi HTTP di RFC 9110. Risorse come addresses, transactions e webhooks si trovano sotto /api/v2/{chain}/, e il metodo indica cosa succede alla risorsa. Le risposte sono in JSON.
| Metodo | Significato | Esempio in questa API |
|---|---|---|
GET | Legge una risorsa o un elenco | GET /api/v2/ethereum/addresses elenca i tuoi indirizzi |
POST | Crea una risorsa o avvia un’azione | POST /api/v2/ethereum/addresses crea un indirizzo |
PUT | Sostituisce i campi di una risorsa esistente | PUT /api/v2/ethereum/webhooks/{id} aggiorna un webhook |
DELETE | Rimuove una risorsa | DELETE /api/v2/ethereum/addresses/{address} elimina un indirizzo |
Un indirizzo non può essere modificato, perché sono le sue chiavi a definirlo, quindi per gli indirizzi non esistono né PUT né PATCH. La password di una chiave memorizzata fa eccezione e cambia tramite POST /api/v2/{chain}/addresses/{address}.
Quali header servono a ogni richiesta?
Sezione intitolata “Quali header servono a ogni richiesta?”Invia tre header: Authorization, Accept e, quando la richiesta ha un corpo, Content-Type. Un quarto header opzionale, X-Network, seleziona la rete di test.
Authorization: Bearer YOUR_API_TOKENtrasporta il tuo token come Bearer token, come definito in RFC 6750. Una richiesta senza token valido riceve HTTP 401 e il corpo{"message":"Unauthenticated."}.Accept: application/jsonchiede una risposta JSON.Content-Type: application/jsonindica al server che il corpo della richiesta è JSON. L’API accetta anche corpi form-encoded, ma gli esempi usano JSON.X-Network: testnetesegue la richiesta sulla rete di test. Omettilo, oppure inviamainnet, per usare la rete principale. La tabella delle reti elenca le reti dietro ciascun valore.
Come invio la mia prima richiesta?
Sezione intitolata “Come invio la mia prima richiesta?”Crea un indirizzo Ethereum con una richiesta POST. Il corpo è un oggetto JSON con un solo campo, password. Protegge la private key che Chaingateway memorizza per questo indirizzo e serve di nuovo ogni volta che invii una transazione da quell’indirizzo. Gestione wallet spiega cosa succede se lo ometti.
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();Una chiamata riuscita restituisce lo stato 201. Il file OpenAPI scrive la chiave del campo dell’indirizzo come adderess, quindi leggila con quel nome:
{ "status": 201, "ok": true, "message": "Address created", "data": { "adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8" }}Per leggere dati si usa GET, che non ha corpo della richiesta. La chiamata seguente elenca gli indirizzi che hai creato e non hai eliminato.
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();Come eseguo la stessa chiamata su una testnet?
Sezione intitolata “Come eseguo la stessa chiamata su una testnet?”Aggiungi l’header X-Network: testnet e lascia invariato il resto. L’indirizzo viene allora creato su Sepolia, e le coin di test non hanno valore di mercato. Usa la testnet finché la tua integrazione non gestisce correttamente le risposte di successo e di errore. Per passare più avanti alla rete principale basta rimuovere l’header o impostarlo su mainnet.
Come appare una risposta di errore?
Sezione intitolata “Come appare una risposta di errore?”Gli errori usano la stessa struttura JSON delle chiamate riuscite, con ok impostato su false. Il file OpenAPI documenta gli stati 200, 201, 400, 401, 404 e 422. Un errore di validazione elenca i campi rifiutati:
{ "status": 422, "ok": false, "message": "Data validation failed", "errors": { "password": ["The password field is required."] }}Gli errori della blockchain arrivano allo stesso modo. Una transazione senza saldo sufficiente per il gas restituisce 422 con il messaggio del nodo, e una password del wallet errata restituisce 401 con Wrong password provided. Registra message ed errors a ogni chiamata fallita, perché di solito indicano il campo o la causa.
- RFC 9110, HTTP Semantics definisce i metodi e i codici di stato usati sopra.
- RFC 6750, Bearer Token Usage definisce l’header
Authorization: Bearer. - RFC 8259, JSON definisce il formato dei corpi di richiesta e risposta.
- Il file OpenAPI dell’API elenca ogni endpoint, parametro e risposta di esempio.