# Install necessary libraries
# The `requests` library is required for making HTTP requests to the Hyperliquid REST API.
!pip install requests

# Import required libraries
# `pandas` is used for data manipulation and creating DataFrames.
import pandas as pd
# `requests` is used for sending HTTP requests.
import requests
# `datetime`, `timezone`, and `timedelta` are used for handling time-related operations.
from datetime import datetime, timezone, timedelta

# Define the API endpoint for Hyperliquid
# All public data queries are directed to this single REST endpoint.
API_ENDPOINT = "https://api.hyperliquid.xyz/info"

# Define the cryptocurrency symbol for data retrieval
# This represents the asset ticker without a quote-currency suffix (e.g., BTC, ETH).
SYMBOL = "BTC"

# Define the start datetime for data collection
# `datetime.now(timezone.utc)` gets the current UTC time.
# `.replace(second=0, microsecond=0)` normalizes the time to the nearest minute.
# `- timedelta(minutes=2)` sets the start time to 2 minutes before the current minute.
START_DATETIME = datetime.now(timezone.utc).replace(second=0, microsecond=0) - timedelta(minutes=30)

# Define the end datetime for data collection
# Sets the end time to 1 minute after the start time, defining a 1-minute window.
END_DATETIME = datetime.now(timezone.utc).replace(second=0, microsecond=0)   # Current minute

def fetch_ohlc(symbol, start_datetime, end_datetime):
    """
    Fetches OHLCV (Open, High, Low, Close, Volume) candle data for a specified symbol and time range.

    Parameters:
        symbol (str): The cryptocurrency ticker symbol (e.g., "BTC").
        start_datetime (datetime): The UTC datetime object representing the start of the data range.
        end_datetime (datetime): The UTC datetime object representing the end of the data range.

    Returns:
        pandas.DataFrame: A DataFrame containing the OHLCV data with columns for datetime, open, high, low, close, and volume.
                          Returns an empty DataFrame if no data is found or an error occurs.
    """

    # STEP 1: Convert datetime objects to Unix timestamps (milliseconds)
    # Unix timestamp = number of seconds since January 1, 1970 (UTC)
    # The Hyperliquid API requires timestamps in milliseconds, so we multiply by 1000
    start_ms = int(start_datetime.timestamp() * 1000)
    end_ms = int(end_datetime.timestamp() * 1000)

    # STEP 2: Build the request payload (data to send to the API)
    # The API expects a JSON object with a 'type' field and a 'req' field
    # 'type': "candleSnapshot" tells the API we want historical candle data
    # 'req': contains the specific parameters for our request
    payload = {
        "type": "candleSnapshot",
        "req": {
            "coin": symbol.upper(),  # Convert to uppercase (e.g., "btc" -> "BTC") as required by the API
            "interval": "1m",        # Request 1-minute interval candles (options: "1m", "5m", "15m", "1h", etc.)
            "startTime": start_ms,   # Start time in milliseconds
            "endTime": end_ms        # End time in milliseconds
        }
    }

    try:
        # STEP 3: Send the request to the Hyperliquid API
        # requests.post() sends an HTTP POST request to the specified URL
        # - API_ENDPOINT: the URL of the Hyperliquid API
        # - headers: tells the API we're sending JSON data
        # - json: automatically converts our payload dictionary to a JSON string
        # - timeout: maximum seconds to wait for a response (prevents hanging indefinitely)
        response = requests.post(
            API_ENDPOINT,
            headers={"Content-Type": "application/json"},
            json=payload,
            timeout=30,
        )

        # STEP 4: Check if the request was successful
        # raise_for_status() will raise an exception if the status code is 4xx or 5xx (client or server error)
        # 200 status code = success
        response.raise_for_status()

        # STEP 5: Parse the JSON response into a Python list of dictionaries
        # Each dictionary in the list represents one minute of candle data
        candles = response.json()

        # STEP 6: Check if we actually received any data
        if not candles:
            print(f"No candle data received for {symbol} from {start_datetime} to {end_datetime}.")
            # Return an empty DataFrame with the correct column structure
            return pd.DataFrame(columns=["datetime", "open", "high", "low", "close", "volume"])

        # STEP 7: Extract data from ALL candles (not just the first one!)
        # We'll loop through each candle in the response and create a row for it
        # This ensures we get ALL minutes of data, not just the first minute

        data_rows = []  # Empty list to store each candle's data

        for candle in candles:  # Loop through every candle returned by the API
            # Extract the 6 values we need from each candle dictionary
            # Keys in the API response:
            # 't' = timestamp (milliseconds)
            # 'o' = open price
            # 'h' = high price
            # 'l' = low price
            # 'c' = close price
            # 'v' = volume traded
            row = [
                pd.to_datetime(int(candle["t"]), unit='ms', utc=True),  # Convert millisecond timestamp to readable datetime
                float(candle["o"]),  # Convert string/float to Python float
                float(candle["h"]),
                float(candle["l"]),
                float(candle["c"]),
                float(candle["v"])
            ]
            data_rows.append(row)  # Add this candle's data to our list

        # STEP 8: Create a Pandas DataFrame from all the data rows
        # pd.DataFrame converts our list of rows into a table with the specified column names
        df = pd.DataFrame(data_rows, columns=["datetime", "open", "high", "low", "close", "volume"])

        # STEP 9: Explicitly set correct data types for each column
        # This ensures consistency and prevents errors in later calculations
        # - datetime64[ns, UTC]: timezone-aware datetime with nanosecond precision
        # - float64: decimal numbers (for price and volume calculations)
        df = df.astype({
            "datetime": "datetime64[ns, UTC]",
            "open": "float64",
            "high": "float64",
            "low": "float64",
            "close": "float64",
            "volume": "float64"
        })

        # STEP 10: Return the complete DataFrame with all candles
        # The columns are returned in a logical order for easy viewing
        return df[["datetime", "open", "high", "low", "close", "volume"]]

    # STEP 11: Error handling - catch specific types of request errors
    # These help debug what went wrong if the API call fails

    except requests.exceptions.HTTPError as http_err:
        # HTTP errors: 404 (Not Found), 401 (Unauthorized), 500 (Server Error), etc.
        print(f"HTTP error occurred: {http_err}")

    except requests.exceptions.ConnectionError as conn_err:
        # Connection errors: network issues, API server down, wrong URL, etc.
        print(f"Connection error occurred: {conn_err}")

    except requests.exceptions.Timeout as timeout_err:
        # Timeout errors: API took too long to respond (more than 30 seconds)
        print(f"Request timed out: {timeout_err}")

    except requests.exceptions.RequestException as req_err:
        # Catch-all for any other request-related exceptions
        print(f"An error occurred during the request: {req_err}")

    except Exception as e:
        # Catch any unexpected errors (e.g., data parsing issues, memory errors)
        print(f"An unexpected error occurred: {e}")

    # If we reach this point, an error occurred above
    # Return an empty DataFrame so the rest of the code doesn't break
    return pd.DataFrame(columns=["datetime", "open", "high", "low", "close", "volume"])

# Execute the data fetching function
# The `fetch_ohlc` function is called with the defined SYMBOL, START_DATETIME, and END_DATETIME.
# The returned DataFrame, containing the OHLCV data, is assigned to the variable `df`.
df = fetch_ohlc(SYMBOL, START_DATETIME, END_DATETIME)

# Display the first few rows of the fetched OHLCV data
# `display(df.head())` shows the header and the initial entries of the DataFrame.
print("--- Fetched OHLCV Data ---")
display(df.head())

# Print a summary of the DataFrame's schema and data types
# `df.info()` provides a concise summary, including the index dtype, column dtypes, non-null values, and memory usage.
print("\n--- Schema Summary ---")
df.info()

# Import the necessary library for plotting
# `matplotlib.pyplot` is a widely used library for creating static, animated, and interactive visualizations in Python.
import matplotlib.pyplot as plt

# Purpose: To visualize the closing price of the fetched OHLCV data.
# What the code does: It generates a line plot of the 'close' price over 'datetime'.
# Input: The Pandas DataFrame `df` containing OHLCV data.
# Output: A line plot displayed within the notebook.
# Why this step is important: Visualizing data helps in quick comprehension of market movements and data validity.

# Check if the DataFrame is not empty before attempting to plot
if not df.empty:
    # Create a figure and a set of subplots for the plot
    fig, ax = plt.subplots(figsize=(10, 6))

    # Plot the 'close' price against the 'datetime' column
    ax.plot(df['datetime'], df['close'], marker='o', linestyle='-', color='blue')

    # Set the title of the plot
    ax.set_title(f'Closing Price for {SYMBOL} (1-Minute Candle)', fontsize=14)

    # Set the label for the x-axis
    ax.set_xlabel('Datetime (UTC)', fontsize=12)

    # Set the label for the y-axis
    ax.set_ylabel('Close Price', fontsize=12)

    # Enable grid for better readability of data points
    ax.grid(True, linestyle='--', alpha=0.7)

    # Rotate x-axis labels for better visibility if they overlap
    plt.xticks(rotation=45, ha='right')

    # Adjust layout to prevent labels from being cut off
    plt.tight_layout()

    # Display the plot
    plt.show()
else:
    # Inform the user if no data is available for plotting
    print("No data available to plot.")

# Import the necessary library for plotting
# `matplotlib.pyplot` is a widely used library for creating static, animated, and interactive visualizations in Python.
import matplotlib.pyplot as plt

# Purpose: To visualize the closing price of the fetched OHLCV data.
# What the code does: It generates a line plot of the 'close' price over 'datetime'.
# Input: The Pandas DataFrame `df` containing OHLCV data.
# Output: A line plot displayed within the notebook.
# Why this step is important: Visualizing data helps in quick comprehension of market movements and data validity.

# Check if the DataFrame is not empty before attempting to plot
if not df.empty:
    # Create a figure and a set of subplots for the plot
    fig, ax = plt.subplots(figsize=(10, 6))

    # Plot the 'close' price against the 'datetime' column
    ax.plot(df['datetime'], df['close'], marker='o', linestyle='-', color='blue')

    # Set the title of the plot
    ax.set_title(f'Closing Price for {SYMBOL} (1-Minute Candle)', fontsize=14)

    # Set the label for the x-axis
    ax.set_xlabel('Datetime (UTC)', fontsize=12)

    # Set the label for the y-axis
    ax.set_ylabel('Close Price', fontsize=12)

    # Enable grid for better readability of data points
    ax.grid(True, linestyle='--', alpha=0.7)

    # Rotate x-axis labels for better visibility if they overlap
    plt.xticks(rotation=45, ha='right')

    # Adjust layout to prevent labels from being cut off
    plt.tight_layout()

    # Display the plot
    plt.show()
else:
    # Inform the user if no data is available for plotting
    print("No data available to plot.")