MCP Paradex Server

Instructions

Analyze your open positions to monitor exposure, profitability, and risk.

Use this tool when you need to:
- Check the status and P&L of all your open positions
- Monitor your liquidation prices and margin requirements
- Assess your exposure across different markets
- Make decisions about position management (scaling, hedging, closing)

Understanding your current positions is fundamental to proper risk management
and is the starting point for many trading decisions.

Example use cases:
- Checking the unrealized P&L of your positions
- Monitoring liquidation prices during market volatility
- Assessing total exposure across related assets
- Verifying entry prices and position sizes

Implementation Reference

• src/mcp_paradex/tools/account.py:50-82 (handler)

  The core handler function for the paradex_account_positions tool. It fetches the user's account positions using the authenticated Paradex client, validates the response with Pydantic, and returns a formatted result including the schema and positions data.

  @server.tool(name="paradex_account_positions")
  async def get_account_positions(ctx: Context) -> dict:
      """
      Analyze your open positions to monitor exposure, profitability, and risk.
  
      Use this tool when you need to:
      - Check the status and P&L of all your open positions
      - Monitor your liquidation prices and margin requirements
      - Assess your exposure across different markets
      - Make decisions about position management (scaling, hedging, closing)
  
      Understanding your current positions is fundamental to proper risk management
      and is the starting point for many trading decisions.
  
      Example use cases:
      - Checking the unrealized P&L of your positions
      - Monitoring liquidation prices during market volatility
      - Assessing total exposure across related assets
      - Verifying entry prices and position sizes
      """
      client = await get_authenticated_paradex_client()
      response = client.fetch_positions()
      if "error" in response:
          await ctx.error(response)
          raise Exception(response["error"])
      positions = position_adapter.validate_python(response["results"])
  
      results = {
          "description": Position.__doc__.strip() if Position.__doc__ else None,
          "fields": Position.model_json_schema(),
          "results": positions,
      }
      return results

• src/mcp_paradex/models.py:52-107 (schema)

  Pydantic model defining the Position structure, used for validating the positions list returned by the Paradex API and generating the JSON schema in the tool response.

  class Position(BaseModel):
      """Position model representing a trading position on Paradex."""
  
      id: Annotated[str, Field(description="Unique string ID for the position")]
      account: Annotated[str, Field(description="Account ID of the position")]
      market: Annotated[str, Field(description="Market for position")]
      status: Annotated[
          str, Field(description="Status of Position : Open or Closed", enum=["OPEN", "CLOSED"])
      ]
      side: Annotated[str, Field(description="Position Side : Long or Short", enum=["SHORT", "LONG"])]
      size: Annotated[
          float,
          Field(description="Size of the position with sign (positive if long or negative if short)"),
      ]
      average_entry_price: Annotated[float, Field(description="Average entry price")]
      average_entry_price_usd: Annotated[float, Field(description="Average entry price in USD")]
      average_exit_price: Annotated[float, Field(description="Average exit price")]
      unrealized_pnl: Annotated[
          float, Field(description="Unrealized P&L of the position in the quote asset")
      ]
      unrealized_funding_pnl: Annotated[
          float, Field(description="Unrealized running funding P&L for the position")
      ]
      cost: Annotated[float, Field(description="Position cost")]
      cost_usd: Annotated[float, Field(description="Position cost in USD")]
      cached_funding_index: Annotated[float, Field(description="Position cached funding index")]
      last_updated_at: Annotated[int, Field(description="Position last update time")]
      last_fill_id: Annotated[
          str, Field(description="Last fill ID to which the position is referring")
      ]
      seq_no: Annotated[
          int,
          Field(
              description="Unique increasing number (non-sequential) that is assigned to this position update. Can be used to deduplicate multiple feeds"
          ),
      ]
      liquidation_price: Annotated[
          str, Field(default="", description="Liquidation price of the position")
      ]
      leverage: Annotated[float, Field(default=0, description="Leverage of the position")]
      realized_positional_pnl: Annotated[
          float,
          Field(
              default=0,
              description="Realized PnL including both positional PnL and funding payments. Reset to 0 when position is closed or flipped.",
          ),
      ]
      created_at: Annotated[int, Field(default=0, description="Position creation time")]
      closed_at: Annotated[int, Field(default=0, description="Position closed time")]
      realized_positional_funding_pnl: Annotated[
          str,
          Field(
              default="",
              description="Realized Funding PnL for the position. Reset to 0 when position is closed or flipped.",
          ),
      ]

• src/mcp_paradex/server/server.py:52-52 (registration)

  Import of the tools module, which loads and registers all tool handlers via their @server.tool decorators, including paradex_account_positions.

  from mcp_paradex.tools import *

• src/mcp_paradex/tools/account.py:47-47 (helper)

  Pydantic TypeAdapter used to validate the list of positions from the API response.

  position_adapter = TypeAdapter(list[Position])

• src/mcp_paradex/utils/paradex_client.py:68-81 (helper)

  Helper function to obtain the authenticated ParadexApiClient instance, called by the tool handler.

  async def get_authenticated_paradex_client() -> ParadexApiClient:
      """
      Get or initialize the authenticated Paradex client.
  
      Returns:
          Paradex: The initialized Paradex client.
  
      Raises:
          ValueError: If the required configuration is not set.
      """
      client = await get_paradex_client()
      if client.account is None:
          raise ValueError("Paradex client is not authenticated")
      return client