MCP Paradex Server

Instructions

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

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])