MCP Paradex Server

Instructions

Implementation Reference

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

  The main handler function for the 'paradex_vault_positions' tool. It takes a vault_address parameter, fetches positions via the Paradex API endpoint 'vaults/positions', validates the results using position_adapter (TypeAdapter(list[Position])), and returns the list of Position objects. Includes comprehensive documentation on usage.
  @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 schema (BaseModel) for Position objects, which defines the output structure of the paradex_vault_positions tool. Used by position_adapter for 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")
• src/mcp_paradex/tools/vaults.py:277-278 (helper)

  TypeAdapter for list[Position] used to validate API responses in the handler.
  position_adapter = TypeAdapter(list[Position])