Saltearse al contenido

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.

Wallet protegido con contraseña: se crea la dirección con una contraseña, Chaingateway almacena la clave cifrada y las transacciones posteriores se firman con la contraseña en lugar de la clave privada POST /api/v2/{chain}/addresses cuerpo: password La clave se almacena cifrada Chaingateway no guarda copia de su contraseña POST /api/v2/{chain}/transactions cuerpo: from, to, amount, password La transacción se firma y se difunde respuesta: txid
En este modo la clave privada nunca aparece en una solicitud ni en una respuesta.

¿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ñaNo seguro
Solicitud de creaciónel cuerpo contiene passwordsin password
Clave privada en la respuestanosí, una vez
Dónde está la clavecifrada en Chaingatewaysolo en su poder
Firmar una transacciónenviar passwordenviar privatekey
Contraseña o clave perdidano se puede restaurarno se puede restaurar
Uso recomendadodirecciones de larga duración y de depósitodirecciones 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.

Ventana de terminal
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"
}'

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.

Ventana de terminal
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ónSolicitudCuerpo
Cambiar la contraseñaPOST /api/v2/ethereum/addresses/{address}old_password, new_password (ambos obligatorios)
Exportar la clave privadaPOST /api/v2/ethereum/addresses/export/{address}password
Importar una clave existentePOST /api/v2/ethereum/addresses/importaddress, privatekey, password (todos obligatorios)
Listar sus direccionesGET /api/v2/ethereum/addressesninguno
Eliminar una direcciónDELETE /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.

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.

Ventana de terminal
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.