MCP Paradex Server

Instructions

Implementation Reference

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

  Handler function for the 'paradex_trades' tool. Fetches recent trades for a given market within a specified time range using the Paradex client API. Validates response with TypeAdapter(list[Trade]) and returns formatted results including schema.
  @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 BaseModel defining the Trade schema used for input/output validation of trade data in the paradex_trades tool response.
  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:433-433 (registration)

  Registration of the paradex_trades tool using the @server.tool decorator.
  @server.tool(name="paradex_trades")
• src/mcp_paradex/tools/market.py:430-430 (helper)

  TypeAdapter for list[Trade] used to validate the API response data in the handler.
  trade_adapter = TypeAdapter(list[Trade])