API Reference

MangroveTrader exposes all tools via two protocols on the same port. Most MCP tools have corresponding REST endpoints. Some tools (trader_last_trade, trader_get_trade_history, trader_cancel_last, trader_watch, trader_unwatch) are MCP-only.

Base URL: https://api.mangrovetraders.com
MCP:      POST /mcp/  (Streamable HTTP)
REST:     /api/v1/*  (free)  |  /api/x402/*  (paid)
Docs:     GET /api/v1/docs/tools  |  GET /openapi.json

Free Endpoints

POST /api/v1/trader/my_stats

Get a trader's score, rank, and open positions.

// Request
{"twitter_handle": "toptrader"}

// Response
{
  "twitter_handle": "toptrader",
  "display_name": "Top Trader",
  "composite_score": 87.4,
  "rank": 3,
  "total_trades": 47,
  "qualified": true,
  "open_positions": 2
}

POST /api/v1/trader/performance_report

Detailed scoring breakdown with component weights.

// Request
{"twitter_handle": "toptrader", "timeframe": "all_time"}

// Response
{
  "twitter_handle": "toptrader",
  "timeframe": "all_time",
  "composite_score": 87.4,
  "rank": 3,
  "total_return_pct": 24.7,
  "avg_return_pct": 0.53,
  "min_return_pct": -3.2,
  "max_return_pct": 8.1,
  "return_stddev": 2.14,
  "sharpe_ratio": 1.82,
  "max_drawdown_pct": 8.3,
  "win_rate": 0.68,
  "trade_count": 47,
  "scoring_weights": {"return": 0.5, "consistency": 0.3, "risk_management": 0.2}
}

x402 Paid Endpoints

All paid endpoints return HTTP 402 if no payment is provided. See x402 Payments for the full payment flow.

POST /api/x402/leaderboard

Full ranked leaderboard. $0.25 USDC base for 100 rows.

// Request
{"timeframe": "all_time", "limit": 100}

// Response (with payment)
{
  "leaderboard": [
    {
      "rank": 1,
      "twitter_handle": "besttrader",
      "display_name": "Best Trader",
      "composite_score": 95.2,
      "avg_return_pct": 0.95,
      "max_return_pct": 12.3,
      "sharpe_ratio": 2.31,
      "max_drawdown_pct": 5.7,
      "trade_count": 89
    }
    // ...
  ],
  "settlement": {"txHash": "0x...", "payer": "0x...", "network": "base"}
}

Dynamic pricing: $0.25 + ceil((limit - 100) / 4) × $0.01

POST /api/x402/search

Search traders by handle or name. $0.02 USDC flat.

// Request
{"query": "trader", "limit": 10}

// Response
{
  "results": [
    {
      "twitter_handle": "toptrader",
      "display_name": "Top Trader",
      "composite_score": 87.4,
      "rank": 3,
      "trade_count": 47,
      "qualified": true
    }
  ],
  "settlement": {"txHash": "0x...", ...}
}

MCP Tools

All nine tools are available via MCP at POST /mcp/. Some have REST equivalents:

MCP-Only Tools

trader_last_trade (Free)

Most recent trade and total trade count.

// MCP Request
{"twitter_handle": "toptrader"}

// Response
{
  "last_trade": {
    "action": "ENTER_LONG",
    "symbol": "AAPL",
    "asset_class": "EQUITY",
    "quantity": 100,
    "price": 185.50,
    "created_at": "2026-03-15T14:30:00Z"
  },
  "total_trades": 47
}

trader_cancel_last (Free)

Cancel the most recent trade. Only works within 5 minutes of submission.

// MCP Request
{"twitter_handle": "yourhandle"}

// Response (success)
{"cancelled": true, "trade": {"symbol": "AAPL", "action": "enter_long", "quantity": 100, "price": 185.50}}

// Response (expired)
{"error": true, "code": "CANCEL_WINDOW_EXPIRED", "message": "Cancel window (5 minutes) has passed."}

trader_watch (Free)

Add a trader to your watchlist. Saves the relationship for future use. Activity notifications for watched traders are planned but not yet available.

// MCP Request
{"twitter_handle": "yourhandle", "target_handle": "toptrader"}

// Response
{"watching": "@toptrader", "total_watching": 3, "note": "Watchlist saved. Activity notifications coming soon."}

trader_unwatch (Free)

Remove a trader from your watchlist.

// MCP Request
{"twitter_handle": "yourhandle", "target_handle": "toptrader"}

// Response
{"unwatched": "@toptrader"}

trader_get_trade_history (x402 -- $0.01 per 3 trades)

Complete trade log.

// MCP Request
{"twitter_handle": "toptrader", "limit": 0, "payment": "<base64 x402 signature>"}

// Response
{
  "trades": [
    {
      "action": "ENTER_LONG",
      "symbol": "AAPL",
      "asset_class": "EQUITY",
      "quantity": 100,
      "price": 185.50,
      "created_at": "2026-03-10T09:30:00Z"
    }
    // ...
  ],
  "settlement": {"txHash": "0x...", ...}
}

Rate Limits

Authentication