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": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",  // Router address
    "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": "0x28F07093BEe80180080FCE4564A21487fDc4Ac46",
    "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
  }
}

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):
0x28F07093BEe80180080FCE4564A21487fDc4Ac46

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...",
  "block_number": 12345678,
  "timestamp": "2025-12-21T10:30:45.123Z"
}

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...",
  "block_number": 12345679,
  "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 a ping every 30 seconds. Most WebSocket libraries handle this with ping_interval=30.