Moralis

Skill based on Moralis docs, generated 2026-02-09. Official docs: https://docs.moralis.io

Moralis provides indexed Web3 APIs for EVM and Solana: wallet balances, token/NFT metadata, prices, transactions, real-time Streams (webhooks), and Auth API for wallet sign-in. Moralis Cortex adds AI-powered natural-language queries via hosted API or self-hosted MCP server.

Core References

Features

Realtime & AI

Best Practices

External Links

• Moralis Docs
• Moralis GitHub
• Cortex MCP Server

Generation Info

• Source: sources/moralis (https://github.com/MoralisWeb3/docs)
• Git SHA: bc25e444d31b55bb17f09d977a74e51b6e016564
• Generated: 2026-02-09
• Docs used: docs/01-web3-data-api, 02-streams-api, 03-authentication-api, 08-moralis-cortex, 07-rpc-nodes

Moralis API Best Practices

API Key

• Get key: admin.moralis.com/api-keys
• Never expose in client-side code; use backend or env vars.
• Free tier has rate limits; paid plans for production.

Chain Selection

• EVM: Use EvmChain.ETHEREUM, EvmChain.POLYGON, EvmChain.ARBITRUM, etc., or hex chain ID ("0x1", "0x89").
• Solana: Use "mainnet" or "devnet" in Solana-specific endpoints.
• Check supported chains for availability.

Agent-Oriented Patterns

1. Resolve ENS first: Use resolveAddress or resolveDomain before wallet queries if user provides ENS. 2. Batching: Some endpoints support multiple addresses/tokens per request; prefer batching over loops. 3. Pagination: Use limit and cursor for large result sets. 4. Cortex for complex queries: For "what tokens does X hold?" or "analyze this wallet" type questions, suggest Cortex or MCP if the agent has access. 5. Error handling: Moralis returns structured errors; check for rate limits (429) and invalid chain/address (400).

RPC Nodes

Moralis also provides RPC nodes with extended methods (eth_getTransactions, eth_getNFTBalances, etc.). Use for direct JSON-RPC calls when integrating with ethers.js or viem.

<!-- Source references:

• https://docs.moralis.io/web3-data-api/evm/get-your-api-key
• https://docs.moralis.io/supported-chains
• https://docs.moralis.io/rpc-nodes

-->

Moralis Auth API

Auth API lets users authenticate via signed messages (EIP-4361) from EVM or Solana wallets. Returns a profileId that identifies the user across chains and wallets.

Flow

1. Request challenge — Backend calls requestChallengeEvm or requestChallengeSolana. 2. User signs — Frontend prompts wallet to sign the challenge message. 3. Verify signature — Backend calls verifyChallengeEvm or verifyChallengeSolana.

EVM Example

// 1. Request challenge (backend)
const challenge = await Moralis.Auth.requestChallenge({
  chainId: 1,
  domain: "myapp.com",
  statement: "Sign in to MyApp",
  uri: "https://myapp.com",
  expirationTime: new Date(Date.now() + 600000).toISOString(),
  notBefore: new Date().toISOString(),
  resources: [],
  address: userAddress,
});

// 2. User signs message in wallet (frontend)
const signature = await signMessage(challenge.message);

// 3. Verify (backend)
const result = await Moralis.Auth.verify({
  message: challenge.message,
  signature,
  network: "evm",
});

// result.profileId — use for session/DB

Key Points

• EIP-4361: Standard SiWe (Sign-In with Ethereum) format.
• profileId: Stable ID for the user; supports multiple wallets per user.
• Compatibility: Works with MetaMask, WalletConnect, RainbowKit, Web3Auth, Magic.link, Particle — any wallet that can sign messages.
• Limitation: Auth API does not support EIP-1271 (smart contract wallets).

<!-- Source references:

• https://docs.moralis.io/authentication-api/evm
• https://eips.ethereum.org/EIPS/eip-4361

-->

Wallet, Token & NFT APIs

Agent-friendly patterns for fetching wallet holdings, token metadata, and NFT data via Moralis.

Wallet API

// Native balance
const native = await Moralis.EvmApi.balance.getNativeBalance({
  address, chain,
});

// ERC20 balances (with optional token filter)
const erc20 = await Moralis.EvmApi.token.getWalletTokenBalances({
  address, chain,
  tokenAddresses: ["0xA0b869..."], // optional
});

// NFTs
const nfts = await Moralis.EvmApi.nft.getWalletNFTs({
  address, chain,
  limit: 20, cursor: "...",
});

// Wallet transactions (decoded)
const txs = await Moralis.EvmApi.wallet.getWalletTransactions({
  address, chain,
  limit: 10,
});

// ERC20 transfers
const transfers = await Moralis.EvmApi.token.getWalletTokenTransfers({
  address, chain,
});

// NFT transfers
const nftTransfers = await Moralis.EvmApi.nft.getWalletNFTTransfers({
  address, chain,
});

// ENS / domain resolution
const ens = await Moralis.EvmApi.resolve.resolveAddress({
  domain: "vitalik.eth",
});

Token API (ERC20)

// Token metadata (name, symbol, decimals)
const meta = await Moralis.EvmApi.token.getTokenMetadata({
  addresses: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
  chain,
});

// Token price
const price = await Moralis.EvmApi.token.getTokenPrice({
  address: tokenAddress, chain,
});

// Pair stats (DEX)
const pair = await Moralis.EvmApi.defi.getTokenPairReserves({
  pairAddress, chain,
});

NFT API

// Collection metadata
const collection = await Moralis.EvmApi.nft.getNFTContractMetadata({
  address: nftContract, chain,
});

// Single NFT metadata
const nftMeta = await Moralis.EvmApi.nft.getNFTMetadata({
  address: nftContract, tokenId, chain,
});

// Floor price
const floor = await Moralis.EvmApi.nft.getNFTLowestPrice({
  address: nftContract, chain,
});

Key Points

• address is required for wallet-scoped endpoints.
• Use cursor and limit for pagination.
• Token addresses use checksum format; ENS domains work where supported.
• For Solana: Moralis.SolApi.* namespace with different address formats.

<!-- Source references:

• https://docs.moralis.io/web3-data-api/evm/reference/wallet-api
• https://docs.moralis.io/web3-data-api/evm/reference/token-api
• https://docs.moralis.io/web3-data-api/evm/reference/nft-api

-->

Moralis Web3 Data API

Moralis indexes blockchain data and exposes structured REST APIs for EVM and Solana chains. Use for wallet balances, token/NFT metadata, prices, transactions, and blocks.

SDK Usage (JavaScript/TypeScript)

import Moralis from "moralis";
import { EvmChain } from "moralis/common-evm-utils";

await Moralis.start({ apiKey: process.env.MORALIS_API_KEY });

// Native balance
const balance = await Moralis.EvmApi.balance.getNativeBalance({
  address: "0x...",
  chain: EvmChain.ETHEREUM,
});

// ERC20 token balances with prices
const tokens = await Moralis.EvmApi.token.getWalletTokenBalances({
  address: "0x...",
  chain: EvmChain.ETHEREUM,
});

// NFTs in wallet
const nfts = await Moralis.EvmApi.nft.getWalletNFTs({
  address: "0x...",
  chain: EvmChain.ETHEREUM,
});

// Token price
const price = await Moralis.EvmApi.token.getTokenPrice({
  address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
  chain: EvmChain.ETHEREUM,
});

API Namespaces

Key Points

• Chain parameter: Use EvmChain.ETHEREUM, EvmChain.POLYGON, hex chain ID, or string ("0x1", "eth").
• Response shape: response.result or response.raw depending on endpoint.
• Rate limits: Free tier has limits; paid plans for production.
• REST fallback: Call https://deep-index.moralis.io/api/v2/... with X-API-Key header if not using SDK.

<!-- Source references:

• https://docs.moralis.io/web3-data-api/evm
• https://github.com/MoralisWeb3/docs

-->

Moralis Cortex

Cortex is an AI-native layer for Web3. Query blockchain data in natural language via a hosted REST API or a self-hosted MCP server. Answers are grounded in indexed Moralis data (no hallucinations).

Hosted Cortex API

const response = await fetch("https://cortex-api.moralis.io/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
  body: JSON.stringify({
    message: "What tokens does wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 hold?",
    chatId: "optional-conversation-id", // for multi-turn
    stream: false,
  }),
});

Best for: dashboards, chat agents, in-product insights. No infra setup.

MCP Server (Self-Hosted)

Run the MCP server for full control: your own LLM (OpenAI, Claude, OSS), grounding logic, and privacy.

npm install -g @moralisweb3/api-mcp-server
export MORALIS_API_KEY=your_key
npx @moralisweb3/api-mcp-server --transport stdio

Claude Desktop

{
  "mcpServers": {
    "moralis": {
      "command": "npx",
      "args": ["@moralisweb3/api-mcp-server"],
      "env": { "MORALIS_API_KEY": "your_api_key" }
    }
  }
}

Cursor IDE

Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "moralis": {
      "command": "npx",
      "args": ["@moralisweb3/api-mcp-server"],
      "env": { "MORALIS_API_KEY": "your_api_key" }
    }
  }
}

Example Queries (Natural Language)

• "What's the current price of PEPE and Ethereum?"
• "What tokens does wallet 0x... hold?"
• "Show me the NFTs owned by vitalik.eth on Base"
• "Analyze the portfolio diversity of wallet 0x... across Ethereum and Base"

Key Points

• Grounded: Answers use real indexed data, not model guesses.
• LLM flexibility: Hosted uses Moralis models; self-hosted can use OpenAI, Claude, or OSS.
• MCP package: @moralisweb3/api-mcp-server on NPM.
• Transports: stdio (default for AI clients), web (HTTP), streamable-http.

<!-- Source references:

• https://docs.moralis.io/cortex
• https://docs.moralis.io/cortex/mcp-server/getting-started
• https://docs.moralis.io/cortex/integrations/cursor

-->

Moralis Streams API

Streams API delivers real-time blockchain events to your backend via webhooks. Listen to wallet activity, contract events, NFT transfers, ERC20 transfers, and more.

Concepts

• Stream: Configuration defining what events to listen for and where to send webhooks.
• Triggers: Wallet addresses, contract addresses, topic filters, or "all addresses".
• Webhook URL: Your server endpoint receiving POST with event payload.

Node.js SDK

import Moralis from "moralis";

await Moralis.start({ apiKey: process.env.MORALIS_API_KEY });

// Create stream listening to NFT transfers for a wallet
const stream = await Moralis.Streams.add({
  webhookUrl: "https://your-server.com/webhook",
  description: "NFT transfers for 0x...",
  tag: "nft-transfers",
  chains: ["0x1", "0x89"], // Ethereum, Polygon
  includeContractLogs: false,
  includeNativeTxs: false,
  includeInternalTxs: false,
  abi: [],
  topic0: [],
  filter: {
    or: [
      { eq: ["fromAddress", "0x..."] },
      { eq: ["toAddress", "0x..."] },
    ],
  },
});

// Add address to stream
await Moralis.Streams.addAddress({
  streamId: stream.id,
  address: ["0x..."],
});

Use Cases

• Wallet notifications: Send/receive/stake/swap/burn alerts.
• Asset monitoring: Track specific NFT or token transfers.
• Token sales: Notify on participation.
• Contract events: Use custom ABI and topic filters.
• Factory patterns: Listen to all events from contracts created by a factory.

Key Points

• 100% delivery: Moralis retries webhooks if your server fails.
• Replay: Manually replay history if missed.
• Filters: Limit by amount, address, topic, etc.
• Extended RPC: Streams can include eth_getNativeBalances for addresses in payload.
• Records/pricing: Streams are billed by records; see docs for limits.

<!-- Source references:

• https://docs.moralis.io/streams-api/evm
• https://docs.moralis.io/streams-api/evm/using-node-js-sdk

-->