MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/market.py:433-477 (handler)

  The handler function for the 'paradex_trades' tool. It fetches trade data from the Paradex API for a given market and time range, validates it using the Trade model, and returns a structured response including schema and results.
  @server.tool(name="paradex_trades") async def get_trades( market_id: Annotated[str, Field(description="Market symbol to get trades for.")], start_unix_ms: Annotated[int, Field(description="Start time in unix milliseconds.")], end_unix_ms: Annotated[int, Field(description="End time in unix milliseconds.")], ctx: Context = None, ) -> dict: """ Analyze actual market transactions to understand market sentiment and liquidity. Use this tool when you need to: - Detect large trades that might signal institutional activity - Calculate average trade size during specific periods - Identify buy/sell pressure imbalances - Monitor execution prices vs. order book prices - Understand market momentum through trade flow Trade data provides insights into actual market activity versus just orders, helping you understand how other participants are behaving. Example use cases: - Detecting large "whale" transactions that might influence price - Analyzing trade sizes to gauge market participation - Identifying periods of aggressive buying or selling - Understanding trade frequency as an indicator of market interest - Comparing executed prices to orderbook mid-price for market impact analysis """ try: # Get trades from Paradex client = await get_paradex_client() response = client.fetch_trades( params={"market": market_id, "start_at": start_unix_ms, "end_at": end_unix_ms} ) if "error" in response: raise Exception(response["error"]) trades = trade_adapter.validate_python(response["results"]) results = { "description": Trade.__doc__.strip() if Trade.__doc__ else None, "fields": Trade.model_json_schema(), "results": trades, } return results except Exception as e: await ctx.error(f"Error fetching trades for {market_id}: {e!s}") raise e
• src/mcp_paradex/models.py:37-49 (schema)

  Pydantic model 'Trade' that defines the schema and validation for individual trade objects returned by the paradex_trades tool.
  class Trade(BaseModel): """Trade model representing a completed trade on Paradex.""" id: Annotated[str, Field(description="Unique Trade ID per TradeType")] market: Annotated[str, Field(description="Market for which trade was done")] side: Annotated[str, Field(description="Taker side")] size: Annotated[float, Field(description="Trade size")] price: Annotated[float, Field(description="Trade price")] created_at: Annotated[ int, Field(description="Unix Millisecond timestamp at which trade was done") ] trade_type: Annotated[str, Field(description="Trade type, can be FILL or LIQUIDATION")]
• src/mcp_paradex/tools/market.py:430-431 (helper)

  TypeAdapter used to validate lists of Trade objects from the API response in the paradex_trades handler.
  trade_adapter = TypeAdapter(list[Trade])
• src/mcp_paradex/tools/market.py:433-433 (registration)

  The @server.tool decorator that registers the get_trades function as the 'paradex_trades' MCP tool.
  @server.tool(name="paradex_trades")