API Reference

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

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

Authentication

Several endpoints require an auth_token — a session token tied to your verified X identity. Get one via the OAuth flow:

# Step 1: open this URL in your browser
GET https://api.mangrovetraders.com/api/v1/auth/twitter/login

# → redirects to X authorization page
# → after you approve, X redirects to the callback
# → callback page displays your MT_AUTH_TOKEN

# Step 2: use the token in requests
{"auth_token": "mtk_..."}

Session tokens are valid for 30 days.

Free Endpoints

POST /api/v1/trader/my_stats

Get your score, rank, and open positions. Requires an auth_token.

// Request
{"auth_token": "mtk_..."}

// 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. Requires an auth_token.

// Request
{"auth_token": "mtk_...", "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}
}

POST /api/v1/trader/last_trade

Most recent trade and total trade count for any trader. No auth required.

// 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
}

POST /api/v1/trader/trade_history

Your own trade history, free. Requires an auth_token matching the requested handle. For other traders' history, use the x402 endpoint below.

// Request (preferred — auth_token identifies you)
{"auth_token": "mtk_...", "twitter_handle": "toptrader", "limit": 20}

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

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)
{
  "timeframe": "all_time",
  "count": 100,
  "total_traders": 312,
  "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
    }
    // ...
  ]
}

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
{"twitter_handle": "toptrader", "limit": 10}

// Response
{
  "query": "toptrader",
  "count": 1,
  "results": [
    {
      "twitter_handle": "toptrader",
      "display_name": "Top Trader",
      "composite_score": 87.4,
      "rank": 3,
      "trade_count": 47,
      "qualified": true
    }
  ]
}

POST /api/x402/trade_history

Trade history for any trader. $0.01 per 3 trades (dynamic). Pass the x402 payment signature in the X-Payment header.

// Request
{"twitter_handle": "toptrader", "limit": 0}
// Header: X-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"
    }
    // ...
  ]
}

MCP Tools

All tools are available via MCP at POST /mcp/. REST equivalents where they exist:

MCP-Only Tools

trader_cancel_last (Free)

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

// MCP Request
{"auth_token": "mtk_..."}

// 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. Activity notifications for watched traders are planned but not yet available.

// MCP Request
{"auth_token": "mtk_...", "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
{"auth_token": "mtk_...", "target_handle": "toptrader"}

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

Rate Limits