Salta ai contenuti

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.

Flusso della richiesta: la tua app invia una richiesta HTTPS con un Bearer token e un header X-Network opzionale all'API Chaingateway, che interroga la blockchain e risponde con JSON La tua applicazione Client HTTP: curl, requests, axios, Guzzle Richiesta HTTPS aapp.chaingateway.io/api/v2/{chain}/... Authorization: Bearer token, X-Network:testnet opzionale API Chaingateway valida il token e il corpo, comunica con lablockchain Risposta JSON status, ok, message, data
Cosa succede a ogni chiamata all'API.

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.

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:

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.

MetodoSignificatoEsempio in questa API
GETLegge una risorsa o un elencoGET /api/v2/ethereum/addresses elenca i tuoi indirizzi
POSTCrea una risorsa o avvia un’azionePOST /api/v2/ethereum/addresses crea un indirizzo
PUTSostituisce i campi di una risorsa esistentePUT /api/v2/ethereum/webhooks/{id} aggiorna un webhook
DELETERimuove una risorsaDELETE /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}.

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_TOKEN trasporta 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/json chiede una risposta JSON.
  • Content-Type: application/json indica al server che il corpo della richiesta è JSON. L’API accetta anche corpi form-encoded, ma gli esempi usano JSON.
  • X-Network: testnet esegue la richiesta sulla rete di test. Omettilo, oppure invia mainnet, per usare la rete principale. La tabella delle reti elenca le reti dietro ciascun valore.

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.

Terminal window
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"
}'

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.

Terminal window
curl --request GET \
--url https://app.chaingateway.io/api/v2/ethereum/addresses \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Accept: application/json'

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.

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.