Firma mensajes, datos tipados y transacciones en crudo con las claves de tu billetera
En resumen
La API de Firma de Blockradar te permite firmar criptográficamente mensajes de texto plano, datos estructurados (datos tipados) y transacciones en crudo usando las claves privadas de tu billetera. Firma mensajes para demostrar la propiedad de la billetera. Firma transacciones construidas externamente (por ejemplo, swaps de Jupiter en Solana) sin exponer claves privadas, y opcionalmente transmítelas en cadena.
Antes de usar la API de Firma, asegúrate de tener:
1
Clave API
Obtén tu clave API desde el Panel de Blockradar. Navega a Developers para generar una.
2
Billetera Creada
Crea una billetera principal desde el Panel de Blockradar. Navega a Wallets y crea una para tu blockchain objetivo. Necesitarás el walletId para las operaciones de firma.
3
Entorno
Elige entre Testnet (para desarrollo) o Mainnet (para producción). Las billeteras están aisladas por entorno.
La API de Firma produce una firma criptográfica que demuestra que controlas una dirección de billetera específica. La salida firmada puede ser verificada por cualquier tercero sin acceder a tus claves privadas.
Firma de Mensajes
Firma mensajes de texto plano para demostrar la propiedad de la billetera. Funciona en todas las blockchains compatibles: EVM, Tron y Solana.
Firma de Datos Tipados
Firma datos estructurados siguiendo el estándar EIP-712. Se usa para aprobaciones sin gas (EIP-2612 Permit) y transferencias autorizadas (EIP-3009). Solo EVM.
Firma de Transacciones
Firma transacciones en crudo construidas externamente. Construye un swap en Jupiter, una llamada a contrato con ethers.js, o una transferencia con TronWeb, luego envía la transacción sin firmar y obtén la firma sin exponer claves privadas.
Broadcast de Transacciones
Firma y transmite una transacción en crudo en un solo paso. Blockradar firma la transacción y la envía en cadena mediante una cola confiable con reintentos automáticos.
Firma un mensaje de texto plano con la clave privada de tu billetera. La API firma el mensaje, verifica que la firma coincida con la dirección de la billetera y devuelve tanto la firma como un registro de transacción.
Firma datos estructurados siguiendo el estándar EIP-712. Esto se usa para aprobaciones sin gas, transferencias delegadas y otros flujos de autorización en cadena que requieren una firma estructurada.
La firma de datos tipados solo está disponible para blockchains compatibles con EVM (Ethereum, Polygon, BSC, Base, Arbitrum, Optimism, Celo). Tron y Solana no soportan EIP-712.
El nombre del dominio de firma (ej., el nombre del token o de la dApp)
version
string
Sí
La versión del dominio
chainId
number
Sí
El ID de cadena. Debe coincidir con la red blockchain de la billetera.
verifyingContract
string
Sí
La dirección del contrato que verificará la firma
salt
string
No
Salt de dominio opcional para EIP-712 v4
Validación de Chain ID
El chainId en tu objeto domain debe coincidir con el ID de cadena de la red blockchain de la billetera. Si no coinciden, la API devuelve un error 400 Chain ID mismatch.
Firma mensajes, datos tipados, transacciones o realiza broadcast usando una dirección hija específica en lugar de la billetera principal. Las cuatro operaciones de firma están disponibles para direcciones hijas:
curl --request POST \ --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/signing/message \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data '{ "message": "Verify ownership of deposit address for provider onboarding.", "reference": "address-verify-001" }'
La firma con dirección hija sigue el mismo formato de solicitud y respuesta que la firma con billetera principal. La única diferencia es la URL del endpoint, que incluye el addressId.
Las operaciones de firma activan un webhook con el registro de transacción:
Evento
Descripción
signed.success
Firma completada exitosamente. Para firma de mensajes/datos tipados/transacciones, se dispara inmediatamente. Para broadcast, se dispara después de la confirmación en cadena.
signed.failed
El broadcast de la transacción falló después de agotar todos los reintentos. Solo aplica al endpoint /broadcast.
Después de que la cola de broadcast confirma la transacción en cadena, recibes este webhook. El campo hash se actualiza al hash de transacción en cadena y confirmed cambia a true.
Si el broadcast falla permanentemente después de todos los intentos de reintento, recibes este webhook. El status es FAILED y confirmed permanece en false.
Firma una transacción en crudo sin firmar, construida externamente. Tú construyes la transacción usando cualquier SDK (ethers.js, TronWeb, Solana web3.js, Jupiter API), luego envías la transacción serializada sin firmar a Blockradar. Blockradar la firma con la clave privada de la billetera y devuelve la transacción firmada sin exponer jamás la clave a tu aplicación.
Para la firma de transacciones, signedTransaction es un string, no un objeto. Esto es diferente de la firma de mensajes donde devuelve un objeto con componentes de firma como r, s, v.
Firma y transmite una transacción en crudo en un solo paso. Blockradar firma la transacción, luego la envía en cadena mediante una cola confiable con reintentos automáticos. La API responde inmediatamente con estado PENDING. Recibirás un webhook signed.success o signed.failed cuando el resultado en cadena sea confirmado.
El broadcast requiere fondos de testnet/mainnet en la billetera para pagar las comisiones de gas. La transacción debe ser válida y no estar expirada (los blockhashes de Solana expiran en ~90 segundos).
Transacción firmada, broadcast en cola. Recibes esto en la respuesta HTTP.
SUCCESS
Transacción confirmada en cadena. Se envía el webhook signed.success.
FAILED
El broadcast falló después de agotar todos los reintentos. Se envía el webhook signed.failed.
La cola de broadcast reintenta hasta 10 veces con intervalos de 5 minutos. Para Solana, si el blockhash expira, los reintentos no ayudarán. Necesitarás reconstruir la transacción con un blockhash fresco.
Aquí tienes una implementación completa para firmar un mensaje y enviar la firma a un proveedor de terceros:
async function signAndVerifyWithProvider(walletId, providerMessage) { const apiKey = process.env.BLOCKRADAR_API_KEY; const baseUrl = 'https://api.blockradar.co/v1'; // Paso 1: Firmar el mensaje const signResponse = await fetch( `${baseUrl}/wallets/${walletId}/signing/message`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ message: providerMessage, reference: `provider-verify-${Date.now()}` }) } ).then(r => r.json()); if (signResponse.statusCode !== 200) { throw new Error(`Signing failed: ${signResponse.message}`); } const { hash, senderAddress } = signResponse.data; // Paso 2: Enviar la firma al proveedor de terceros // El proveedor puede verificar que la firma coincide con la dirección de la billetera // sin acceder a tus claves privadas return { address: senderAddress, signature: hash, message: providerMessage };}// UsosignAndVerifyWithProvider( 'wallet-uuid', 'I authorize Iron to manage assets on my behalf.');
Coincide los chain IDs: El chainId en tu domain debe coincidir con la red de la billetera. Usa chain IDs de sandbox (testnet) para pruebas y chain IDs de producción (mainnet) para operaciones en vivo
Verifica el contrato: El verifyingContract debe ser el contrato que verificará la firma en cadena
Construye la transacción con el remitente correcto: La transacción sin firmar debe usar la clave pública de la billetera o dirección hija como el pagador de comisiones (Solana) o remitente (EVM/Tron). Si la clave no coincide, la firma fallará.
Los blockhashes de Solana expiran rápido: Los blockhashes de Solana son válidos por aproximadamente 60 a 90 segundos. Construye la transacción y llama al endpoint de firma rápidamente. Si usas broadcast, los reintentos de la cola no ayudarán una vez que el blockhash expire.
Gestión de nonce en EVM: Configura el nonce correctamente. Si el nonce ya fue usado, el broadcast fallará. Consulta el nonce desde la cadena inmediatamente antes de construir la transacción.
Expiración en Tron: Las transacciones de Tron tienen una ventana de expiración de 24 horas configurada durante la construcción. Esto da tiempo suficiente para la firma y el broadcast.
Solo firma vs broadcast: Usa /signing/transaction cuando quieras transmitir la transacción tú mismo o a través de otro servicio. Usa /signing/broadcast cuando quieras que Blockradar maneje el envío con reintentos automáticos.
