API Documentation

Trading API and real-time WebSocket data for NAD.fun on Monad

Real-Time Data Stream:
wss://monadtrenches.com/ws?api_key=YOUR_KEY
Live token creations and trades. See the "Data Stream" tab below.

About This Service: Monad Trenches provides a managed API for NAD.fun trading and real-time data streams. Nonces, gas prices, and transaction assembly are handled automatically.

Buy/Sell API

Buy and sell endpoints that handle nonces, gas prices, and transaction assembly automatically. You sign and broadcast the transaction.

Fee Structure: All transactions are subject to a 0.5% fee in each direction, automatically included in the calldata.

How it works: The API fetches nonces and gas prices from Monad RPC automatically. You only need to sign and broadcast the transaction.

Buy

Purchase tokens using MON.

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": "0x670f873c33301428141C0822a63dafdd0ce85927",  // Router address (use /api/router/info to fetch dynamically)
    "from": "0xYourWalletAddress...",
    "data": "0x...",  // Transaction calldata
    "value": "10500000000000000000",  // Amount in wei
    "gas": "180000",  // Gas limit (padded 20%)
    "gas_price": "52000000000",  // Legacy gas price in wei
    "max_fee_per_gas": "300000000000",  // EIP-1559 max fee (recommended)
    "max_priority_fee_per_gas": "100000000000",  // EIP-1559 tip
    "base_fee_per_gas": "50000000000",  // Current base fee (reference)
    "nonce": 42,  // Nonce (from RPC)
    "chain_id": 143  // Monad mainnet
  },
  "metadata": {
    "action": "buy",
    "amount_mon": "10.50000000",
    "fee_bps": 50
  }
}

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.",
  "transaction": {
    "to": "0x670f873c33301428141C0822a63dafdd0ce85927",  // Router address
    "from": "0xYourWalletAddress...",
    "data": "0x...",
    "value": "0",
    "gas": "200000",
    "gas_price": "52000000000",
    "max_fee_per_gas": "300000000000",
    "max_priority_fee_per_gas": "100000000000",
    "base_fee_per_gas": "50000000000",
    "nonce": 43,
    "chain_id": 143
  },
  "metadata": {
    "action": "sell",
    "amount_tokens": "1000000000000000000",
    "fee_bps": 50,
    "base_token": "0x91b8...",  // only for alt-base tokens (e.g. LVMON)
    "receive_token": "0x91b8..."  // null = MON, set = base token (no conversion pair)
  }
}

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}
Headers:
  X-API-Key: your_api_key

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

# Router Address (Spender) — fetch dynamically:
GET /api/router/info  // Returns {"router_address": "0x...", ...}

# Current address:
0x670f873c33301428141C0822a63dafdd0ce85927

Integration Checklist

Call the buy or sell endpoint (nonce & gas price are fetched automatically)
Sign and broadcast the transaction using your RPC provider
Handle transaction receipt and errors
For sells: approve the router contract first

Real-Time Data Stream

Live stream of all token creations and trades on NAD.fun via WebSocket.

Connection

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

Limits: Up to 5 concurrent WebSocket connections per API key.

Message Format

Token Creation:

{
  "type": "token",
  "trade_type": "create",
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "token_symbol": "SYMBOL",
  "token_name": "Token Name",
  "image_url": "https://...",
  "amount_mon": 26795.57,  // Creator's initial buy
  "market_cap_usd": 3847.82,
  "price_mon": 0.000003848,
  "trader": "0xCreatorAddress...",
  "creator_token_count": 5,
  "tx_hash": "0x...",
  "contract_version": "V2",  // "V1" or "V2" (NAD.fun contract version)
  "block_number": 12345678,
  "timestamp": "2025-12-21T10:30:45.123Z",
  "creator_fee_rate": 100,  // creator fee in bps (V2 only, 100 = 1%)
  "vault_allocations": [  // fee vault routing (V2 only)
    { "vault_type": "burn", "bps": 5000 },
    { "vault_type": "lp", "bps": 3000 },
    { "vault_type": "creator", "bps": 2000 }
  ]
}

Buy/Sell Trade:

{
  "type": "trade",
  "trade_type": "buy",  // or "sell"
  "trading_venue": "bonding_curve",  // or "dex"
  "token_address": "0x9F22b83201C4Bb56aea8D20257594FD7A7AE7777",
  "token_symbol": "SYMBOL",
  "token_name": "Token Name",
  "image_url": "https://...",
  "amount_mon": 30.0,
  "market_cap_usd": 4278.02,
  "price_mon": 0.000004278,
  "trader": "0xTraderAddress...",
  "tx_hash": "0x...",
  "contract_version": "V1",  // "V1" or "V2"
  "block_number": 12345679,
  "timestamp": "2025-12-21T10:31:12.456Z"
}

NAD.fun Contract Versions (Sniper Tax):
Every event includes contract_version ("V1" or "V2").
V1 tokens have no sniper tax.
V2 tokens have a sniper tax that penalizes buys within the first few blocks after creation (up to 20% penalty at block 2, tapering to 0% by block 7). V2 also charges a flat 1% fee on buys and sells. Factor this into your slippage calculations for early V2 buys.

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':
        version = data.get('contract_version', 'V1')
        print(f"NEW TOKEN [{version}]: {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 a ping every 30 seconds. Most WebSocket libraries handle this with ping_interval=30.