Skip to main content

dukascopy-python

Download historical financial market data from Dukascopy Bank SA, including tick-level prices and OHLCV candles for Forex, commodities, indices, and other financial instruments.

Supports multiple data feed versions, configurable HTTP sessions, optional logging, and Pandas integration.

Installation

pip install dukascopy-python

Backward Compatibility

The previous API remains available through dukascopy_python.compat, which uses data feed version 1 internally.

Existing applications can continue using fetch(), live_fetch(), and legacy constants by updating their imports.

from datetime import datetime, timezone

import dukascopy_python.compat as duka
from dukascopy_python.compat.instruments import (
    INSTRUMENT_FX_MAJORS_EUR_USD,
)

df = duka.fetch(
    INSTRUMENT_FX_MAJORS_EUR_USD,
    duka.INTERVAL_MIN_1,
    duka.OFFER_SIDE_BID,
    datetime(2025, 1, 1, tzinfo=timezone.utc),
    datetime(2025, 1, 2, tzinfo=timezone.utc),
)

df.to_csv("output.csv")

New API

The new API provides two functions:

  • fetch_candles() — Retrieve historical OHLCV candles.
  • fetch_ticks() — Retrieve historical bid/ask tick data.

Fetch Candles

from datetime import datetime, timezone

import dukascopy_python as duka
from dukascopy_python.instruments import I_EUR_USD

candles = duka.fetch_candles(
    instrument=I_EUR_USD,
    interval=1,
    time_unit=duka.TimeUnit.HOUR,
    offer_side=duka.OfferSide.BID,
    start=datetime(2025, 1, 1, tzinfo=timezone.utc),
    end=datetime(2025, 2, 1, tzinfo=timezone.utc),
    version=2,
)

for candle in candles:
    print(candle)

Fetch Ticks

ticks = duka.fetch_ticks(
    instrument=I_EUR_USD,
    start=datetime(2025, 1, 1, tzinfo=timezone.utc),
    end=datetime(2025, 1, 2, tzinfo=timezone.utc),
    version=2,
)

for tick in ticks:
    print(tick)

Both functions return iterable model objects.

Parameters

Parameter Description
instrument Instrument code, e.g. I_EUR_USD
start Start datetime (inclusive range boundary, subject to feed behaviour)
end End datetime; must be later than start
version 1 or 2; defaults to the globally configured version
validate_instrument_name Validate and convert the instrument identifier; default True
create_session Optional callable returning an HTTP session
logger Optional logging.Logger instance

Additional parameters for fetch_candles():

Parameter Description
interval Positive integer specifying the candle interval
time_unit TimeUnit enum, e.g. TimeUnit.MINUTE
offer_side OfferSide.BID or OfferSide.ASK

start and end must both be timezone-aware or both timezone-naive. UTC-aware datetimes are recommended.

Data Feed Versions

Two data feed implementations are available.

Version Implementation
1 DataFeedV1 (default)
2 DataFeedV2

Set the Default Version

duka.set_default_version(2)

All subsequent fetch operations use version 2 unless explicitly overridden.

Override Version Per Request

candles = duka.fetch_candles(
    instrument=I_EUR_USD,
    interval=5,
    time_unit=duka.TimeUnit.MINUTE,
    offer_side=duka.OfferSide.BID,
    start=start,
    end=end,
    version=1,
)

The version argument overrides the default for that request without changing the global setting.

Data Models

Candle

Field Description
timestamp Candle timestamp
open, high, low, close OHLC prices
volume Trading volume
time_unit Candle time unit
interval Candle interval

Tick

Field Description
timestamp Tick timestamp
bid, ask Bid and ask prices
bid_volume, ask_volume Bid and ask volumes
volume Tick volume

Pandas Integration

Convert retrieved candles or ticks into a Pandas DataFrame.

candles = list(duka.fetch_candles(
    instrument=I_EUR_USD,
    interval=1,
    time_unit=duka.TimeUnit.HOUR,
    offer_side=duka.OfferSide.BID,
    start=start,
    end=end,
))

df = duka.to_dataframe(candles)

df.to_csv("candles.csv")
df.to_json("candles.json")

Pandas is an optional dependency. Install it with:

pip install pandas

Advanced Configuration

Custom HTTP Session

Use the create_session argument to provide a session factory.

candles = duka.fetch_candles(
    instrument=I_EUR_USD,
    interval=1,
    time_unit=duka.TimeUnit.HOUR,
    offer_side=duka.OfferSide.BID,
    start=start,
    end=end,
    create_session=lambda: duka.create_session(retries=7),
)

The library manages the returned session using a context manager.

Custom Logging

Provide a configured Python logger:

import logging

logger = duka.create_logger(
    name="dukascopy",
    level=logging.DEBUG,
)

ticks = duka.fetch_ticks(
    instrument=I_EUR_USD,
    start=start,
    end=end,
    logger=logger,
)

Instrument Validation

Instrument validation and identifier conversion are enabled by default.

To bypass them:

ticks = duka.fetch_ticks(
    instrument="EUR/USD",
    start=start,
    end=end,
    version=2,
    validate_instrument_name=False,
)

When validation is disabled, the instrument identifier is passed directly to the selected data feed.

Migration Reference

Previous API New API
dukascopy_python.compat dukascopy_python
fetch() fetch_candles() / fetch_ticks()
live_fetch() Available through compat
INTERVAL_MIN_1 interval=1, time_unit=TimeUnit.MINUTE
OFFER_SIDE_BID OfferSide.BID
INSTRUMENT_FX_MAJORS_EUR_USD I_EUR_USD
Pandas DataFrame Iterable Candle / Tick objects

License

MIT

Contributing

Contributions, bug reports, and pull requests are welcome.

Metadata

Release files for dukascopy-python 5.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dukascopy-python 5.0.0
File Size Uploaded Provenance Actions
dukascopy_python-5.0.0.tar.gz 108.6 kB Without provenance Details for dukascopy_python-5.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dukascopy-python 5.0.0
File Interpreter ABI Platform Actions
dukascopy_python-5.0.0-py3-none-any.whl Python 3 none any Details for dukascopy_python-5.0.0-py3-none-any.whl

Total release size: 219.1 kB

Release files / dukascopy_python-5.0.0.tar.gz

Download URL dukascopy_python-5.0.0.tar.gz
Size 108.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0543794f45f0f79b1526b6b66f16e69f8f61ff80ca8cf189542af9730c379eb1
BLAKE2b-256 checksum
How to use checksums
7c9d0fbc1f70e1c71896e1438f1861aa3b8b92a3171af85f350753331e08c0f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / dukascopy_python-5.0.0-py3-none-any.whl

Download URL dukascopy_python-5.0.0-py3-none-any.whl
Size 110.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d294c30f7b17c8c7063ba28d8f4033c8bf069e7be6b5d8811f47f76d017e117
BLAKE2b-256 checksum
How to use checksums
2e01983ad0b3c2a11da4e71440ca864c5373bab74d392b0913cd76ace3844a45
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for dukascopy-python 5.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page