moralis-data-api

CRITICAL: Read Rule Files Before Implementing

The #1 cause of bugs is not reading the endpoint rule file before writing code.

For EVERY endpoint:

1. Read rules/{EndpointName}.md
2. Find "Example Response" section
3. Copy the EXACT JSON structure
4. Note field names (snake_case), data types, HTTP method, path, wrapper structure

Reading Order:

1. This SKILL.md (core patterns)
2. Endpoint rule file in rules/
3. references/PricingAndPremium.md when the user asks about CU costs, premium endpoints, or plan requirements
4. Pattern references in references/ (for edge cases only)

Setup

API Key (optional)

Never ask the user to paste their API key into the chat. Instead:

1. Check if MORALISAPIKEY is set in the environment (try running [ -n "$MORALISAPIKEY" ] && echo "API key is set" || echo "API key is NOT set").
2. If not set, offer to create the .env file with an empty placeholder: MORALISAPIKEY=
3. Tell the user to open the .env file and paste their key there themselves.
4. Let them know: without the key, you won't be able to test or call the Moralis API on their behalf.

If they don't have a key yet, point them to admin.moralis.com/register (free, no credit card).

Environment Variable Discovery

The .env file location depends on how skills are installed:

Create the .env file in the project root (same directory the user runs Claude Code from). Make sure .env is in .gitignore.

Verify Your Key

curl "https://deep-index.moralis.io/api/v2.2/YOUR_EVM_ADDRESS/balance?chain=0x1" \
  -H "X-API-Key: $MORALIS_API_KEY"

Base URLs

Authentication

All requests require: X-API-Key: $MORALISAPIKEY

Quick Reference: Most Common Patterns

Data Type Rules

Block Numbers (always decimal)

block_number: 12386788; // number - use directly
block_number: "12386788"; // string - parseInt(block_number, 10)

Timestamps (usually ISO strings)

"2021-05-07T11:08:35.000Z"; // → new Date(timestamp).getTime()

Balances (always strings unless its a property named "formatted" eg. balanceFormatted, BigInt)

balance: "1000000000000000000";
// → (Number(BigInt(balance)) / 1e18).toFixed(6)

Response Patterns

// Safe extraction
const data = Array.isArray(response) ? response : response.result || [];

Common Field Mappings

token_address → tokenAddress
from_address_label → fromAddressLabel
block_number → blockNumber
receipt_status: "1" → success, "0" → failed
possible_spam: "true"/"false" → boolean check

Common Pitfalls (Top 5)

1. Block numbers are decimal, not hex - Use parseInt(x, 10), not parseInt(x, 16)
2. Timestamps are ISO strings - Use new Date(timestamp).getTime()
3. Balances are strings - Use BigInt(balance) for math
4. Response may be wrapped - Check for .result before .map()
5. Path inconsistencies - Some use /wallets/{address}/..., others /{address}/...

See [references/CommonPitfalls.md](references/CommonPitfalls.md) for complete reference.

Pagination

Many endpoints use cursor-based pagination:

# First request
curl "...?limit=100" -H "X-API-Key: $KEY"

# Next page
curl "...?limit=100&cursor=<cursor_from_response>" -H "X-API-Key: $KEY"

See [references/Pagination.md](references/Pagination.md) for details.

Testing Endpoints

ADDRESS="YOUR_EVM_ADDRESS"
CHAIN="0x1"

# Wallet Balance
curl "https://deep-index.moralis.io/api/v2.2/${ADDRESS}/balance?chain=${CHAIN}" \
  -H "X-API-Key: $MORALIS_API_KEY"

# Token Price
curl "https://deep-index.moralis.io/api/v2.2/erc20/YOUR_EVM_ADDRESS/price?chain=${CHAIN}" \
  -H "X-API-Key: $MORALIS_API_KEY"

# Wallet Transactions (note result wrapper)
curl "https://deep-index.moralis.io/api/v2.2/${ADDRESS}?chain=${CHAIN}&limit=5" \
  -H "X-API-Key: $MORALIS_API_KEY" | jq '.result'

Quick Troubleshooting

Performance & Timeouts

Most endpoints respond quickly under normal conditions. Response times can vary based on wallet activity volume, chain, and query complexity.

Recommended client timeouts:

• Simple queries (balance, price, metadata): 10s
• Complex queries (wallet history, DeFi positions): 30s

Large wallets with extensive transaction histories may take longer — use pagination with reasonable limit values.

See [references/PerformanceAndLatency.md](references/PerformanceAndLatency.md) for optimization tips.

Pricing and Plan Requirements

Data API endpoints have explicit Compute Unit (CU) costs, and some endpoints require Starter or Pro plans. Use [references/PricingAndPremium.md](references/PricingAndPremium.md) before answering cost, quota, premium endpoint, or plan-gating questions.

Default Chain Behavior

EVM addresses (0x...): Default to Ethereum (chain=0x1) unless specified.

Solana addresses (base58): Auto-detected and routed to Solana API.

Supported Chains

EVM (40+ chains): Ethereum (0x1), Polygon (0x89), BSC (0x38), Arbitrum (0xa4b1), Optimism (0xa), Base (0x2105), Avalanche (0xa86a), and more.

Solana: Mainnet, Devnet

See [references/SupportedApisAndChains.md](references/SupportedApisAndChains.md) for full list.

Endpoint Catalog

Complete list of all 156 endpoints (106 EVM + 35 Solana + 15 Universal / Bitcoin) organized by category.

Wallet

Balances, tokens, NFTs, transaction history, profitability, and net worth data.

Token

Token prices, metadata, pairs, DEX swaps, analytics, security scores, and sniper detection.

NFT

NFT metadata, transfers, traits, rarity, floor prices, and trades.

DeFi

DeFi protocol positions, liquidity, and exposure data.

Entity

Labeled addresses including exchanges, funds, protocols, and whales.

Price

Token and NFT prices, OHLCV candlestick data.

Blockchain

Blocks, transactions, date-to-block conversion, and contract functions.

Discovery

Trending tokens, blue chips, market movers, and token discovery.

Other

Utility endpoints including API version, endpoint weights, and address resolution.

Solana Endpoints

Solana-specific endpoints (24 native + 11 EVM variants that support Solana chain = 35 total).

Universal / Bitcoin Endpoints

Universal v1 endpoints used by the Bitcoin Data API and cross-chain Universal API pages.

Reference Documentation

• [references/CommonPitfalls.md](references/CommonPitfalls.md) - Complete pitfalls reference
• [references/DataTransformations.md](references/DataTransformations.md) - Type conversion reference
• [references/DataFeatureGuidance.md](references/DataFeatureGuidance.md) - Enrichment, safety, pricing, and discovery feature behavior
• [references/FilteredTokens.md](references/FilteredTokens.md) - Token discovery metrics, timeframes, filters, and examples
• [references/ApiResponseCodes.md](references/ApiResponseCodes.md) - Common status codes and response field conventions
• [references/PerformanceAndLatency.md](references/PerformanceAndLatency.md) - Response time guidance, timeout recommendations, caching
• [references/ResponsePatterns.md](references/ResponsePatterns.md) - Pagination patterns
• [references/SpamDetection.md](references/SpamDetection.md) - Spam detection behavior and filtering guidance
• [references/SupportedApisAndChains.md](references/SupportedApisAndChains.md) - Chains and APIs
• [references/UniversalAndBitcoin.md](references/UniversalAndBitcoin.md) - Universal v1 and Bitcoin Data API request patterns

See Also

• Endpoint rules: rules/*.md files
• Streams API: @moralis-streams-api for real-time events