Python Client API

The Quantdle Python Client is a user-friendly library that simplifies downloading financial market data from Quantdle. This client handles all the complexity of data downloading, extraction, and processing, giving you clean, ready-to-use pandas or polars DataFrames.

Why Use the Python Client?

Simple Data Access

Download historical market data with just a few lines of code.

High Performance

Parallel downloads and smart chunking for faster data retrieval.

Multiple Formats

Support for both pandas and polars DataFrames.

Zero Configuration

Works out of the box with minimal setup.

Installation

Install the Quantdle Python client using pip:

Standard Installation

pip install quantdle

With Polars Support

pip install quantdle[polars]

Python Version Requirements

The Quantdle Python client requires Python 3.9 or higher. Make sure your Python version is compatible before installing.

You can check it in the project page of pypi.org/project/quantdle/.

Getting Your API Credentials

Before using the Python client, you’ll need to obtain your API credentials from the Quantdle dashboard.

1. Log into your Quantdle account
2. Navigate to the API Keys section in your dashboard
3. Click “Generate API Keys” to create your credentials
4. Copy both your API Key and API Key ID - you’ll need both for authentication

Need Help with API Keys?

For detailed instructions on generating API keys, check out our API Keys guide.

Quick Start

Here’s how to get started with the Quantdle Python client in just a few lines of code:

import quantdle as qdl

# Initialize the client with your API credentials
client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Download data for EURUSD
df = client.download_data(
    symbol="EURUSD",
    timeframe="H1",
    start_date="2023-01-01",
    end_date="2023-12-31"
)

# Display the first few rows
print(df.head())

Data Format

By default, the client returns data as a pandas DataFrame. You can also request polars DataFrames by setting output_format="polars" in the download_data() method.

Basic Usage Examples

Download Different Symbols and Timeframes

import quantdle as qdl

# Initialize client once
client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Download different symbols and timeframes
xau_data = client.download_data("XAUUSD", "D1", "2023-01-01", "2023-12-31")
eur_data = client.download_data("EURUSD", "H1", "2023-01-01", "2023-01-31")

Using Polars DataFrames

For large datasets, polars DataFrames offer better performance and memory efficiency:

import quantdle as qdl

client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Get data as a polars DataFrame
df = client.download_data(
    symbol="XAUUSD",
    timeframe="D1",
    start_date="2023-01-01",
    end_date="2023-12-31",
    output_format="polars"
)

print(f"Data shape: {df.shape}")
print(df.head())

Discover Available Symbols

Before downloading data, you can check which symbols are available for your account:

import quantdle as qdl

client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Get all available symbols for your account
symbols = client.get_available_symbols()
print(f"Available symbols: {symbols}")

# Get information about a specific symbol
info = client.get_symbol_info("EURUSD")
print(f"EURUSD available from {info['available_from']} to {info['available_to']}")

Advanced Features

Handling Large Date Ranges

The client automatically handles large date ranges by splitting them into smaller chunks to avoid timeouts:

import quantdle as qdl

client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Download 10 years of data - will be automatically chunked
df = client.download_data(
    symbol="EURUSD",
    timeframe="H1",
    start_date="2014-01-01",
    end_date="2023-12-31",
    chunk_size_years=5  # Download in 5-year chunks
)

Performance Optimization

Customize download behavior for optimal performance:

import quantdle as qdl

client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

# Customize download behavior
df = client.download_data(
    symbol="EURUSD",
    timeframe="M5",
    start_date="2023-01-01",
    end_date="2023-12-31",
    max_workers=8,           # Increase parallel downloads
    show_progress=True,      # Show progress bars
    chunk_size_years=3       # Smaller chunks for more frequent updates
)

Performance Tips

• Use parallel downloads: The max_workers parameter controls concurrent downloads
• Choose appropriate chunk sizes: Larger chunks mean fewer API calls but longer wait times
• Cache downloaded data: Save DataFrames locally to avoid re-downloading
• Use polars for large datasets: More memory-efficient for datasets >1GB

Available Timeframes

The Quantdle API supports the following timeframes:

Timeframe	Description
M1	1 minute
M5	5 minutes
M15	15 minutes
M30	30 minutes
H1	1 hour
H4	4 hours
D1	1 day

Timeframe Selection

Choose your timeframe based on your analysis needs. Higher frequency data (M1, M5) provides more granular analysis but larger datasets, while daily data (D1) is suitable for longer-term analysis.

DataFrame Structure

The returned DataFrame contains the following columns:

Column	Type	Description
timestamp	datetime	Bar timestamp
open	float	Opening price
high	float	Highest price
low	float	Lowest price
close	float	Closing price
tickvol	int	Tick volume (number of new ticks)
volume	int	Trading volume
spread	int	Average spread of the bar
spreadmax	int	Maximum spread of the bar
spread_open	int	Opening spread of the bar

Spread data characteristics

All spread data is captured in tick resolution. So the spread column is the average spread of all ticks in the bar, the spreadmax column is the maximum spread of those ticks, and the spread_open column is the spread present in the first tick of the bar.

Example DataFrame Output

# Sample output structure
                    timestamp     open     high      low    close  tickvol     volume  spread  spreadmax  spreadopen
0  2023-06-30 15:34:00         1.08840  1.08867  1.08829  1.08861      389  369332000       4          7           2
1  2023-06-30 15:35:00         1.08862  1.08874  1.08849  1.08854      302  318511000       4          7           4
2  2023-06-30 15:36:00         1.08859  1.08880  1.08844  1.08851      281  339198000       3          7           1
3  2023-06-30 15:37:00         1.08851  1.08898  1.08849  1.08881      253  328819000       3          6           3
...

Error Handling

The client includes robust error handling for common scenarios:

import quantdle as qdl

client = qdl.Client(
    api_key="your-api-key",
    api_key_id="your-api-key-id"
)

try:
    df = client.download_data(
        symbol="INVALID_SYMBOL",
        timeframe="H1",
        start_date="2023-01-01",
        end_date="2023-12-31"
    )
except ValueError as e:
    print(f"Invalid parameter: {e}")
except ConnectionError as e:
    print(f"Network error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Common Error Scenarios

• Invalid symbol: Check available symbols using get_available_symbols().
• Date range issues: Ensure start_date is before end_date and within available data range.
• Network timeouts: The client automatically retries, but check your internet connection.
• API rate limits: The client handles chunking, but be mindful of making too many concurrent requests.

Best Practices

1. Reuse Client Instances

Create the client once and reuse it for multiple downloads:

# Good: Create client once
client = qdl.Client(api_key="...", api_key_id="...")

# Download multiple datasets
eurusd = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")
gbpusd = client.download_data("GBPUSD", "H1", "2023-01-01", "2023-12-31")

# Bad: Creating new client for each download
# This is inefficient and may hit rate limits

2. Cache Downloaded Data

Save large datasets locally to avoid re-downloading:

import quantdle as qdl
import pandas as pd

client = qdl.Client(api_key="...", api_key_id="...")

# Download and save to file
df = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")
df.to_parquet("eurusd_h1_2023.parquet")  # Efficient binary format

# Later, load from file instead of re-downloading
df = pd.read_parquet("eurusd_h1_2023.parquet")

3. Use Appropriate Date Ranges

Be mindful of the data range you’re requesting:

# Good: Reasonable date range
df = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")

# Consider carefully: Very large range
df = client.download_data("EURUSD", "M1", "2020-01-01", "2023-12-31")  # 4 years of minute data!

API Rate Limits

Rate Limit Considerations

Quantdle has API rate limits to ensure fair usage. The Python client automatically:

• Chunks large requests to avoid timeouts
• Implements retry logic for temporary failures
• Spaces out requests to prevent overwhelming the API

However, you should still be mindful of making too many concurrent requests.

Troubleshooting

Common Issues and Solutions

Authentication Errors

• Verify your API Key and API Key ID are correct
• Ensure your account has an active subscription
• Check that your API keys haven’t expired

Download Timeouts

• Try reducing the chunk_size_years parameter
• Check your internet connection stability
• Verify the requested date range has available data

Memory Issues with Large Datasets

• Use output_format="polars" for better memory efficiency
• Download smaller date ranges and combine locally
• Consider using streaming processing for very large datasets

Symbol Not Found

• Use get_available_symbols() to check available symbols
• Verify the symbol name format (e.g., “EURUSD” not “EUR/USD”)

Getting Help

If you encounter issues with the Python client:

1. Check the error message - most errors include helpful details about what went wrong.
2. Review the examples in this documentation to ensure correct usage.
3. Visit our FAQs page for additional help.
4. Report bugs on our GitHub repository.

Support Resources

• GitHub Issues: For bugs and feature requests.
• Documentation: This guide and API reference.
• Quantdle Support: For account and subscription questions.
• PyPI Page: Latest version and release notes at pypi.org/project/quantdle/.

What’s Next?

Now that you know how to use the Python client, explore these related topics:

• Symbol Information - Learn about available trading instruments.
• Custom Symbols - Using custom symbols in MetaTrader 5.
• API Keys Management - Managing your API credentials.

Symbol Reference

Explore all available symbols and their specifications

View Symbols →

MetaTrader Integration

Use the Expert Advisor for direct MT5 integration

Install EA →