The Kraken Pro connector polls a Kraken Pro account and surfaces its asset wallets, balances, payments, trading orders, and conversions. It is read-only and spot-only.
Kraken Pro API keys scope to a single account, so install one connector instance per Kraken Pro account you need to get data from.
Prerequisites#
You need a Kraken Pro account and an API key. Kraken signs requests with HMAC-SHA512; the connector signs internally — you supply only the key and secret.
The API key must carry at least the following scopes:
- Funds → Query
- Orders & trades → Query closed orders & trades
- Data → Query ledger entries
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
Installation#
With config.json containing:
Configuration fields#
| Field | Required | Default | Description |
|---|---|---|---|
apiKey | yes | — | Kraken Pro API key. |
apiSecret | yes | — | Kraken Pro private key. |
endpoint | yes | — | Kraken Pro API base URL, e.g. https://api.kraken.com. |
name | yes | — | Unique name for this connector instance (e.g. krakenpro-main, krakenpro-treasury when running one per account). |
pollingPeriod | no | 30m | Sync cadence (min 20m). Drives every capability. |
The config is deliberately minimal — the API key scopes the connection to a single Kraken Pro account, and Kraken's API exposes no portable way to fan out across accounts.
Capabilities#
The Kraken Pro connector supports the following read-only capabilities:
- FetchAccounts — one account per asset variant present via
POST /0/private/BalanceEx. - FetchBalances — derived from the same
BalanceExcall, no extra hop. - FetchPayments — deposits, withdrawals, transfers, staking, rewards, and adjustments from
POST /0/private/Ledgers. - FetchOrders — closed/historical orders from
POST /0/private/ClosedOrders. - FetchConversions — off-orderbook swaps from
POST /0/private/Ledgers, grouped byrefid.
Account model#
Each Connectivity account maps to one Kraken asset wallet. Kraken keeps a separate wallet per asset variant — the spot balance, staked balance, rewards balance, and so on are distinct — and each becomes its own account. The reference is Kraken's asset code (XXBT, XBT.M, ZUSD, ADA.S), a wallet_type metadata key records the variant (spot, staked, rewards, yield, earn, parachain, tokenised, hold, margin), and defaultAsset is the normalised TICKER/precision (see Asset model). Only assets the account holds or has held are surfaced. See the generic Accounts page for the cross-connector model.
Kraken doesn't expose a creation date per asset wallet, so CreatedAt is set to a fixed placeholder — Kraken's launch date, 2011-08-01T00:00:00Z.
Asset model#
Kraken uses its own asset codes (XXBT, ZUSD, XETH). The connector normalises them to standard tickers — XXBT → BTC, ZUSD → USD, XETH → ETH — so assets appear under the symbols you expect.
Precision follows Kraken's internal precision for each asset, which is finer than common market conventions (e.g. BTC/10 rather than BTC/8, USD/4 rather than USD/2). This keeps every amount exact — no value is rounded or truncated on the way in.
Status mapping#
Payments come from Kraken's Ledgers endpoint, which only writes an entry on settlement — there is no pending state at this layer, so every Payment is SUCCEEDED.
Order status is derived from Kraken's status enum combined with the filled-vs-ordered volume:
Kraken status | vol_exec vs vol | Order status |
|---|---|---|
closed | exec ≥ vol | FILLED |
closed | 0 < exec < vol | PARTIALLY_FILLED |
closed | 0 | CANCELLED |
canceled | exec > 0 | PARTIALLY_FILLED |
canceled | 0 | CANCELLED |
expired | — | EXPIRED |
Payments#
A Payment is one row from /0/private/Ledgers. Kraken's ledger type enum maps as follows:
Kraken type | Payment type |
|---|---|
deposit | PAYIN |
withdrawal | PAYOUT |
transfer, custodytransfer | TRANSFER |
staking, reward, dividend, credit, nft_rebate | PAYIN |
nftcreatorfee | PAYOUT |
adjustment, rollover, settled, reserve, ic_settlement, … | OTHER |
trade, eqtrade | skipped — handled by Orders |
conversion, sale, marginconversion, margin_conversion | skipped — handled by Conversions |
The Payment reference is the ledger entry id (not refid, which groups multi-leg events). The row's fee is recorded in metadata but not subtracted from the amount. Unknown future type values fall back to OTHER with a warning log.
Orders#
Only closed orders are registered — an order is surfaced once it has been filled, cancelled, or expired. In-flight orders that are still open or partially filled are not tracked while they remain active.
Conversions#
Conversions share the /0/private/Ledgers stream with payments but classify a distinct type set — conversion, sale, marginconversion, margin_conversion (plus derivatives variants for exhaustiveness; spot-only accounts see only the first two). A conversion is a pair of ledger rows sharing one refid: a negative-amount leg (source asset) and a positive-amount leg (destination asset).
SourceAmount / DestinationAmount are gross; fee is the sum across both legs.
Metadata keys#
All keys are namespaced com.krakenpro.spec/:
- Account:
wallet_type(spot/staked/rewards/ …). - Payment / Conversion:
refid,kraken_type,subtype,aclass,balance_after;fee(payments);source_ledger_id,destination_ledger_id(conversions). - Order:
pair,ws_name,ordertype,price_asset,fills(comma-separated fill txids),cl_ord_id?.
Known gaps#
- Orders appear only once they're closed (filled, cancelled, or expired) — orders that are still open or partially filled aren't shown while active.
- A Kraken Pro API key is scoped to a single account, so reconciling multiple accounts means installing one connector per account.