MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/account.py:88-127 (handler)

  The main handler function for the paradex_account_fills tool. It authenticates a Paradex client, fetches fills filtered by market and time range, validates the response using TypeAdapter(list[Fill]), and returns a structured dictionary with schema and results.
  @server.tool(name="paradex_account_fills") async def get_account_fills( market_id: Annotated[str, Field(description="Filter by market ID.")], 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 your executed trades to evaluate performance and execution quality. Use this tool when you need to: - Review your trading history across specific markets - Calculate your average entry price for multi-fill positions - Analyze execution quality compared to intended prices - Track realized PnL from completed trades - Verify order execution details for reconciliation Detailed fill information is essential for performance analysis and understanding how your orders were actually executed. Example use cases: - Calculating volume-weighted average price (VWAP) of your entries - Analyzing execution slippage from your intended prices - Reviewing trade history for tax or accounting purposes - Tracking commission costs across different markets - Identifying which of your strategies produced the best execution """ client = await get_authenticated_paradex_client() params = {"market": market_id, "start_at": start_unix_ms, "end_at": end_unix_ms} response = client.fetch_fills(params) if "error" in response: await ctx.error(response) raise Exception(response["error"]) fills = fill_adapter.validate_python(response["results"]) results = { "description": Fill.__doc__.strip() if Fill.__doc__ else None, "fields": Fill.model_json_schema(), "results": fills, } return results
• src/mcp_paradex/models.py:110-132 (schema)

  Pydantic BaseModel defining the structure and validation for Fill objects returned by the tool.
  class Fill(BaseModel): """Fill model representing a trade fill on Paradex.""" id: Annotated[str, Field(description="Unique string ID of fill per FillType")] side: Annotated[str, Field(description="Taker side")] liquidity: Annotated[str, Field(description="Maker or Taker")] market: Annotated[str, Field(description="Market name")] order_id: Annotated[str, Field(description="Order ID")] price: Annotated[float, Field(description="Price at which order was filled")] size: Annotated[float, Field(description="Size of the fill")] fee: Annotated[float, Field(description="Fee paid by the user")] fee_currency: Annotated[str, Field(description="Asset that fee is charged in")] created_at: Annotated[int, Field(description="Fill time")] remaining_size: Annotated[float, Field(description="Remaining size of the order")] client_id: Annotated[str, Field(description="Unique client assigned ID for the order")] fill_type: Annotated[str, Field(description="Fill type, can be FILL, LIQUIDATION or TRANSFER")] realized_pnl: Annotated[float, Field(description="Realized PnL of the fill")] realized_funding: Annotated[float, Field(description="Realized funding of the fill")] account: Annotated[str, Field(default="", description="Account that made the fill")] underlying_price: Annotated[ str, Field(default="", description="Underlying asset price of the fill (spot price)") ]
• src/mcp_paradex/tools/account.py:88-88 (registration)

  The @server.tool decorator registers the get_account_fills function as the MCP tool named paradex_account_fills.
  @server.tool(name="paradex_account_fills")
• src/mcp_paradex/tools/account.py:85-85 (schema)

  TypeAdapter for validating lists of Fill models in the tool response.
  fill_adapter = TypeAdapter(list[Fill])