Gestión de wallets y almacenamiento de claves
Un wallet en Chaingateway es una dirección cuya clave privada se guarda cifrada tras una contraseña suya, o se le devuelve una vez y solo usted la conserva. Chaingateway no almacena la contraseña ni puede restaurar una clave perdida. Elija el modo al crear la dirección: con password es protegido, sin él es no seguro.
¿Qué diferencia hay entre los wallets protegidos con contraseña y los no seguros?
Sección titulada «¿Qué diferencia hay entre los wallets protegidos con contraseña y los no seguros?»En el modo protegido, Chaingateway cifra la clave privada con su contraseña y con su propia cadena de cifrado. En el modo no seguro, la clave se devuelve en la respuesta de creación y usted la envía con cada transacción. La tabla compara ambos.
| Protegido con contraseña | No seguro | |
|---|---|---|
| Solicitud de creación | el cuerpo contiene password | sin password |
| Clave privada en la respuesta | no | sí, una vez |
| Dónde está la clave | cifrada en Chaingateway | solo en su poder |
| Firmar una transacción | enviar password | enviar privatekey |
| Contraseña o clave perdida | no se puede restaurar | no se puede restaurar |
| Uso recomendado | direcciones de larga duración y de depósito | direcciones temporales y de un solo uso |
::: danger Guarde su contraseña de forma segura Nunca almacenamos contraseñas, así que si pierde la contraseña, no podemos restaurar la clave privada de su wallet. Guarde la contraseña en un gestor de secretos, no en el repositorio. :::
¿Cómo creo un wallet protegido con contraseña?
Sección titulada «¿Cómo creo un wallet protegido con contraseña?»Envíe una solicitud POST a /api/v2/{blockchain}/addresses con un password en el cuerpo JSON. Sustituya {blockchain} por ethereum, bsc, polygon, arbitrum o tron. El ejemplo crea una dirección de Ethereum.
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "password": "choose-a-strong-password"}'<?php$ch = curl_init();curl_setopt($ch, CURLOPT_URL, 'https://app.chaingateway.io/api/v2/ethereum/addresses');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["password" => "choose-a-strong-password"]));curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer YOUR_API_TOKEN', 'Content-Type: application/json']);$response = curl_exec($ch);curl_close($ch);echo $response;fetch('https://app.chaingateway.io/api/v2/ethereum/addresses', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ password: 'choose-a-strong-password' })}).then(response => response.json()).then(data => console.log(data));import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json'}data = {"password": "choose-a-strong-password"}response = requests.post('https://app.chaingateway.io/api/v2/ethereum/addresses', headers=headers, json=data)print(response.json())La respuesta incluye la nueva dirección. El archivo OpenAPI escribe la clave como adderess:
{ "status": 201, "ok": true, "message": "Address created", "data": { "adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8" }}Para enviar desde la dirección, pase la misma contraseña en la solicitud de transacción. La clave privada no forma parte de la solicitud. Una contraseña incorrecta devuelve el estado 401 con el mensaje Wrong password provided.
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/transactions \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "from": "0xSenderAddress", "to": "0xRecipientAddress", "amount": "0.1", "password": "choose-a-strong-password"}'¿Cómo cambio la contraseña, exporto la clave o importo una clave existente?
Sección titulada «¿Cómo cambio la contraseña, exporto la clave o importo una clave existente?»Cada una de estas acciones es un endpoint por blockchain. Las rutas siguientes usan ethereum, y las mismas rutas existen para bsc, polygon y arbitrum. Tron ofrece las mismas operaciones sobre direcciones, salvo listar las direcciones.
| Acción | Solicitud | Cuerpo |
|---|---|---|
| Cambiar la contraseña | POST /api/v2/ethereum/addresses/{address} | old_password, new_password (ambos obligatorios) |
| Exportar la clave privada | POST /api/v2/ethereum/addresses/export/{address} | password |
| Importar una clave existente | POST /api/v2/ethereum/addresses/import | address, privatekey, password (todos obligatorios) |
| Listar sus direcciones | GET /api/v2/ethereum/addresses | ninguno |
| Eliminar una dirección | DELETE /api/v2/ethereum/addresses/{address} | ninguno |
El cambio de contraseña es un POST, no un PUT ni un PATCH. Importar una clave convierte una dirección existente en una protegida con contraseña, que es la forma de usar el modo protegido con una dirección creada en otro sitio o en el modo no seguro. La respuesta de exportación devuelve la clave como data.private_key. Eliminar una dirección reduce el número de direcciones que cuentan para su plan.
¿Cuándo debo usar un wallet no seguro?
Sección titulada «¿Cuándo debo usar un wallet no seguro?»Use un wallet no seguro solo para direcciones temporales o de un solo uso. Si omite la contraseña, la respuesta de creación contiene la clave privada y debe conservarla usted. Quien obtenga la clave controla todos los fondos de la dirección, y una clave que se envía con cada transacción aparece en cada solicitud que haga. La solicitud siguiente crea una dirección de Tron sin contraseña.
curl --request POST \ --url https://app.chaingateway.io/api/v2/tron/addresses \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json'La respuesta contiene privateKey, publicKey, hexAddress y address. Guarde la clave antes de hacer nada más, porque la necesitará para cada transacción posterior. Para enviar desde una dirección así, pase privatekey en lugar de password en el cuerpo de la transacción. Las transferencias de TRX y TRC20 en Tron se describen en Crear transacciones y Crear transacciones de tokens.
::: danger Usar solo para wallets no permanentes Dado que la clave privada se incluye en la respuesta, es su responsabilidad almacenarla y protegerla. Si alguien obtiene acceso a su clave privada, puede controlar todos los fondos del wallet. :::
¿Cómo funcionan los wallets en Bitcoin y Solana?
Sección titulada «¿Cómo funcionan los wallets en Bitcoin y Solana?»Bitcoin y Solana no usan el endpoint addresses de la misma manera que las cadenas EVM y Tron.
En Bitcoin, un wallet es un contenedor de direcciones. POST /api/v2/bitcoin/wallets con un password crea el wallet y devuelve su identificador como data.bitcoinwallet. Después, POST /api/v2/bitcoin/wallets/{wallet}/addresses le añade direcciones, y POST /api/v2/bitcoin/wallets/{wallet}/addresses/{address}/export exporta la clave de una dirección con la contraseña del wallet. Una transacción de Bitcoin indica el wallet en walletname y envía la password del wallet. Cuando se alcanza el límite de direcciones del plan, la API responde con el estado 422 y el mensaje Your address limit exceeded. Please upgrade your plan.
En Solana, POST /api/v2/solana/addresses crea una dirección, y cada solicitud de transacción lleva la privatekey del remitente. El archivo OpenAPI no define un modo con contraseña para las transacciones de Solana, así que la gestión de la clave queda de su lado.
¿Cómo debo guardar las claves y las contraseñas?
Sección titulada «¿Cómo debo guardar las claves y las contraseñas?»Trate el token de API, las contraseñas de los wallets y las claves privadas como tres secretos distintos. No los guarde en el mismo sitio y no registre cuerpos de solicitud que los contengan. La Key Management Cheat Sheet de OWASP cubre el ciclo de vida de las claves, desde la generación hasta el almacenamiento y la retirada. Para el formato de la clave cifrada, Ethereum documenta la definición de Web3 Secret Storage, que describe cómo una contraseña cifra una clave. La guía de wallets de Bitcoin describe cómo almacenan y derivan claves los wallets.