{"openapi":"3.1.0","info":{"title":"MangroveTrader","description":"Agent-native trading performance tracker with x402 payments and MCP tools.\n\n## For Agents\n\n- **REST discovery**: GET `/openapi.json` for the full OpenAPI 3.0 spec\n- **MCP tool catalog**: GET `/api/v1/docs/tools` for tool names, parameters, access tiers, and pricing\n- **MCP endpoint**: Connect to `/mcp` via Streamable HTTP transport\n\n## Access Tiers\n\n| Tier | How to access |\n|------|---------------|\n| Free | No credentials needed |\n| Auth | `X-API-Key` header |\n| x402 | Payment via x402 protocol (or API key for free access) |\n","version":"0.1.0"},"paths":{"/api/v1/docs/tools":{"get":{"tags":["discovery"],"summary":"MCP tool catalog","description":"Lists all registered MCP tools with their access tier, parameters, and pricing. Agents should call this before connecting via MCP to discover what tools are available and what each one costs.","operationId":"tool_catalog_api_v1_docs_tools_get","responses":{"200":{"description":"List of MCP tools with metadata","content":{"application/json":{"schema":{}}}}}}},"/api/v1/leaderboard":{"get":{"tags":["leaderboard"],"summary":"Live leaderboard (free, public)","description":"Top 20 traders by composite score. Backed by Redis cache (5-min TTL) with live DB fallback.","operationId":"rest_leaderboard_free_api_v1_leaderboard_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/trader/my_stats":{"post":{"tags":["trader"],"summary":"Rest My Stats","operationId":"rest_my_stats_api_v1_trader_my_stats_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/trader/performance_report":{"post":{"tags":["trader"],"summary":"Rest Performance Report","operationId":"rest_performance_report_api_v1_trader_performance_report_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/trader/last_trade":{"post":{"tags":["trader"],"summary":"Rest Last Trade","operationId":"rest_last_trade_api_v1_trader_last_trade_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/trader/trade_history":{"post":{"tags":["trader"],"summary":"Own trade history (free)","description":"Free trade history for your own account. requester_handle must match twitter_handle. For other traders' history, use /api/x402/trade_history.","operationId":"rest_own_trade_history_api_v1_trader_trade_history_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/x402/leaderboard":{"post":{"tags":["x402"],"summary":"Trader leaderboard (x402-gated)","description":"Top 500 leaderboard rankings. $0.25 USDC on Base. Max 500 rows via REST. API key holders get free access. Payment handled by x402 middleware.","operationId":"rest_leaderboard_api_x402_leaderboard_post","responses":{"200":{"description":"Leaderboard data (authenticated or paid)","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required -- includes x402 payment options"}}}},"/api/x402/search":{"post":{"tags":["x402"],"summary":"Search trader (x402-gated)","description":"Search for a trader by handle. Costs $0.02 USDC on Base. API key holders get free access. Returns 402 with payment requirements if no credentials are provided. Payment handled by x402 middleware.","operationId":"rest_search_trader_api_x402_search_post","responses":{"200":{"description":"Search results (authenticated or paid)","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required -- includes x402 payment options"}}}},"/api/x402/trade_history":{"post":{"tags":["x402"],"summary":"Trade history (x402-gated, dynamic pricing)","description":"Full trade history for a trader. Dynamic pricing: $0.01 per 3 trades (USDC on Base). Payment is handled at the tool level, NOT by the Coinbase x402 middleware. Pass the x402 payment signature in the X-Payment header. API key holders get free access via X-API-Key header.","operationId":"rest_trade_history_api_x402_trade_history_post","responses":{"200":{"description":"Trade history data (authenticated or paid)","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required -- includes x402 payment options"}}}},"/api/v1/auth/twitter/login":{"get":{"tags":["auth"],"summary":"Start X OAuth 2.0 login","description":"Redirects to X authorization page. After login, X redirects to the callback which issues a MangroveTrader session token. Set it as MT_AUTH_TOKEN.","operationId":"twitter_login_api_v1_auth_twitter_login_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["discovery"],"summary":"Health check","description":"Returns service health, Redis connectivity, and worker heartbeat. Free, no auth required.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"tags":[{"name":"discovery","description":"API and tool discovery endpoints (free, no auth)"},{"name":"x402","description":"x402 payment-gated endpoints"}]}