Kraken

Kraken offers spot and derivatives trading across a wide range of digital assets. This integration connects to Kraken Pro and supports live market data and order execution for Kraken Spot and Kraken Derivatives (Futures).

Overview

The adapter is implemented in Rust with Python bindings and does not require an external Kraken client library. Each data or execution configuration selects a Spot or Futures client through its product_type.

The main Python components are:

• KrakenDataClientConfig and KrakenExecutionClientConfig: Live client configuration.
• KrakenDataClientFactory and KrakenExecutionClientFactory: Factories used by the trading node builder.
• KrakenSpotHttpClient and KrakenFuturesHttpClient: Lower-level HTTP access for direct requests.

The Rust crate also exposes KrakenSpotWebSocketClient and KrakenFuturesWebSocketClient for lower-level WebSocket access.

Examples

• Python examples
• Rust examples

Kraken documentation

Kraken provides detailed documentation for users:

• Kraken API documentation
• Kraken Spot REST API
• Kraken Derivatives API

Refer to the Kraken documentation in conjunction with this NautilusTrader integration guide.

Products

The adapter supports these product categories:

Spot instrument fees

Spot instruments do not carry maker or taker fee rates. Loading instruments does not call Kraken's TradeVolume endpoint.

A Spot API key without Funds permissions - Query (Query Funds) fails when the execution client requests account state.

Bar streaming

Supported intervals

The Kraken adapter supports real-time bar (OHLC) streaming for Spot markets via WebSocket. The following intervals are available:

Bar emission latency

Kraken's Spot WebSocket OHLC channel updates the current, incomplete bar on trade events. It does not provide a field that marks a bar as closed.

During normal streaming, the adapter buffers the current bar and emits it after receiving an update with a new interval_begin. The delay therefore depends on the first trade in the next interval and is not bounded to one bar period when a market has no trades. When the WebSocket message handler stops, the adapter flushes its buffered bars, including a current bar that may still be incomplete.

The adapter uses buffering instead of timer-based emission because:

• Timer-based emission could miss the final update before the bar closes.
• Kraken's updates are not guaranteed to arrive at exact interval boundaries.

This favors the latest venue update at the cost of latency.

Symbology

Spot symbol normalization

Kraken uses different Bitcoin symbol conventions across their APIs:

Kraken also uses XDG for Dogecoin in some Spot responses. The adapter normalizes it to DOGE, including in quote currency symbols.

Currency codes

Kraken reports some assets under legacy codes, prefixing them with X or Z: XXBT for Bitcoin, ZEUR for the euro. The adapter maps those to the standard code used everywhere else on the platform, so instruments, balances, fees and currency configuration all agree: XXBT and XBT become BTC, XXDG and XDG become DOGE, ZEUR becomes EUR, ZUSD becomes USD.

The mapping is an explicit table rather than a prefix rule, because the prefix is not a rule. XTZ, XRP, XLM, XAUT, ZRX and ZEC legitimately begin with those letters, and a code the table does not list passes through unchanged. Kraken's own CLI normalizes the same way.

Fees are booked in the currency the venue reports, where it reports one. Futures fills carry a fee currency, which on an inverse contract is the base rather than the quote. Kraken's Spot TradesHistory reports a fee amount without a currency, so those fills are booked in the instrument's quote currency.

Spot markets

NautilusTrader uses normalized, slash-separated symbols for Kraken Spot instruments. The adapter translates them to Kraken's native format internally.

Instrument ID format:

InstrumentId.from_str("BTC/USD.KRAKEN")  # Spot BTC/USD
InstrumentId.from_str("ETH/USD.KRAKEN")  # Spot ETH/USD
InstrumentId.from_str("SOL/USD.KRAKEN")  # Spot SOL/USD
InstrumentId.from_str("BTC/USDT.KRAKEN")  # Spot BTC/USDT
InstrumentId.from_str("ETH/BTC.KRAKEN")  # Spot ETH/BTC (normalized from ETH/XBT)

Futures markets

Kraken Futures instruments use a specific naming convention with prefixes:

• PI_ - Perpetual Inverse contracts (e.g., PI_XBTUSD)
• PF_ - Perpetual Fixed-margin contracts (e.g., PF_XBTUSD)
• PV_ - Perpetual Vanilla contracts (e.g., PV_XRPXBT)
• FI_ - Fixed maturity Inverse contracts (e.g., FI_XBTUSD_230929)
• FF_ - Flex futures contracts

Instrument ID format:

InstrumentId.from_str("PI_XBTUSD.KRAKEN")  # Perpetual inverse BTC
InstrumentId.from_str("PI_ETHUSD.KRAKEN")  # Perpetual inverse ETH
InstrumentId.from_str("PF_XBTUSD.KRAKEN")  # Perpetual fixed-margin BTC

Data capability

Subscriptions (real-time)

Requests (historical)

L3 order book (market-by-order)

Kraken exposes Spot per-order book data via the WebSocket v2 level3 channel at wss://ws-l3.kraken.com/v2. This gives venue order IDs, per-order quantities, and true incremental events (add, modify, delete). The adapter hashes each venue order ID into the u64 BookOrder.order_id field used by NautilusTrader.

Prerequisites

L3 subscriptions require Spot API credentials because Kraken's level3 channel is authenticated. Pass them to KrakenDataClientConfig:

from nautilus_trader.adapters.kraken import KrakenDataClientConfig

config = KrakenDataClientConfig(
    api_key="YOUR_KEY",
    api_secret="YOUR_SECRET",
)

Then subscribe with book_type=BookType.L3_MBO:

from nautilus_trader.model import BookType

await client.subscribe_book_deltas(
    instrument_id=instrument_id,
    book_type=BookType.L3_MBO,
    depth=1000,  # valid: 10, 100, 1000
)

Valid depths are 10, 100, and 1000. A depth of 0 uses 1000.

CRC32 checksum validation

By default, the adapter validates the CRC32 checksum on each L3 snapshot and update when Kraken provides one. On mismatch, it emits a Clear delta, clears local L3 state, refreshes the auth token, and resubscribes so Kraken sends a fresh snapshot. To disable validation for benchmarking:

config = KrakenDataClientConfig(
    api_key="...",
    api_secret="...",
    validate_l3_checksum=False,
)

Storage recommendations

OrderBookDelta already carries order_id: u64 in its Arrow schema, so L3 data is stored identically to L2 in the ParquetDataCatalog. L3 generates significantly more events per instrument than L2. Recommended settings:

• Lower chunk size (e.g. chunk_size=50_000) for faster parallel reads.
• Enable zstd compression in catalog config.
• Use per-instrument path partitioning (enabled by default).

Orders capability

Order types

Time in force

Execution instructions

Trigger types

Conditional orders (stop, take-profit, trailing stop) support a trigger price reference on Spot:

Batch operations

Position management

Order querying

Contingent orders

Maker Protection (Futures)

Kraken Futures applies Maker Protection on selected markets: placements and edits that could take liquidity are held for the market's configured window before reaching the matching engine. The classification is by order type, so any order not marked post_only is held even when it would in fact have rested. Post-only placements and all cancellations are never held, and no held-order state is exposed on any API. The venue applies the hold per market to every client; the adapter decodes the per-market window (makerProtectionMillis) on the raw venue instrument model and exposes no configuration for it.

Order-state handling accounts for the held-order semantics:

• A cancel acknowledged while an order is held is not terminal. The order is released as IOC and can still fill. Fills and terminal states are driven by venue order updates, never by the cancel acknowledgement itself.
• An order that cannot trade after such a release is reported with the venue status iocWouldNotExecute on REST (IOC_WOULD_ENTER_BOOK on market data), which the adapter treats as a terminal rejection. On the order-update feed the same outcome arrives as a terminal cancellation whose venue reason the adapter preserves.
• A released order cancels a resting order of the same account it would match, overriding the configured self-trade strategy. The resting order is reported canceled with reason CANCELLED_BY_SELF_TRADE.

The adapter closes an order only once the venue's fills for it are accounted.

Order-update feed

A removal with is_cancel=true and reason partial_fill discards the remainder and is terminal (a converted hold, or any IOC-style order). The delta carries the venue's cumulative filled.

• For a tracked order, the adapter closes from the feed once the fills stream has accounted that quantity. A fill still in flight is never orphaned, and a tracked order is not left open after its fills are accounted.
• For a removal it cannot match, the adapter skips and converges through reconciliation.

Reconciliation

A held order never reaches the book, so it is absent from /openorders. Mass status, open-only report runs, and targeted single-order queries consult POST /orders/status before treating the order as missing. That window reports orders that are open or were filled or canceled in the last 5 seconds.

A hold that fills after a cancel acknowledgement reconciles to its true terminal state with the venue's cumulative filled, not a premature cancellation.

Order routing (Spot)

The Spot execution client routes order submission, modification, cancellation, and batch cancellation through Kraken's authenticated WebSocket v2 trade channel by default. It falls back to REST when the WebSocket is inactive. Set use_ws_trade=False on KrakenExecutionClientConfig to route these operations through REST.

Order shapes routed via REST

Kraken's Spot WebSocket v2 add_order method supports these shapes, but the adapter routes them through REST:

Mixed-symbol order lists also use REST because Kraken's WebSocket batch_add request requires one shared symbol. Unsupported trigger references fall back to the REST path, which rejects them locally before sending a request to Kraken.

The per-call params={"use_ws_trade": False} override forces a single command through REST regardless of the configured default. Set it on SubmitOrder, ModifyOrder, CancelOrder, SubmitOrderList, or BatchCancelOrders.

WebSocket request timeout

When a WebSocket round-trip exceeds ws_request_timeout_secs (default 5), the venue outcome remains unknown. Submit, modify, cancel, and batch-add requests remain in flight without a terminal rejection. The dispatcher retains the request ID so a delayed matching response can still apply the normal success or definitive rejection handling.

Submit and batch-add timeouts also send a best-effort compensating cancel over the same WebSocket for every affected client order ID. This cancel limits exposure if Kraken accepted the order but delayed its response. It does not replace the unknown outcome with local terminal state.

Stream updates and the live execution reconciliation engine resolve orders when no matching response arrives. Targeted status queries can resolve modify or cancel requests that already have a venue order ID. A matching response or execution client shutdown retires the retained request correlation.

WebSocket order-routing options

KrakenExecutionClientConfig exposes:

Reconciliation

The Kraken adapter provides reconciliation capabilities for both Spot and Futures markets, allowing traders to synchronize their local state with the exchange state at startup or during operation.

Bounded reports

When reconciliation supplies a lookback, both execution clients derive a single cutoff and apply it to every historical query, then record it on the mass status through set_report_window. Using one cutoff avoids a report set that never existed at the venue, which a moving cutoff can produce.

Declaring the cutoff is what lets the engine apply its bounded-history rules; the completeness flag described below qualifies that set rather than gating it.

Order and fill records contribute to the completeness flag: the set is incomplete when a record's instrument could not be resolved, or when a record could not be parsed. Position records do not currently contribute, and the futures position read still drops an unresolved symbol silently.

Spot closed-order and fill reads page through an offset until the venue returns an empty page, and stop after 500 pages. A read cut short by that cap logs a warning, and how it surfaces depends on the caller. Startup mass status carries the completeness of the order and fill reads in its report window, so the engine sees the set as incomplete. generate_order_status_reports and generate_fill_reports return the records read up to the cap and do not expose a completeness flag.

Spot reconciliation

Order status reports:

• Open orders: Fetches all currently active orders.
• Closed orders: Fetches historical orders with pagination support.
• Time-bounded queries: Supports filtering by start/end timestamps.
• Startup mass status reads closed orders alongside open ones, so an order that reached a terminal state while the node was down is reconciled. The reconciliation lookback bounds the read, and a closed-order read cut short by the page cap leaves the mass status incomplete.

Fill reports:

• Trade history: Fetches execution history with pagination.
• Time-bounded queries: Supports filtering by start/end timestamps.
• All fill types: Market, limit, and conditional order fills.

Pair spelling:

• Kraken spells a pair two ways: the AssetPairs key (XXBTZEUR), used as the instrument raw_symbol, and the altname (XBTEUR). OpenPositions returns the key, while OpenOrders and TradesHistory return the altname.
• The adapter resolves both spellings, so an order or fill on a legacy-named pair is reported.
• A read scoped to one instrument resolves each row and compares instrument IDs, rather than comparing a cached raw_symbol against the venue's spelling, so a scoped read returns that pair's own records whichever way Kraken spells it.
• A read scoped to an instrument the client does not hold returns nothing. Spot and futures IDs share the KRAKEN venue, so a futures ID can reach the spot client and the reverse; neither falls back to returning every instrument's records.
• A spot instrument whose altname differs from its AssetPairs key carries the altname in its info map, so a client whose instruments arrive through cache_instrument or cache_instruments resolves altname-spelled records without refetching AssetPairs.
• On an unscoped read, an open order whose pair cannot be resolved to a cached instrument fails the read, rather than being omitted from an otherwise successful one. A scoped read skips a record it cannot resolve, since it cannot belong to the requested instrument.
• A closed order or fill that cannot be resolved is logged as a warning and skipped, preserving the records that do resolve. Historical records routinely outlive the loaded instrument set.

Account balances:

• Wallet balances: Fetched from POST /0/private/BalanceEx, which reports both the total and the held (hold_trade) amount per asset. The held amount populates AccountBalance.locked, so free excludes funds Kraken has reserved against resting orders. For accounts with a credit line, net credit (credit - credit_used) is included in AccountBalance.total, so free matches Kraken's available balance of balance + credit - credit_used - hold_trade.
• Zero balances: An asset Kraken lists at zero is reported at zero rather than omitted, on both spot and futures. The engine only ever inserts balances, so a currency left out of a snapshot keeps its previous value. On futures the zero joins the per-currency sum, so a funded wallet alongside an empty one of the same asset reports the funded amount. An asset Kraken drops from the response entirely still keeps its last reported value.

Margin position reports (when spot_account_type=Margin):

• Open positions: Fetched from POST /0/private/OpenPositions and aggregated by pair into PositionStatusReport entries. Kraken returns one entry per lot, so opposing lots for the same pair net into a single report.
• Entry average: Each report carries avg_px_open, derived from the lot cost and vol fields and weighted by the volume still open. Long and short lots are averaged separately, so the reported average describes the side that survives netting. Reconciliation needs this value to open a position from a report when the cache holds no order or fill history for it.
• The average is marked AvgPxReconciliation::OpeningOnly, because Kraken closes margin lots FIFO and drops a fully closed one from OpenPositions. After a partial close the average therefore describes the lots that remain open rather than the opening fills, and would not match a netting position's average. Reconciliation uses it to open a position from flat and never compares it. Futures keeps the default, since that endpoint reports one netted position whose price Kraken documents as the average entry price.
• No synthetic FLAT cleanup: OpenPositions reports leveraged positions only, so an unleveraged spot holding never appears there and its absence is not evidence that the position is closed. The bulk read reports only what the venue returns.
• Margin balances: POST /0/private/TradeBalance is called alongside the account-state refresh; used margin populates MarginBalance.initial, while equity and free margin populate the summary balance (see Spot margin trading).

Futures reconciliation

Order status reports:

• Open orders: Fetches all currently active futures orders.
• Historical orders: Fetches closed and filled orders when open_only=False.
• Order events: Full order lifecycle history via /api/history/v2/orders endpoint.

Fill reports:

• Fill history: Fetches all execution reports.
• Time filtering: Client-side filtering by start/end timestamps (parses RFC3339 timestamps).
• All fill types: Maker and taker fills with fee information.

Position status reports:

• Open positions: Fetches all active futures positions.
• Real-time data: Includes unrealized funding, average price, and position size.

Spot position reports (cash mode)

In cash mode, the Kraken adapter can optionally report wallet balances as position status reports for spot instruments. This feature is disabled by default and must be explicitly enabled via configuration. Margin-mode accounts should leave it disabled and rely on OpenPositions instead (see Spot margin trading).

How it works:

• When enabled, wallet balances are converted to PositionStatusReport objects.
• Positive balances are reported as LONG positions.
• Only instruments matching the configured quote currency are reported (default: USDT). The same filter decides which instruments the client declares bulk position coverage for, so an instrument quoted in anything else is never reconciled to flat from a missing report.
• This prevents duplicate reports when the same asset is available with multiple quote currencies (e.g., BTC/USD, BTC/USDT, BTC/EUR).

Configuration:

from nautilus_trader.adapters.kraken import KrakenExecutionClientConfig
from nautilus_trader.model import AccountId


exec_config = KrakenExecutionClientConfig(
    account_id=AccountId.from_str("KRAKEN-001"),
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    use_spot_position_reports=True,
    spot_positions_quote_currency="USDT",  # Default
)

Spot margin trading

Kraken Spot supports leveraged trading on selected pairs. Per-pair availability and the valid leverage tiers are advertised by Kraken on the instruments endpoint as AssetPairInfo.leverage_buy and leverage_sell; the adapter caches these at instrument-load time and validates the requested tier before order submission. Margin trading is enabled per-execution-client via spot_account_type, with per-order leverage params.

Configuration

from nautilus_trader.adapters.kraken import KrakenExecutionClientConfig
from nautilus_trader.model import AccountId
from nautilus_trader.model import AccountType


exec_config = KrakenExecutionClientConfig(
    account_id=AccountId.from_str("KRAKEN-001"),
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    spot_account_type=AccountType.MARGIN,
    default_leverage=3,  # Optional config-level default
    margin_balance_asset="ZGBP",  # Optional summary-display asset
)

margin_balance_asset controls only the denomination of the account-summary metrics returned by Kraken's TradeBalance endpoint (equity, free margin, used margin, etc.). Per-position figures from OpenPositions are always in the traded pair's quote currency.

Per-order leverage

Override the configured default on a single order via params:

order = strategy.order_factory.limit(
    instrument_id=BTC_USD,
    order_side=OrderSide.BUY,
    quantity=Quantity.from_str("0.01"),
    price=Price.from_str("50000.00"),
    params={"leverage": 5},
)

The adapter validates the requested tier against AssetPairInfo.leverage_buy / leverage_sell for the pair before submitting; an invalid tier produces an OrderDenied event and never hits the venue.

Reduce-only

Margin orders can carry reduce_only=True so they reduce an existing position without opening a larger opposite position. Set spot_account_type=Margin and supply either default_leverage or per-order params={"leverage": N}. The adapter denies cash orders with reduce_only before sending them to Kraken.

Account state

When spot_account_type=Margin, the execution client calls Kraken's TradeBalance endpoint during account refreshes. The live account state uses:

• Equity (e) and free margin (mf) for the balance denominated by margin_balance_asset.
• Used margin (m) for MarginBalance.initial. Maintenance margin is zero because Kraken does not return a separate maintenance-margin amount.

The lower-level KrakenSpotHttpClient methods request_margin_metrics() and request_account_state_with_metrics() return the full TradeBalance metrics dictionary for direct consumers. The live execution client does not attach that dictionary to AccountState.info.

Position reconciliation

Open spot margin positions are surfaced via POST /0/private/OpenPositions on each position_check_interval_secs tick. This path is independent of use_spot_position_reports (which is wallet-derived, cash-mode-only).

The spot client declares bulk position coverage per instrument, and only for instruments the read would actually enumerate: cash mode with use_spot_position_reports=True, and the instrument quoted in spot_positions_quote_currency (see Spot position reports, which applies the same filter). Under spot_account_type=Margin the source is OpenPositions, which omits unleveraged lots, and cash mode without wallet-derived reports returns nothing at all. Wherever coverage is not declared, an absent report leaves the cached position untouched instead of closing it.

Funding rates

The adapter receives funding rate data from the Futures ticker WebSocket feed, which provides relative_funding_rate and next_funding_rate_time for perpetual futures.

The interval field on FundingRateUpdate is None for Kraken because the ticker feed does not include a funding interval field and the Kraken API documentation does not specify a fixed funding period.

Rate limiting

Each Kraken HTTP client applies an adapter-side request throttle. The default is five requests per second and max_requests_per_second can override it. This is a request-count throttle, not a complete model of Kraken's endpoint costs or account-tier budgets.

Kraken applies different venue limits to Spot and Futures:

• Spot REST rate limits use a tier-dependent call counter. Ledger and trade history calls add 2, most other REST calls add 1, and order management uses a separate trading limiter.
• Derivatives rate limits use endpoint costs and separate budgets for /derivatives and /history paths.

The current Spot REST call-counter limits are:

If the adapter's fixed request rate is too high for the endpoint mix and account tier, Kraken can still reject or throttle requests.

Reconciliation interval guidance

The execution engine's open_check_interval_secs and position_check_interval_secs settings create sustained private REST API load. Short intervals can exhaust Kraken's venue budgets even when the adapter stays below its configured requests-per-second throttle.

Use conservative intervals as a starting point, especially for a Spot Starter account:

exec_engine = LiveExecutionEngineConfig(
    reconciliation=True,
    open_check_interval_secs=30.0,  # Conservative Spot Starter-tier starting point
    position_check_interval_secs=120.0,
)

Tune these values for the account tier, enabled reconciliation checks, and other clients using the same API key. If Kraken returns EAPI:Rate limit exceeded, increase the intervals or reduce max_requests_per_second.

Configuration

The product type for each client is specified via the product_type option.

Data client configuration options

Execution client configuration options

For spot margin, default_leverage applies when an order has no per-order leverage param. margin_balance_asset only changes the TradeBalance summary denomination; per-position figures remain in the pair's quote currency.

Demo environment setup

To test with Kraken Futures demo (paper trading):

1. Sign up at Kraken Futures demo and generate API credentials.
2. Set environment variables with your demo credentials:
   • KRAKEN_FUTURES_DEMO_API_KEY
   • KRAKEN_FUTURES_DEMO_API_SECRET
3. Read the credentials and pass them to KrakenExecutionClientConfig, then set environment=KrakenEnvironment.DEMO and product_type=KrakenProductType.FUTURES.

The Python examples show the complete demo and live LiveNode configurations.

Production configuration

Use KrakenDataClientConfig with KrakenDataClientFactory, and use KrakenExecutionClientConfig with KrakenExecutionClientFactory. The Python examples show the complete LiveNode.builder(...) configuration for data and execution clients.

API credentials

Live-node configuration objects do not read credential environment variables automatically. Pass api_key and api_secret explicitly to KrakenExecutionClientConfig and, for Spot L3 data, to KrakenDataClientConfig. Public market data does not require credentials.

The lower-level Python HTTP and WebSocket clients load the following variables when their credential arguments are omitted. Rust applications can use KrakenCredential::from_env_spot() or KrakenCredential::from_env_futures(demo) to load them before constructing live-node configs.

Authentication errors are reported when a private client connects or performs a private operation. Required permissions depend on the requested data or trading operation.

Contributing