Documentation

Overview

Monad Atlas provides EVM-compatible RPC and WebSocket access to the Monad blockchain, plus custom address-centric transfer streams for wallet monitoring.

Endpoints

Authentication

All requests require a valid API key.

Browser WebSocket clients cannot set custom headers. Use the query param: ?api_key=YOUR_KEY.

Quick Start

The examples below fetch the latest block number and subscribe to new block headers.

HTTP RPC

curl -X POST https://api.monadatlas.com/rpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

WebSocket (raw)

Subscribe to new block headers. Send this after connecting:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newHeads"]
}

Event response:

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x123",
    "result": { "number": "0x3912345", "hash": "0x...", ... }
  }
}

WebSocket (ethers.js)

import { ethers } from 'ethers';

const provider = new ethers.WebSocketProvider(
  'wss://api.monadatlas.com/ws?api_key=YOUR_KEY'
);

provider.on('block', (blockNumber) => {
  console.log('New block:', blockNumber);
});

HTTP JSON-RPC

Standard EVM JSON-RPC over HTTPS. Supports eth_blockNumber, eth_getBlockByNumber, eth_getTransactionByHash, eth_getLogs, eth_call, eth_estimateGas, eth_sendRawTransaction, and other standard methods.

Use eth_getLogs for historical log queries with fromBlock / toBlock.

WebSocket Subscriptions

Standard eth_subscribe subscriptions. Compatible with ethers, web3, viem.

Production Behavior

• Idle timeout: Connections may close after extended inactivity. Reconnect and resubscribe.
• Ping/pong: Server sends periodic pings. Clients should respond to keep the connection alive.
• Reconnect: After disconnect, resubscribe and backfill from the last processed block if needed. Clients should store the last processed block number and backfill using eth_getLogs or RPC queries after reconnect.
• Ordering: Events are delivered in block order. No ordering guarantee across reconnects.
• Duplicates: Events may be delivered more than once after reconnect. Dedupe by txHash + logIndex.
• Finality: Do not assume pending events are final. Wait for block confirmations for critical logic.

Atlas Custom API

REST endpoints backed by the Monad Atlas indexer. Same API key as RPC.

address_transfers

Historical transfers for a wallet. Native MON, ERC20, ERC721, ERC1155 in one feed.

Example

curl "https://api.monadatlas.com/api/address_transfers?address=0xabc123...&limit=20" \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "transfers": [
    {
      "id": 12345,
      "blockNumber": 59880434,
      "txHash": "0x...",
      "transferType": "erc20",
      "from": "0x...",
      "to": "0xabc123...",
      "tokenAddress": "0x...",
      "amount": "1000",
      "direction": "in",
      "timestamp": "2025-03-07T20:00:00Z"
    }
  ],
  "nextCursor": 12325,
  "count": 20
}

transferType: native_direct | erc20 | erc721 | erc1155

Wallet Monitoring

Two options for monitoring wallet transfer activity.

A. Standard EVM Logs

Use eth_subscribe("logs", filter) for contract event monitoring.

Best for: Known contracts, known topics, standard event-driven apps.

Limitations: Native MON transfers are not logs. Token transfers require known contract addresses. Clients must decode event ABI.

B. Atlas Wallet Transfer Stream Preview

Use wallet_transfers to monitor all transfer activity for an address in one stream.

This feature is currently in preview and may change before general availability.

Best for: Wallets, native MON tracking, token-agnostic monitoring, simpler client integrations.

Benefits: One wallet, one stream. Native MON + ERC20 + ERC721 + ERC1155. Enriched payloads. In/out/both direction.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "wallet_transfers",
    {
      "address": "0xabc123...",
      "direction": "both",
      "includeNative": true,
      "includeTokens": true
    }
  ]
}

direction: in | out | both

Monitor incoming transfers only

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "wallet_transfers",
    {
      "address": "0xabc123...",
      "direction": "in"
    }
  ]
}

Event Payload

{
  "subscription": "sub_123",
  "result": {
    "blockNumber": 59880434,
    "txHash": "0x...",
    "assetType": "native",
    "tokenAddress": null,
    "symbol": "MON",
    "from": "0x...",
    "to": "0xabc123...",
    "amount": "3.0",
    "direction": "in"
  }
}

assetType: native | erc20 | erc721 | erc1155

Which Should I Use?

Errors and Limits

Error Payloads

HTTP (401 Unauthorized):

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Missing or invalid X-API-Key header"
  }
}

WebSocket (connection rejected):

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Missing or invalid X-API-Key header"
  }
}

Limits

• Concurrent WebSocket connections: 5 per API key
• Subscriptions per connection: 10
• Mempool coverage: Pending tx stream may be restricted. No guaranteed mempool coverage unless explicitly enabled.
• Rate limits: Rate limits may apply depending on plan tier.

Support

access@monadatlas.com