Multi-Launchpad Analytics Infrastructure

MON $0.00

NAD.fun API & Monad WebSocket Documentation

Complete guide to NAD.fun API and Monad WebSocket access. Real-time trading, WebSocket streams, and analytics for Monad blockchain

📡 Real-Time Data Stream:
wss://monadtrenches.com/ws?api_key=YOUR_KEY
Live token creations & trades • See "Data Stream" tab below for details

💡 About This Service:
Monad Trenches provides a managed API service for NAD.fun trading and real-time data streams. This API abstracts the complexity of Monad blockchain transactions, gas optimization, and data aggregation. All transaction parameters (gas, slippage, etc.) are optimized by our service—simply use the values we provide.

💰 Buy/Sell API (Advanced)

Execute buy and sell transactions programmatically with full control over your wallet and transactions. You handle all RPC communication, transaction building, broadcasting, and receipt polling.

⚠️ Fee Structure: All buy and sell transactions executed through this API are subject to a 0.5% fee in each direction. This fee is automatically included in the transaction calldata.

Integration Mode: You handle all RPC communication, transaction building, broadcasting, and receipt polling. We provide transaction calldata and slippage calculations.

📘 Integration Guide

Essential information for automated trading systems

1. Token Decimals & Units

All NAD.fun tokens use 18 decimals (standard ERC20).

All token amounts in API responses are in wei (1 token = 10¹⁸ wei)
MON amounts: amount_mon_wei = amount_mon × 10¹⁸
Token amounts: expected_tokens_wei is in wei, divide by 10¹⁸ for human-readable
SELL IMPORTANT: You must approve token amount in wei, not human-readable units

2. Approve Flow (REQUIRED for Selling)

Before selling tokens, you MUST approve the router contract to spend your tokens:

# Step 1: Check current allowance
GET /api/router/approve/check/{token_address}/{owner_address}

# Response:
{
  "token_address": "0x9f22...",
  "owner_address": "0x6181...",
  "spender_address": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",  // Router
  "current_allowance": "0",  // In wei
  "needs_approval": true,
  "is_unlimited": false
}

# Step 2: Build approval transaction (if needed)
POST /api/router/approve/build
{
  "token_address": "0x9f22...",
  "owner_address": "0x6181...",
  "amount": "max"  // or specific amount in wei
}

# Response:
{
  "message": "Approval transaction built",
  "transaction": {
    "to": "0x9f22...",  // Token contract
    "data": "0x095ea7b3...",  // approve(spender, amount)
    "value": "0",
    "gas_estimate": "50000",
    "gas_price": "102000000000"
  },
  "spender_address": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",
  "amount": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
}

Spender Address (Router): 0x28F07093BEe80180080FCE4564A21487fDc4Ac46

This address is intended to remain stable long-term. Any changes will be announced in advance.

3. Gas Model (EIP-1559 Recommended)

Monad supports EIP-1559 gas pricing for better transaction ordering and refunds:

✅ Recommended: EIP-1559 (Better Performance)

maxFeePerGas: Maximum total fee (base + tip + buffer) - protects against spikes
maxPriorityFeePerGas: Validator tip (100 gwei for snipes) - determines transaction ordering
baseFeePerGas: Current network base fee (for reference)
Benefits: Better same-block ordering, automatic refunds when base fee is low

⚠️ Legacy: gasPrice (Backward Compatible)

gasPrice: Legacy single gas price field (still supported for existing bots)
Note: EIP-1559 is recommended for new implementations

Common Fields:

Gas Limit: Our gas_estimate is padded by 20% for safety. You can use it as-is.
Chain ID: Always 143 (Monad mainnet)

4. Limits & Expected Errors

Limit Type	Limit	Notes
WebSocket Connections	5 concurrent	Per API key

Common Error Codes:

401 Unauthorized - Invalid or missing API key
403 Forbidden - API key deactivated or expired
429 Too Many Requests - WebSocket connection limit reached (max 5 concurrent per API key)
400 Bad Request - Invalid parameters (check error field in response)
404 Not Found - Token not indexed yet (see #5 below)
500 Internal Server Error - Service temporarily unavailable (retry after a few seconds)

5. Token Availability

New tokens may not be immediately available:

WebSocket "token" event: Token creation detected (may not be tradeable immediately)
Quote/Build endpoints: May return 404 for brand new tokens
Error Handling: If you receive a 404, wait a few seconds and retry. If errors persist, the token may not be tradeable yet.
Allowlist Check: Use GET /api/router/allowlist/{token_address} to verify token is on NAD.fun

💡 Tip: Handle transient 404 errors gracefully in your code. Our service handles token indexing automatically—simply retry failed requests after a short delay.

6. Transaction Field Notes

from field: Pre-filled for convenience. Override this with your actual wallet address
nonce: Not included. Use GET /api/router/nonce/{address} to get latest nonce
gas_estimate: Already padded by 20% - safe to use as gas limit
value (for buys): Total MON needed including our 0.5% fee. Send this exact amount.
data: Pre-encoded calldata. Do not modify.

Buy Transaction Endpoint

POST /api/router/buy

Request Body:

{
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "trade_amount_mon": 500,  // Buy with 500 MON
  "slippage_percent": 5.0,  // 5% slippage protection
  "user_address": "0xYourAddress..."
}

Response Example:

{
  "success": true,
  "message": "Buy transaction built successfully. Sign and broadcast this transaction.",
  "transaction": {
    "to": "0x9504b38d01186577d9ae100f4dd7c6e3c747f063",  // Router contract
    "from": "0x6181e387f1c162363fb5b91d62c318f4985bfcf2",
    "data": "0x1622dbe4...",  // Encoded calldata
    "value": "502500000000000000000",  // 502.5 MON (500 + 0.5% fee) in wei
    "gas_estimate": "300000",  // Recommended gas limit
    "gas_price": "102000000000",  // Legacy gas price (backward compatibility)
    "max_fee_per_gas": "300000000000",  // EIP-1559 max fee (recommended)
    "max_priority_fee_per_gas": "100000000000",  // EIP-1559 tip (100 gwei for snipes)
    "base_fee_per_gas": "100000000000",  // Base fee (reference)
    "chain_id": "143"  // Monad mainnet
  },
  "metadata": {
    "token_address": "0x9f22b83201c4bb56aea8d20257594fd7a7ae7777",
    "amount_mon": "500",
    "amount_mon_wei": "500000000000000000000",
    "expected_tokens_wei": "2183045795938762422810119",  // ~2.18B tokens expected
    "min_tokens_wei": "2073893506141824301669613",  // Min tokens (with 5% slippage)
    "fee_mon": "2.50",  // 0.5% fee = 2.5 MON
    "fee_wei": "2500000000000000000",
    "slippage_percent": 5.0,
    "timestamp": 1734715063
  }
}

Complete Python Example (DIY Mode):

from web3 import Web3
import requests

# Setup
API_KEY = "your_api_key"
PRIVATE_KEY = "0x..."
USER_ADDRESS = "0x..."
RPC_URL = "https://your-rpc.monad-mainnet.quiknode.pro/..."

w3 = Web3(Web3.HTTPProvider(RPC_URL))

# Step 1: Get transaction data from API
tx_data = requests.post(
    "https://monadtrenches.com/api/router/buy",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
        "trade_amount_mon": 500,
        "slippage_percent": 5.0,
        "user_address": USER_ADDRESS
    }
).json()

if not tx_data['success']:
    print(f"API Error: {tx_data.get('error', 'Unknown')}")
    exit()

# Step 2: Sign and broadcast transaction
# IMPORTANT: This example shows the conceptual flow only.
#
# You will need to:
# 1. Get nonce from your RPC provider
# 2. Build transaction object using fields from API response
# 3. Sign transaction with your private key
# 4. Broadcast to your RPC provider
# 5. Wait for transaction receipt
#
# For production implementations, use Simple Mode API or contact us for integration support.

Sell Transaction Endpoint

POST /api/router/sell

Request Body:

{
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "amount_in_tokens": "1000000000000000000000",  // Amount in wei (1000 tokens)
  "slippage_percent": 5.0,
  "user_address": "0xYourAddress..."
}

Response Example:

{
  "success": true,
  "message": "Sell transaction built successfully. Sign and broadcast this transaction.",
  "transaction": {
    "to": "0x9504b38d01186577d9ae100f4dd7c6e3c747f063",
    "from": "0x6181e387f1c162363fb5b91d62c318f4985bfcf2",
    "data": "0x6d1b229d...",
    "value": "0",  // No MON sent for sell
    "gas_estimate": "300000",
    "gas_price": "102000000000",  // Legacy gas price (backward compatibility)
    "max_fee_per_gas": "300000000000",  // EIP-1559 max fee (recommended)
    "max_priority_fee_per_gas": "100000000000",  // EIP-1559 tip (100 gwei for snipes)
    "base_fee_per_gas": "100000000000",  // Base fee (reference)
    "chain_id": "143"
  },
  "metadata": {
    "token_address": "0x9f22b83201c4bb56aea8d20257594fd7a7ae7777",
    "amount_in_tokens": "1000",
    "amount_in_wei": "1000000000000000000000",
    "expected_mon_wei": "245000000000000000000",  // ~245 MON expected
    "min_mon_wei": "232750000000000000000",  // Min MON (with 5% slippage)
    "expected_mon_after_fee": "243.78",  // After 0.5% fee
    "fee_mon": "1.22",
    "slippage_percent": 5.0,
    "timestamp": 1734715123
  }
}

⚠️ Important for Selling: You must approve the router contract to spend your tokens before you can sell. Use the /api/router/approve/check and /api/router/approve/build endpoints.

Quote Endpoints (No Transaction)

POST /api/router/quote/buy

Get buy quote without building transaction

Request:

{
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "amount_mon": 500,
  "slippage_percent": 5.0
}

Response:

{
  "success": true,
  "quote": {
    "expected_tokens": "2183045795.938762422810119",  // Human-readable (billions)
    "expected_tokens_wei": "2183045795938762422810119",
    "min_tokens": "2073893506.141824301669613",
    "min_tokens_wei": "2073893506141824301669613",
    "price_per_token_mon": "0.000000229",
    "slippage_percent": 5.0,
    "fee_mon": "2.50",
    "total_cost_mon": "502.50"  // Including 0.5% fee
  }
}

POST /api/router/quote/sell

Get sell quote without building transaction

Request:

{
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "amount_tokens": "1000000000000000000000",  // Wei (1000 tokens)
  "slippage_percent": 5.0
}

Response:

{
  "success": true,
  "quote": {
    "expected_mon": "245.00",
    "expected_mon_wei": "245000000000000000000",
    "min_mon": "232.75",
    "min_mon_wei": "232750000000000000000",
    "expected_mon_after_fee": "243.78",  // After 0.5% fee
    "fee_mon": "1.22",
    "slippage_percent": 5.0
  }
}

Error Handling

Common Error Responses:

// Invalid token
{
  "success": false,
  "error": "Token does not exist or has not been indexed yet"
}

// Brand new token (< 1 second old)
{
  "success": false,
  "error": "Unable to calculate slippage protection for this token. This can happen for brand new tokens (< 1 second old) or during RPC issues. Please retry in 1-2 seconds."
}

// Invalid address format
{
  "success": false,
  "error": "Invalid token address format"
}

// Missing required field
{
  "success": false,
  "error": "Missing required field: trade_amount_mon"
}

⚠️ Advanced Mode Requirements:

Advanced Mode returns transaction data that you must sign and broadcast yourself. You are responsible for:

Getting nonce from your RPC provider
Using gas parameters from our API response (we optimize these for you)
Building and signing the transaction
Broadcasting to your RPC provider
Handling transaction receipts and errors

💡 Recommendation: For production bots, use Simple Mode API to reduce complexity and ensure reliability.

⚡ Buy/Sell API (Simple)

Beginner-friendly buy and sell endpoints that automatically handle nonces, gas prices, and transaction assembly. Perfect for quick integrations!

⚠️ Fee Structure: All buy and sell transactions executed through this API are subject to a 0.5% fee in each direction. This fee is automatically included in the transaction calldata.

✨ What's Different: Simple Mode automatically fetches nonces and gas prices from the Monad RPC, so you only need to sign and broadcast the transaction. No need to query RPC yourself!

Simple Buy

Purchase tokens using MON. The API handles nonce and gas price lookup automatically.

POST /api/router/simple/buy
Headers:
  X-API-Key: your_api_key

Request Body:
{
  "wallet_address": "0xYourWalletAddress...",
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "amount_mon": 10.5,  // Amount in MON (human-readable)
  "slippage_bps": 50  // Optional, defaults to 50 (0.5%)
}

Response:
{
  "success": true,
  "message": "Transaction ready! Sign and broadcast this transaction with your wallet.",
  "transaction": {
    "to": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",  // Router address
    "from": "0xYourWalletAddress...",
    "data": "0x...",  // Transaction calldata
    "value": "10500000000000000000",  // Amount in wei
    "gas": "180000",  // Gas limit (padded 20%)
    "gas_price": "102000000000",  // Gas price in wei (from RPC)
    "nonce": 42,  // Nonce (from RPC)
    "chain_id": 143  // Monad mainnet
  },
  "metadata": {
    "action": "buy",
    "amount_mon": "10.50000000",
    "fee_bps": 50
  }
}

Simple Sell

Sell tokens back to MON. Important: You must approve the router to spend your tokens first (see Approve Flow below).

POST /api/router/simple/sell
Headers:
  X-API-Key: your_api_key

Request Body:
{
  "wallet_address": "0xYourWalletAddress...",
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "amount_tokens": "1000000000000000000",  // Amount in wei (18 decimals)
  "slippage_bps": 50  // Optional, defaults to 50 (0.5%)
}

Response:
{
  "success": true,
  "message": "Transaction ready! Make sure you've approved the router to spend your tokens first (see /approve endpoint).",
  "transaction": {
    "to": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",  // Router address
    "from": "0xYourWalletAddress...",
    "data": "0x...",  // Transaction calldata
    "value": "0",
    "gas": "200000",  // Gas limit (padded 20%)
    "gas_price": "102000000000",  // Gas price in wei (from RPC)
    "nonce": 43,  // Nonce (from RPC)
    "chain_id": 143  // Monad mainnet
  },
  "metadata": {
    "action": "sell",
    "amount_tokens": "1000000000000000000",
    "fee_bps": 50
  }
}

Approve Flow (Required for Selling)

Before selling tokens, you must approve the router contract to spend your tokens. Use the same approve endpoints as in Buy/Sell API:

# Step 1: Check current allowance
GET /api/router/approve/check/{token_address}/{owner_address}

# Step 2: Build approval transaction (if needed)
POST /api/router/approve/build
{
  "token_address": "0x9f22...",
  "owner_address": "0x6181...",
  "amount": "max"  // or specific amount in wei
}

# Router Address (Spender):
0x28F07093BEe80180080FCE4564A21487fDc4Ac46

Integration Steps

✅ Simple Mode Checklist:

✅ Call Simple Mode endpoint (nonce & gas price fetched automatically)
✅ Sign and broadcast transaction using your RPC provider
✅ Handle transaction receipt and errors
✅ Handle errors and retries yourself

💡 When to Use Simple Mode: Use Simple Mode if you want the API to handle nonce and gas price lookup automatically. Use Buy/Sell API (DIY Mode) if you prefer to query RPC yourself for more control.

📡 Monad WebSocket & NAD.fun WebSocket Stream

Real-time Monad WebSocket stream of all token creations and trades on NAD.fun. Connect to our NAD.fun WebSocket for live trading data on the Monad blockchain.

Connection

wss://monadtrenches.com/ws?api_key=YOUR_API_KEY

Message Format

Token Creation:

{
  "type": "token",
  "trade_type": "create",
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "token_symbol": "SYMBOL",
  "token_name": "Token Name",
  "amount_mon": 26795.57,  // Creator's initial liquidity
  "market_cap_usd": 3847.82,  // Initial market cap in USD
  "price_mon": 0.000003848,  // Initial price per token
  "trader": "0xCreatorAddress...",  // Token creator's wallet
  "creator_token_count": 5,  // Number of tokens created by this creator
  "tx_hash": "0x...",
  "timestamp": "2025-12-21T10:30:45.123Z"
}

Buy/Sell Trade:

{
  "type": "trade",
  "trade_type": "buy",  // or "sell"
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "token_symbol": "SYMBOL",
  "token_name": "Token Name",
  "amount_mon": 30.0,  // Trade size in MON
  "market_cap_usd": 4278.02,  // Market cap after trade
  "price_mon": 0.000004278,  // Price per token after trade
  "trader": "0xTraderAddress...",  // Wallet who made the trade
  "tx_hash": "0x...",
  "timestamp": "2025-12-21T10:31:12.456Z"
}

Python Example

import websocket
import json

API_KEY = "your_api_key"
WS_URL = f"wss://monadtrenches.com/ws?api_key={API_KEY}"

def on_message(ws, message):
    data = json.loads(message)
    
    if data['type'] == 'token':
        print(f"🎉 NEW TOKEN: {data['token_symbol']}")
    
    elif data['type'] == 'trade':
        print(f"📊 {data['trade_type'].upper()}: {data['amount_mon']} MON")

ws = websocket.WebSocketApp(WS_URL, on_message=on_message)
ws.run_forever(ping_interval=30)

ℹ️ Keep-Alive: Send ping every 30 seconds. Most WebSocket libraries handle this with ping_interval=30.