“Hola, mundo” en Moralis

El 'Hola, mundo' de Moralis: inicializar el SDK con tu API Key y autenticar un usuario usando su billetera Web3 (ej: MetaMask) a través de la funcionalidad de Sign-in with Wallet.

📋 Copiar

// Instala el SDK: npm install moralis @moralisweb3/core @moralisweb3/common-evm-utils

import Moralis from '@moralisweb3/core';
import { EvmBlockchain } from '@moralisweb3/common-evm-utils';

const moralis = Moralis.create({
  apiKey: 'TU_API_KEY', // Reemplaza con tu clave API
});

async function login() {
  try {
    await moralis.start(); // Iniciar SDK
    
    // Usar la funcionalidad de autenticación (requiere un provider inyectado como Metamask)
    const { authenticate } = await import('@moralisweb3/auth');
    const result = await authenticate({
       moralis, // Pasa la instancia de Moralis Core
       chain: EvmBlockchain.ETHEREUM, // O la cadena con la que el usuario se conectará
       signingMessage: "Bienvenido a mi dApp Web3!", // Mensaje para firmar
    });

    console.log('Usuario autenticado exitosamente:', result.address);
    console.log('ID de sesión:', result.sessionId);

  } catch (error) {
    console.error('Error durante la autenticación:', error);
  }
}

login();

Resultado:

Output

Solicita al usuario firmar un mensaje con su billetera Metamask. Si tiene éxito, la consola mostrará la dirección autenticada y el ID de sesión.

Comandos básicos

Familiarizarse con estos comandos es esencial para interactuar eficientemente con Moralis:

Registrarse y Obtener API Key de Moralis

📋 Copiar

Ir a https://moralis.io/, registrarse, iniciar sesión en el dashboard, crear un nuevo proyecto y encontrar la 'API Key' en la sección de configuración o detalles del proyecto.

El primer paso para usar los servicios de Moralis. Necesitas una API Key válida para autenticar tus solicitudes.

Instalar Moralis SDK (Core, EVM, Auth, etc.)
📋 Copiar
```
npm install moralis @moralisweb3/core @moralisweb3/common-evm-utils @moralisweb3/auth
```
Instala los paquetes necesarios del SDK de Moralis en tu proyecto Node.js o frontend (React, Vue, etc.). El paquete `@moralisweb3/core` es el núcleo.
Inicializar Moralis SDK en tu Aplicación
📋 Copiar
```
import Moralis from '@moralisweb3/core';
const moralis = Moralis.create({ apiKey: 'TU_API_KEY' });
await moralis.start();
```
Inicializa el Moralis SDK, conectándolo a los servicios de Moralis usando tu API Key, antes de poder usar sus funcionalidades.
Autenticar usuario con Billetera (Sign-in with Wallet)
📋 Copiar
```
import { authenticate } from '@moralisweb3/auth';

const result = await authenticate({ moralis }); // Requiere moralis.start() previo y un provider inyectado (Metamask)
```
Inicia el flujo de autenticación Web3, solicitando al usuario firmar un mensaje con su billetera. Devuelve la dirección del usuario y otros datos de sesión si tiene éxito.

Obtener balances de tokens (nativos y ERC-20/BEP-20) para una dirección (EVM API)

📋 Copiar

import { EvmBlockchain } from '@moralisweb3/common-evm-utils';

const address = '0x...'; // Dirección del usuario
const chain = EvmBlockchain.ETHEREUM; // o POLYGON, BSC, SEPOLIA, etc.

const balances = await moralis.EvmApi.token.getWalletTokenBalances({ address, chain });
console.log('Balances:', balances.toJSON());

Consulta los balances de tokens fungibles (incluyendo la moneda nativa como ETH o MATIC) para una dirección específica en una cadena compatible con EVM.

Obtener NFTs de un usuario (EVM API)

📋 Copiar

import { EvmBlockchain } from '@moralisweb3/common-evm-utils';

const address = '0x...'; // Dirección del usuario
const chain = EvmBlockchain.POLYGON; // o ETHEREUM, BSC, etc.

const nfts = await moralis.EvmApi.nft.getWalletNFTs({ address, chain });
console.log('NFTs:', nfts.toJSON());

Consulta la lista de NFTs (ERC-721, ERC-1155) que posee una dirección específica en una cadena compatible con EVM, incluyendo metadatos.

Obtener transacciones para una dirección (EVM API)

📋 Copiar

import { EvmBlockchain } from '@moralisweb3/common-evm-utils';

const address = '0x...'; // Dirección del usuario
const chain = EvmBlockchain.ETHEREUM;

const transactions = await moralis.EvmApi.transaction.getWalletTransactions({ address, chain });
console.log('Transacciones:', transactions.toJSON());

Consulta el historial de transacciones (enviadas y recibidas) para una dirección específica en una cadena compatible con EVM.

Obtener datos de contratos (EVM API runContractFunction)

📋 Copiar

import { EvmBlockchain } from '@moralisweb3/common-evm-utils';

const address = '0x...'; // Dirección del contrato
const chain = EvmBlockchain.ETHEREUM;
const functionName = 'someViewFunction'; // Nombre de la función view/pure
const abi = [...] // Array con el ABI del contrato o la función específica
const params = { param1: 'value1' }; // Argumentos de la función

const response = await moralis.EvmApi.utils.runContractFunction({
  address,
  chain,
  functionName,
  abi,
  params,
});

console.log('Resultado:', response.toJSON());

Llama funciones `view` o `pure` de un contrato desplegado en una cadena compatible con EVM, obteniendo el resultado sin enviar una transacción real.

Configurar un Stream (en el Dashboard)
📋 Copiar
```
Accede a tu dashboard de Moralis (moralis.io/dashboard) -> 'Streams'. Haz clic en 'Create new Stream'. Define la cadena, dirección del contrato, los eventos a escuchar, y la URL del webhook de tu backend donde Moralis enviará los datos.
```
Proceso en la interfaz web de Moralis para configurar notificaciones en tiempo real (vía webhooks HTTP POST) a tu backend cuando ocurren eventos o transacciones específicas en la blockchain.

Subir un archivo a IPFS vía Moralis API

📋 Copiar

import { EvmChain } from '@moralisweb3/common-evm-utils'; // O usar Moralis Core

const uploadResponse = await moralis.EvmApi.ipfs.uploadFolder({ // O moralis.Core.getApi().ipfs.uploadFolder
  items: [{
    path: "mi-imagen.png",
    content: 'BASE64_DEL_CONTENIDO', // Contenido del archivo en formato base64
  }],
});

console.log('Archivo subido a IPFS con CID:', uploadResponse.toJSON()[0].path);

Utiliza la API de IPFS de Moralis para subir archivos (ej: imágenes, metadatos JSON), donde Moralis se encarga de agregarlos y pinearlos en la red IPFS. Devuelve el CID del contenido.

Conceptos Clave

Comprender estos conceptos fundamentales te ayudará a dominar Moralis de forma más organizada y eficiente:

Backend-as-a-Service (BaaS) para Web3:

La propuesta de valor central de Moralis. En lugar de que los desarrolladores construyan y mantengan una infraestructura backend compleja para interactuar con blockchains (ejecutar nodos, indexar datos, implementar autenticación), Moralis proporciona estas funcionalidades como servicios preconstruidos a los que accedes a través de APIs y SDKs. Permite enfocarse en la lógica de negocio de la dApp.
Autenticación Web3 (Auth API / Sign-in with Wallet):

Una característica fundamental que simplifica enormemente la autenticación de usuarios en dApps. Permite a los usuarios iniciar sesión de forma segura utilizando su billetera Web3 (ej: Metamask) firmando un mensaje. Moralis maneja todo el proceso criptográfico y de gestión de sesiones, proporcionando una experiencia de inicio de sesión familiar para los usuarios de Web3.
Acceso a Datos On-Chain (Data API - EVM, Solana, Aptos, etc.):

Moralis indexa y normaliza datos de múltiples blockchains. Su Data API (organizada por cadena, ej: EVM API, Solana API, Aptos API) proporciona endpoints unificados para consultar información compleja fácilmente: balances de tokens, NFTs (propiedad, metadatos), historial de transacciones, eventos de contratos, precios, etc. Elimina la necesidad de hacer consultas de bajo nivel a nodos RPC o indexar la blockchain manualmente.
Sincronización en Tiempo Real y Eventos (Streams API / Events API):

Permite monitorizar contratos o direcciones en la blockchain y recibir actualizaciones en tiempo real cuando ocurren eventos o cambios de estado relevantes. Moralis utiliza webhooks: cuando algo sucede en la cadena, Moralis envía una petición HTTP POST a una URL de tu backend, notificándote con los datos del evento/transacción. Es clave para mantener bases de datos sincronizadas o activar lógica backend asíncrona.
Integración con IPFS (IPFS API):

Moralis ofrece una API para interactuar con IPFS. Puedes subir archivos a la infraestructura IPFS de Moralis (ellos se encargan de agregarlos y pinearlos de forma fiable) y acceder a ellos vía CID. Útil para almacenar metadatos de NFTs, activos de juegos u otro contenido descentralizado relacionado con tu dApp.
SDKs y APIs Específicas por Cadena:

Moralis proporciona un SDK principal (Core SDK) y SDKs/APIs específicas para las diferentes blockchains que soporta (Moralis EVM API para Ethereum y cadenas compatibles como Polygon, BSC; Moralis Solana API; Moralis Aptos API, etc.). Elige el SDK o API correcto según la cadena con la que necesites interactuar.
API Keys (Gestión y Seguridad):

Necesitas una API Key de Moralis para autenticar tus solicitudes a sus servicios y para que se registre tu consumo. Es vital proteger tu API Key, especialmente en backends, y seguir las mejores prácticas de seguridad: usar variables de entorno, evitar exponerla en código frontend público, y considerar el uso de IP Whitelisting o Referer Whitelisting si Moralis los ofrece.
Límites de Uso y Planes:

Moralis opera con diferentes planes (incluyendo un plan gratuito). Cada plan tiene límites en el número de solicitudes API por segundo/mes, ancho de banda, número de streams activos, etc. Monitorizar tu uso en el dashboard de Moralis es importante para escalar tu aplicación y evitar interrupciones del servicio.
Simplificación del Desarrollo Backend de dApps:

El principal beneficio de Moralis es que reduce drásticamente el tiempo y el esfuerzo necesarios para construir el backend de una dApp. Te proporciona acceso a datos on-chain, autenticación y sincronización en tiempo real a través de APIs sencillas, permitiéndote enfocar tus recursos de desarrollo en la lógica de negocio de tu dApp y en la experiencia del usuario.
Webhooks vs Polling vs RPC Directo:

Comprender por qué los Streams (usando webhooks) son a menudo más eficientes para recibir datos en tiempo real que hacer 'polling' (consultas repetidas) a un nodo RPC. Moralis maneja el polling a la blockchain y te notifica solo cuando hay algo nuevo, reduciendo la carga en tus sistemas y en la red blockchain.

Casos de uso

Algunos ejemplos de aplicaciones prácticas donde se utiliza Moralis:

Implementar autenticación de usuarios con billetera Web3 (Sign-in with Wallet) en cualquier dApp frontend:

Integrar el Moralis SDK (ej: con frameworks como React, Vue, Angular) para proporcionar un flujo de inicio de sesión seguro y familiar para los usuarios de Web3, permitiéndoles autenticarse simplemente firmando un mensaje con su billetera.
Construir dashboards de usuario que muestren balances de tokens y NFTs a través de múltiples cadenas soportadas:

Utilizar la Data API de Moralis (EVM API, Solana API, etc.) para obtener rápidamente la lista completa de activos (monedas nativas, tokens fungibles, NFTs) que posee una dirección de usuario en diferentes blockchains y mostrarlos en una interfaz unificada.
Crear un servicio backend que reacciona en tiempo real a eventos específicos de contratos inteligentes (ej: mints, transferencias, swaps):

Configurar Streams en el dashboard de Moralis para que envíen webhooks (peticiones POST) a una URL de tu backend cada vez que se emite un evento específico de un contrato en la blockchain, permitiéndote actualizar bases de datos, enviar notificaciones, o activar lógica de negocio en tiempo real.
Desarrollar un marketplace de NFTs que muestre metadatos, precios e información de propiedad:

Utilizar la Data API de Moralis para obtener información sobre colecciones de NFTs, la propiedad de tokens (quién tiene qué NFT), los metadatos asociados (incluyendo si están en IPFS o URL tradicional) y, si está disponible, información sobre listados o precios de mercado.
Sincronizar datos de contratos a una base de datos tradicional para permitir consultas rápidas y complejas:

Utilizar los Streams de Moralis para recibir eventos y actualizaciones de estado de contratos en tiempo real, y almacenar esos datos en tu propia base de datos relacional o NoSQL. Esto permite realizar consultas complejas y agregaciones sobre datos on-chain de forma mucho más rápida y eficiente que consultando directamente a un nodo.
Implementar funcionalidades de seguimiento de transacciones, historiales de actividad o auditorías para usuarios o contratos:

Utilizar la Data API (EVM API) para obtener el historial completo de transacciones entrantes y salientes para una dirección específica, o el historial de interacciones con un contrato dado, facilitando la creación de secciones de 'Actividad' en tu dApp.
Simplificar el desarrollo backend de una dApp al no tener que gestionar nodos blockchain ni infraestructura de datos:

Aprovechar Moralis para abstraer la complejidad de la infraestructura blockchain. Esto libera a tu equipo de desarrollo para que se centre en construir la lógica de negocio única de tu dApp y mejorar la experiencia del usuario, en lugar de dedicar tiempo y recursos a la operación de nodos, indexación, etc.
Automatizar tareas backend basadas en la actividad on-chain (ej: procesar pagos de suscripciones, distribuir recompensas):

Utilizar Streams para ser notificado en tiempo real cuando se reciben pagos on-chain o cuando los usuarios completan acciones en contratos que emiten eventos, y luego activar lógica en tu backend para procesar esas acciones (ej: actualizar el estado de una suscripción en tu base de datos, acreditar recompensas off-chain).
Subir y gestionar archivos relacionados con dApps o NFTs (metadatos, imágenes) en IPFS a través de la API de Moralis:

Utilizar la funcionalidad IPFS de Moralis para subir archivos de forma sencilla y asegurar que están agregados y pineados de forma fiable en la red IPFS. Esto es crucial para la permanencia de los metadatos de NFTs o el contenido de dApps descentralizadas.

Consejos para Principiantes

Aquí tienes algunas recomendaciones para facilitar tus inicios en Moralis:

Consigue Tu API Key de Moralis y Protégela Rigurosamente:

Este es el primer paso. Regístrate en moralis.io y crea un proyecto para obtener tu API Key. Trátala como una contraseña sensible. Nunca la incluyas directamente en el código frontend público. Úsala de forma segura, preferiblemente desde un backend o configurando IP/Referer Whitelisting en el dashboard.
Familiarízate con las Tres Funcionalidades Principales: Auth, Data y Streams:

Estas son las herramientas clave que Moralis te ofrece para simplificar Web3. Auth (Autenticación con billetera). Data (Acceso a datos on-chain indexados: balances, NFTs, transacciones). Streams (Sincronización en tiempo real vía webhooks). Entiende qué problema resuelve cada una y cuándo usarla.
Empieza con un Tutorial Simple de la Documentación Oficial:

La documentación de Moralis es muy completa y tiene guías de inicio rápido. Empieza con un tutorial básico (ej: 'Sign-in with Wallet' o 'Get NFT Balances') para ver cómo usar el SDK y las APIs en la práctica con pocas líneas de código.
Usa el Moralis SDK en Tu Proyecto (Frontend o Backend):

Instala los paquetes del SDK (`npm install moralis @moralisweb3/...`) e inicializa el SDK con tu API Key (`moralis.create(...)`, `moralis.start()`). Luego, podrás llamar a las funciones del SDK para acceder a las funcionalidades de Moralis desde tu código JavaScript/TypeScript.
Explora Tu Dashboard de Moralis Constantemente:

El dashboard es donde gestionas tus proyectos, API Keys, configuras Streams y, crucialmente, monitorizas tu uso. Revisa la sección de 'USAGE' para ver cuántas llamadas API estás haciendo, cuánto ancho de banda consumes, y si te acercas a los límites de tu plan (especialmente en el plan gratuito).
Entiende las Cadenas Soportadas y Sus APIs Específicas:

Moralis soporta múltiples blockchains. Consulta la documentación para ver la lista de cadenas disponibles y qué APIs (EVM API, Solana API, etc.) necesitas usar para acceder a los datos de cada cadena.
Considera Usar Streams (Webhooks) para Reacciones en Tiempo Real:

Si necesitas que tu backend haga algo cuando ocurre un evento en un contrato (ej: alguien compra tu NFT), configura un Stream en Moralis para que te envíe un webhook. Es mucho más eficiente que hacer 'polling' constante a un nodo RPC y Moralis gestiona la complejidad por ti.
Recuerda el Propósito de Moralis: Simplificar Tu Backend Web3:

Moralis te da acceso fácil a datos on-chain y funcionalidades backend comunes para que no tengas que operar infraestructura blockchain compleja. Te permite enfocarte en la lógica de negocio de tu dApp.
Lee la Documentación Específica de la API/Funcionalidad que Necesitas:

Una vez que tienes una idea general, profundiza en la documentación de la API específica (ej: 'EVM API Reference') o la funcionalidad (ej: 'Streams Documentation') que estás implementando para ver todos los detalles, parámetros y ejemplos.
Explora la Funcionalidad IPFS si Necesitas Almacenamiento Descentralizado:

Si tu dApp maneja archivos descentralizados (metadatos NFT, contenido de dApp), la API IPFS de Moralis simplifica la subida y el pineado de archivos. Es una forma fácil de interactuar con IPFS sin ejecutar tu propio nodo.

Herramientas relacionadas

Si te interesa Moralis, también podrías explorar estas herramientas:

Recursos útiles

Amplía tus conocimientos con estos enlaces y materiales: