import requests
import pandas as pd

# Install required libraries: requests for HTTP communication, pandas for data manipulation, and mplfinance for plotting.
%pip install requests pandas mplfinance

import warnings
from datetime import datetime, timezone

# Ignore non-critical runtime warnings to maintain clean output.
warnings.filterwarnings("ignore")

# The requests library handles HTTP communication with the OKX public REST endpoint.
import requests
# The pandas library provides the DataFrame structure for tabular OHLCV data.
import pandas as pd
# datetime and timezone modules supply UTC-aware datetime objects for millisecond timestamp derivation.
from datetime import datetime, timezone

# Define the OKX instrument identifier. Format: {BASE}-{QUOTE}-SWAP for perpetual futures; {BASE}-{QUOTE} for spot.
SYMBOL = "BTC-USDT-SWAP"

# Define the UTC-aware datetime marking the start of the retrieval window.
START_DATETIME = datetime(2024, 1, 1, tzinfo=timezone.utc)

# Define the number of candles to retrieve per API call. The OKX history-candles endpoint supports a maximum of 100 per request.
LIMIT = 5

# Define the public OKX historical candles endpoint. No API key is required for this endpoint.
BASE_URL = "https://www.okx.com/api/v5/market/history-candles"

def fetch_ohlc(symbol, start_datetime, limit):
    """
    Fetches OHLCV (Open, High, Low, Close, Volume) data from the OKX API.

    Input:
    - `symbol` (str): The instrument ID (e.g., "BTC-USDT-SWAP").
    - `start_datetime` (datetime): UTC-aware datetime indicating the start of the data retrieval window.
    - `limit` (int): The number of candles to retrieve (maximum 100).

    Output:
    - `pandas.DataFrame`: A DataFrame containing the OHLCV data, or an empty DataFrame if no data is returned.

    Logic:
    1. Converts the `start_datetime` to a Unix millisecond timestamp, as required by the OKX API.
    2. Constructs request parameters including the instrument ID, bar interval, limit, and cursor for pagination.
    3. Sends an HTTP GET request to the OKX `history-candles` endpoint.
    4. Raises an HTTPError for non-2xx responses.
    5. Extracts candle data from the JSON response.
    6. If data exists, it constructs a pandas DataFrame with specified columns.
    7. Converts the 'timestamp' column to UTC-aware datetime objects and renames it to 'datetime'.
    8. Casts OHLCV columns to float64 for numerical precision.
    9. Sorts the DataFrame by the 'datetime' column in ascending order.
    """
    # Convert the UTC datetime to a Unix millisecond integer, as required by the OKX `after` cursor parameter.
    after_ms = int(start_datetime.timestamp() * 1000)

    # Define parameters for the API request.
    params = {
        "instId": symbol,
        "bar":    "1m",  # Specifies the 1-minute candlestick interval.
        "limit":  limit,
        "after":  str(after_ms), # OKX cursor-based pagination parameter — returns candles with timestamps strictly after the specified value.
    }

    # Send the HTTP GET request to the OKX API.
    response = requests.get(BASE_URL, params=params, timeout=30)
    # Raise an HTTPError on any non-2xx response code, ensuring silent failures are surfaced immediately.
    response.raise_for_status()
    # Extract the candle array from the OKX response envelope; defaults to an empty list if the key is absent.
    data = response.json().get("data", [])

    # Return an empty DataFrame if no data is received.
    if not data:
        return pd.DataFrame()

    # Construct a structured DataFrame from the raw indexed-list response. OKX returns each candle as a positional list.
    df = pd.DataFrame(data, columns=[
        "timestamp", "open", "high", "low", "close", "volume",
        "volCcy", "volCcyQuote", "confirm"
    ])
    # Discard auxiliary columns (`volCcy`, `volCcyQuote`, `confirm`) not required for OHLCV analysis.
    df = df[["timestamp", "open", "high", "low", "close", "volume"]]

    # Convert the Unix millisecond timestamp to a UTC-aware datetime object.
    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms", utc=True)
    # Rename the `timestamp` column to `datetime` for clarity.
    df = df.rename(columns={"timestamp": "datetime"})

    # Cast all string-encoded API values to numeric types required for arithmetic computation.
    df = df.astype({
        "open":      "float64",
        "high":      "float64",
        "low":       "float64",
        "close":     "float64",
        "volume":    "float64",
    })

    # Ensure chronological ordering of the output DataFrame by the `datetime` column.
    return df.sort_values("datetime", ignore_index=True)

# Execute a single API call using the globally defined configuration parameters
# and store the returned OHLCV data in a pandas DataFrame.
df = fetch_ohlc(SYMBOL, START_DATETIME, LIMIT)

print("--- Fetched OHLCV Data Head ---")
# Display the first few rows of the DataFrame to inspect the data.
display(df.head())

print("\n--- Schema Summary ---")
# Print a concise summary of the DataFrame, including data types and non-null values.
df.info()

import matplotlib.pyplot as plt
import mplfinance as mpf

def plot_ohlc(df, symbol):
    """
    Plots an OHLCV candlestick chart for the given DataFrame.

    Input:
    - `df` (pandas.DataFrame): DataFrame containing OHLCV data with a 'datetime' index.
    - `symbol` (str): The instrument ID for the chart title.
    """
    # Set 'datetime' as the index for mplfinance
    df_plot = df.set_index('datetime')

    fig, axlist = mpf.plot(df_plot,
                            type='candle',
                            volume=True,
                            title=f"{symbol} OHLCV Candlestick Chart",
                            ylabel='Price',
                            ylabel_lower='Volume',
                            style='yahoo',
                            returnfig=True)
    plt.show()

# Visualize the fetched OHLCV data
plot_ohlc(df, SYMBOL)