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. 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 MORALIS_API_KEY is set in the environment (try running [ -n "$MORALIS_API_KEY" ] && 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: MORALIS_API_KEY=
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/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balance?chain=0x1" \
  -H "X-API-Key: $MORALIS_API_KEY"

Base URLs

Authentication

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

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 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 for details.

Testing Endpoints

ADDRESS="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
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/0x6B175474E89094C44Da98b954EedeAC495271d0F/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 for optimization tips.

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 for full list.

Endpoint Catalog

Complete list of all 136 endpoints (102 EVM + 34 Solana) 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 + 10 EVM variants that support Solana chain = 34 total).

Reference Documentation

• references/CommonPitfalls.md - Complete pitfalls reference
• references/DataTransformations.md - Type conversion reference
• references/FilteredTokens.md - Token discovery metrics, timeframes, filters, and examples
• references/PerformanceAndLatency.md - Response time guidance, timeout recommendations, caching
• references/ResponsePatterns.md - Pagination patterns
• references/SupportedApisAndChains.md - Chains and APIs

See Also

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