Inicio rápido de la API y claves de API
La API de Chaingateway es una API REST que crea wallets, envía transacciones, lee saldos y entrega webhooks para varias blockchains mediante HTTPS y JSON. Para usarla necesita una cuenta, un token de API y un cliente HTTP. Esta guía cubre los tres y termina con una primera solicitud que crea una dirección de Ethereum.
¿Cómo creo una cuenta y una clave de API?
Sección titulada «¿Cómo creo una cuenta y una clave de API?»Registre una cuenta, abra la página de claves de API y cree un token. Una cuenta nueva empieza con una prueba gratuita de 7 días, y para comenzar no hace falta tarjeta. Cree su cuenta en cuenta de Chaingateway o inicie sesión, y después abra la página de claves de API.
Escriba un nombre para el token y pulse «+ Create Token». El nuevo token aparece en la lista. Guárdelo en un lugar seguro y no lo comparta. Quien tenga el token puede llamar a la API con su cuenta, así que manténgalo fuera del control de versiones y cárguelo desde una variable de entorno o un archivo .env.
¿Qué cliente HTTP debo usar?
Sección titulada «¿Qué cliente HTTP debo usar?»Sirve cualquier cliente que pueda enviar solicitudes HTTPS. La referencia de la API genera ejemplos para muchos más lenguajes que esta página. Los ejemplos de aquí usan estos clientes:
- curl para scripts de shell
- Requests para Python
- Axios para JavaScript y Node.js
- Guzzle para PHP, o el cliente HTTP de Laravel
¿Qué significan aquí los métodos REST?
Sección titulada «¿Qué significan aquí los métodos REST?»La API sigue la semántica de los métodos HTTP de la RFC 9110. Los recursos como addresses, transactions y webhooks cuelgan de /api/v2/{chain}/, y el método indica qué ocurre con el recurso. Las respuestas son JSON.
| Método | Significado | Ejemplo en esta API |
|---|---|---|
GET | Leer un recurso o una lista | GET /api/v2/ethereum/addresses lista sus direcciones |
POST | Crear un recurso o activar una acción | POST /api/v2/ethereum/addresses crea una dirección |
PUT | Reemplazar los campos de un recurso existente | PUT /api/v2/ethereum/webhooks/{id} actualiza un webhook |
DELETE | Eliminar un recurso | DELETE /api/v2/ethereum/addresses/{address} elimina una dirección |
Una dirección no se puede editar, porque la definen sus claves, así que no hay PUT ni PATCH para direcciones. La contraseña de una clave almacenada es la excepción y se cambia con POST /api/v2/{chain}/addresses/{address}.
¿Qué cabeceras necesita cada solicitud?
Sección titulada «¿Qué cabeceras necesita cada solicitud?»Envíe tres cabeceras: Authorization, Accept y, cuando la solicitud lleva cuerpo, Content-Type. Una cuarta cabecera opcional, X-Network, selecciona la red de pruebas.
Authorization: Bearer YOUR_API_TOKENenvía su token como token Bearer, según la RFC 6750. Una solicitud sin un token válido recibe HTTP 401 y el cuerpo{"message":"Unauthenticated."}.Accept: application/jsonpide una respuesta JSON.Content-Type: application/jsonindica al servidor que el cuerpo de la solicitud es JSON. La API también acepta cuerpos codificados como formulario, pero los ejemplos usan JSON.X-Network: testnetejecuta la solicitud en la red de pruebas. Omita la cabecera, o envíemainnet, para usar la red principal. La tabla de redes lista las redes que hay detrás de cada valor.
¿Cómo envío mi primera solicitud?
Sección titulada «¿Cómo envío mi primera solicitud?»Cree una dirección de Ethereum con una solicitud POST. El cuerpo es un objeto JSON con un solo campo, password. Protege la clave privada que Chaingateway guarda para esta dirección, y la necesita de nuevo cada vez que envíe una transacción desde ella. Gestión de wallets explica qué ocurre si la omite.
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 llamada correcta devuelve el estado 201. El archivo OpenAPI escribe la clave del campo de la dirección como adderess, así que léala con ese nombre:
{ "status": 201, "ok": true, "message": "Address created", "data": { "adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8" }}Para leer datos se usa GET, que no lleva cuerpo de solicitud. La llamada siguiente lista las direcciones que ha creado y no ha eliminado.
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();¿Cómo ejecuto la misma llamada en una testnet?
Sección titulada «¿Cómo ejecuto la misma llamada en una testnet?»Añada la cabecera X-Network: testnet y mantenga todo lo demás. La dirección se crea entonces en Sepolia, y las monedas de prueba no tienen valor de mercado. Use la testnet hasta que su integración gestione bien las respuestas correctas y las de error. Para pasar más adelante a la red principal, elimine la cabecera o establézcala en mainnet.
¿Cómo es una respuesta de error?
Sección titulada «¿Cómo es una respuesta de error?»Los errores usan el mismo envoltorio JSON que las llamadas correctas, con ok en false. El archivo OpenAPI documenta los códigos de estado 200, 201, 400, 401, 404 y 422. Un error de validación lista los campos rechazados:
{ "status": 422, "ok": false, "message": "Data validation failed", "errors": { "password": ["The password field is required."] }}Los errores de la blockchain llegan de la misma forma. Una transacción sin saldo suficiente para el gas devuelve 422 con el mensaje del nodo, y una contraseña de wallet incorrecta devuelve 401 con Wrong password provided. Registre message y errors en cada llamada fallida, porque suelen nombrar el campo o la causa.
Fuentes
Sección titulada «Fuentes»- RFC 9110, HTTP Semantics define los métodos y los códigos de estado usados arriba.
- RFC 6750, Bearer Token Usage define la cabecera
Authorization: Bearer. - RFC 8259, JSON define el formato de los cuerpos de solicitud y respuesta.
- El archivo OpenAPI de la API lista cada endpoint, parámetro y respuesta de ejemplo.