MCP Paradex Server

Instructions

Monitor active trading positions to track performance and manage risk.

Use this tool when you need to:
- Get a complete view of all open positions for a vault
- Monitor unrealized P&L across all positions
- Check liquidation prices and margin requirements
- Assess position sizing and leverage across markets
- Track entry prices and position duration

Position monitoring is fundamental to risk management and provides
the necessary information for trade management decisions.

Example use cases:
- Checking the current status of all open trades
- Monitoring unrealized profit/loss across positions
- Assessing liquidation risk during market volatility
- Comparing performance across different markets
- Planning adjustments to position sizes or leverage

Implementation Reference

• src/mcp_paradex/tools/vaults.py:280-313 (handler)

  The main handler function decorated with @server.tool(name="paradex_vault_positions"). It fetches vault positions from the Paradex API using get_paradex_client and api_call, validates with position_adapter, and returns the list of Position objects.

  @server.tool(name="paradex_vault_positions")
  async def get_vault_positions(
      vault_address: Annotated[
          str, Field(description="The address of the vault to get positions for.")
      ],
  ) -> list[Position]:
      """
      Monitor active trading positions to track performance and manage risk.
  
      Use this tool when you need to:
      - Get a complete view of all open positions for a vault
      - Monitor unrealized P&L across all positions
      - Check liquidation prices and margin requirements
      - Assess position sizing and leverage across markets
      - Track entry prices and position duration
  
      Position monitoring is fundamental to risk management and provides
      the necessary information for trade management decisions.
  
      Example use cases:
      - Checking the current status of all open trades
      - Monitoring unrealized profit/loss across positions
      - Assessing liquidation risk during market volatility
      - Comparing performance across different markets
      - Planning adjustments to position sizes or leverage
      """
      try:
          client = await get_paradex_client()
          response = await api_call(client, "vaults/positions", params={"address": vault_address})
          positions = position_adapter.validate_python(response["results"])
          return positions
      except Exception as e:
          logger.error(f"Error fetching positions for vault {vault_address}: {e!s}")
          raise e

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

  Pydantic BaseModel defining the schema for individual Position objects returned by the tool. Used in position_adapter for list validation.

  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/tools/vaults.py:280-280 (registration)

  The @server.tool decorator registers the get_vault_positions function as the MCP tool named 'paradex_vault_positions'.

  @server.tool(name="paradex_vault_positions")