Trading on Kraken

Kraken is the only supported exchange that runs two separate products behind a single account: Kraken Spot at api.kraken.com and Kraken Futures at futures.kraken.com. They have separate API key management, different signing schemes, and different symbol formats. OEMS hides most of this. You register one exchange account (one exchange_account_id), provide one credential pair for spot and an optional second pair for futures, and OEMS routes every call to the right product behind the scenes. This guide walks through the full flow.

1. Set up your Kraken API keys

You’ll need two API keys, generated independently. Create both in Kraken Pro (web UI), one in the Spot area and one in the Futures area.

Spot key (api.kraken.com)

In Kraken Pro → Settings → API → Manage API Keys, generate a key with these permissions:

✅ Query Funds (required for balance / position polling)
✅ Query Open Orders & Trades
✅ Query Closed Orders & Trades
✅ Query Ledger Entries
✅ Create & Modify Orders (for spot order placement)
✅ Cancel/Close Orders
❌ Withdraw Funds — DO NOT enable
❌ Deposit Funds — not needed for trading

Set Nonce Window = 10000 ms. This absorbs cross-process nonce drift between OEMS, the polling jobs, and any other services sharing the key. The default 5000 ms is fine for a single-process integration but tight for ours.

Futures key (futures.kraken.com)

Open futures.kraken.com → Settings → API Keys. Generate a separate key with:

✅ Read (account / positions / orders)
✅ Trade (place / cancel orders)
❌ Withdraw — DO NOT enable

Kraken Futures’ UI does not expose a per-key nonce window setting. That’s fine — OEMS uses microsecond nonces and few processes hit the futures key, so collisions are very unlikely.

2. Register the account in OEMS

You can configure the keys at registration or add them later.

Option A — at registration time

curl -X POST https://api.dev.autowhale.net/delegation/register-exchange-account \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "exchange": "kraken",
    "params": {
      "apiKey": "<spot-api-key>",
      "secret": "<spot-secret>",
      "futuresApiKey": "<futures-api-key>",
      "futuresSecret": "<futures-secret>"
    }
  }'

Either credential pair can be omitted. Spot-only or futures-only are both valid configurations:

Spot only: Trading futures pairs returns PERMISSION_DENIED: futures key not configured.
Futures only: Trading spot pairs returns the equivalent.

Option B — add the futures key later

If the account already exists with only the spot pair, send a PUT to the credentials endpoint:

curl -X PUT https://api.dev.autowhale.net/delegation/exchange-account/credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "params": {
      "futuresApiKey": "<futures-api-key>",
      "futuresSecret": "<futures-secret>"
    }
  }'

Same path can be used to rotate keys (overwrite) or clear them (send "" or null for the value). Behind the scenes:

Each value is encrypted via the same SECRET_KEY-derived AES path as the spot keys; it sits in the same params JSONB column.
The cached CCXT instances for the account are invalidated, so the next OEMS call re-instantiates with the new credentials.

3. Symbol conventions

Kraken Spot and Kraken Futures use different symbol formats. OEMS accepts CCXT’s unified format for both.

Product	CCXT symbol	Notes
Spot	`BTC/USD`, `BTC/EUR`, `BTC/USDT`	Quote is a fiat or stablecoin.
Perp (USD-margined)	`BTC/USD:USD`	The `:USD` suffix marks it as a perpetual settled in USD.
Perp (USDT-margined linear)	`BTC/USD:USDT`	Less common on Kraken; use `:USD` unless you specifically need linear.
Dated futures	`BTC/USD:USD-260626`	Expiry suffix `YYMMDD`.

When you call /oems/execution/order with market_type: "swap" and a Kraken account, OEMS resolves to ccxt.krakenfutures and expects the symbol to be in CCXT futures format (BTC/USD:USD).

4. Move funds to the right wallet

Kraken Spot and Kraken Futures hold balances in separate wallets. A USDT balance on the spot side can’t margin a futures order — you need to transfer it across.

Check both wallets

# Spot
curl "https://api.dev.autowhale.net/oems/execution/balance?exchange_account_id=exchange_my_kraken&market_type=spot" \
  -H "Authorization: Bearer $TOKEN"

# Futures
curl "https://api.dev.autowhale.net/oems/execution/balance?exchange_account_id=exchange_my_kraken&market_type=swap" \
  -H "Authorization: Bearer $TOKEN"

Transfer spot → futures

curl -X POST https://api.dev.autowhale.net/oems/execution/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "asset": "USD",
    "amount": 100,
    "from_account": "spot",
    "to_account": "swap"
  }'

The /transfer endpoint is unified across exchanges that support inter-wallet moves (Kraken, Binance, OKX, Gate.io). On exchanges with a single unified wallet (Bybit UTA, Hyperliquid) it returns NOT_SUPPORTED.

5. Set leverage and margin mode (futures only)

Set leverage

curl -X POST https://api.dev.autowhale.net/oems/execution/leverage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "leverage": 5,
    "market_type": "swap"
  }'

Set margin mode

Kraken Futures models margin mode as a per-pair leverage preference:

isolated: a leverage preference is set for the symbol
cross: no leverage preference is set (default)

# Isolated 5x
curl -X POST https://api.dev.autowhale.net/oems/execution/margin-mode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "margin_mode": "isolated",
    "market_type": "swap"
  }'

# Back to cross
curl -X POST https://api.dev.autowhale.net/oems/execution/margin-mode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "margin_mode": "cross",
    "market_type": "swap"
  }'

CCXT’s unified set_margin_mode is not implemented for krakenfutures. OEMS works around this via an adapter override that calls Kraken’s /derivatives/api/v3/leveragepreferences endpoint directly. From the caller’s perspective the unified /margin-mode route just works.

6. Place orders

The /oems/execution/order endpoint takes the same shape regardless of spot / perp — only symbol, market_type, and a few perp-specific flags (reduce_only) change between the two.

Spot market buy

curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD",
    "side": "buy",
    "order_type": "market",
    "quantity": 0.001,
    "market_type": "spot"
  }'

Perp limit order, post-only

curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "side": "buy",
    "order_type": "limit",
    "quantity": 0.0001,
    "price": 70000,
    "post_only": true,
    "market_type": "swap"
  }'

Perp stop-loss with reduce-only

curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "side": "sell",
    "order_type": "stop_loss",
    "quantity": 0.0004,
    "stop_price": 70000,
    "reduce_only": true,
    "market_type": "swap"
  }'

Perp take-profit with reduce-only

curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "side": "sell",
    "order_type": "take_profit",
    "quantity": 0.0004,
    "stop_price": 95000,
    "reduce_only": true,
    "market_type": "swap"
  }'

Stop-limit (limit triggered at stop price)

curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "side": "sell",
    "order_type": "stop_loss_limit",
    "quantity": 0.0004,
    "price": 69000,
    "stop_price": 70000,
    "reduce_only": true,
    "market_type": "swap"
  }'

7. Read positions and close

Get open positions

curl "https://api.dev.autowhale.net/oems/execution/positions?exchange_account_id=exchange_my_kraken&market_type=swap" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "isError": false,
  "data": {
    "positions": [
      {
        "symbol": "BTC/USD:USD",
        "side": "short",
        "contracts": 0.0004,
        "entry_price": 80826.0,
        "leverage": 5.0,
        "exchange": "krakenfutures",
        "exchange_account_id": "exchange_my_kraken"
      }
    ],
    "count": 1
  }
}

Close a position

OEMS doesn’t have a separate “close position” verb — close via a reduce_only market order in the opposite direction:

# Close the SHORT BTC/USD:USD position above
curl -X POST https://api.dev.autowhale.net/oems/execution/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "exchange_my_kraken",
    "symbol": "BTC/USD:USD",
    "side": "buy",
    "order_type": "market",
    "quantity": 0.0004,
    "reduce_only": true,
    "market_type": "swap"
  }'

8. Funding and realized PnL

Funding rate history

curl "https://api.dev.autowhale.net/oems/execution/funding-history?exchange_account_id=exchange_my_kraken&symbol=BTC/USD:USD&limit=10&market_type=swap" \
  -H "Authorization: Bearer $TOKEN"

Kraken Futures publishes funding rates as a schedule (per-rate history), not as discrete payment events. OEMS sources this from fetch_funding_rate_history and returns the unified payments shape.

Realized PnL

curl "https://api.dev.autowhale.net/oems/execution/realized-pnl?exchange_account_id=exchange_my_kraken&limit=10&market_type=swap" \
  -H "Authorization: Bearer $TOKEN"

Kraken Futures has no “income” endpoint analogous to Binance. OEMS aggregates realized PnL from fetch_my_trades — each trade that closes (or partially closes) a position carries realisedPnl in its info payload. OEMS filters and returns just the PnL events.

9. Troubleshooting

`EAPI:Invalid nonce`

The same Kraken key was used by another process in the recent past with a higher nonce. Set Nonce Window = 10000 ms on the spot key in Kraken Pro → API → Manage API Keys (per the setup section above). The futures-side UI doesn’t expose this setting; the microsecond override OEMS applies is normally sufficient there.

`EGeneral:Permission denied`

The key is valid but lacks a permission for the operation. Most common: missing Query Funds on the spot key. Update permissions in Kraken Pro and retry. OEMS surfaces this with an explicit PERMISSION_DENIED rather than the generic “wrong key” message.

`authenticationError` from `krakenfutures`

You’re trying to use a spot key against the futures API. Spot keys cannot sign futures requests. Configure a separate futures key per the setup section, then either re-register or use the PUT /credentials endpoint to add it.

Order rejected with `wouldNotReducePosition`

A reduce-only order’s quantity exceeds the open position size, or the order is in the wrong direction to reduce. Check /positions first and place a smaller / opposite order.

Spot-purchased BTC shows up under “Staking/Yield Farming”

Kraken auto-allocates spot balances to Flex Earn by default in many regions. This is a Kraken account setting — disable Auto-allocate to Earn in Kraken Pro → Earn → Allocations to keep new spot purchases in the trading wallet, or un-allocate the existing balance manually.

Quick reference

Task	Endpoint	`market_type`
Spot balance	`GET /balance`	`spot`
Futures balance	`GET /balance`	`swap`
Place spot order	`POST /order`	`spot`
Place perp order	`POST /order`	`swap`
Set leverage	`POST /leverage`	`swap`
Set margin mode	`POST /margin-mode`	`swap`
Open positions	`GET /positions`	`swap`
Move spot → futures	`POST /transfer`	implicit (driven by `from_account`/`to_account`)
Funding rate history	`GET /funding-history`	`swap`
Realized PnL	`GET /realized-pnl`	`swap`
Add / rotate futures key	`PUT /delegation/exchange-account/credentials`	n/a

Getting Started

Exchange Guides

API Reference

Trading on Kraken

Trading on Kraken

1. Set up your Kraken API keys

Spot key (api.kraken.com)

Futures key (futures.kraken.com)

2. Register the account in OEMS

Option A — at registration time

Option B — add the futures key later

3. Symbol conventions

4. Move funds to the right wallet

Check both wallets

Transfer spot → futures

5. Set leverage and margin mode (futures only)

Set leverage

Set margin mode

6. Place orders

Spot market buy

Perp limit order, post-only

Perp stop-loss with reduce-only

Perp take-profit with reduce-only

Stop-limit (limit triggered at stop price)

7. Read positions and close

Get open positions

Close a position

8. Funding and realized PnL

Funding rate history

Realized PnL

9. Troubleshooting

`EAPI:Invalid nonce`

`EGeneral:Permission denied`

`authenticationError` from `krakenfutures`

Order rejected with `wouldNotReducePosition`

Spot-purchased BTC shows up under “Staking/Yield Farming”

Quick reference

Getting Started

Exchange Guides

API Reference

Documentation Index

​Trading on Kraken

​1. Set up your Kraken API keys

​Spot key (api.kraken.com)

​Futures key (futures.kraken.com)

​2. Register the account in OEMS

​Option A — at registration time

​Option B — add the futures key later

​3. Symbol conventions

​4. Move funds to the right wallet

​Check both wallets

​Transfer spot → futures

​5. Set leverage and margin mode (futures only)

​Set leverage

​Set margin mode

​6. Place orders

​Spot market buy

​Perp limit order, post-only

​Perp stop-loss with reduce-only

​Perp take-profit with reduce-only

​Stop-limit (limit triggered at stop price)

​7. Read positions and close

​Get open positions

​Close a position

​8. Funding and realized PnL

​Funding rate history

​Realized PnL

​9. Troubleshooting

​EAPI:Invalid nonce

​EGeneral:Permission denied

​authenticationError from krakenfutures

​Order rejected with wouldNotReducePosition

​Spot-purchased BTC shows up under “Staking/Yield Farming”

​Quick reference

Trading on Kraken

1. Set up your Kraken API keys

Spot key (api.kraken.com)

Futures key (futures.kraken.com)

2. Register the account in OEMS

Option A — at registration time

Option B — add the futures key later

3. Symbol conventions

4. Move funds to the right wallet

Check both wallets

Transfer spot → futures

5. Set leverage and margin mode (futures only)

Set leverage

Set margin mode

6. Place orders

Spot market buy

Perp limit order, post-only

Perp stop-loss with reduce-only

Perp take-profit with reduce-only

Stop-limit (limit triggered at stop price)

7. Read positions and close

Get open positions

Close a position

8. Funding and realized PnL

Funding rate history

Realized PnL

9. Troubleshooting

`EAPI:Invalid nonce`

`EGeneral:Permission denied`

`authenticationError` from `krakenfutures`

Order rejected with `wouldNotReducePosition`

Spot-purchased BTC shows up under “Staking/Yield Farming”

Quick reference