WhiteBIT API Changelog

bankBic parameter for SEPA and bank-rail fiat withdrawals

New bankBic request parameter on POST /api/v4/main-account/withdraw and POST /api/v4/main-account/withdraw-payThe withdrawal endpoints now accept a bankBic parameter carrying the beneficiary bank’s BIC (SWIFT) code. It is required when the fiat provider is one of SEPA, SEPA_CLEAR_JUNCTION, SEPA_BCB_GROUP, FINCI, ZEN, or BANKING_CIRCLE, and identifies the destination bank for bank-rail payouts.

Create Withdraw Request

Create withdraw request (specific amount)

Funding cap and floor on futures markets list

New funding_cap and funding_floor fields on GET /api/v4/public/futuresEach futures market entry now returns the bounds that the funding rate can reach: funding_cap (upper) and funding_floor (lower). Use the fields to model worst-case funding costs in trading algorithms instead of hardcoding exchange-wide limits. Both fields are decimal strings served from the last successfully refreshed funding snapshot, so a temporary source outage does not drop the values; both return null only when no snapshot has been loaded since service start.

Available futures markets list

Funding history

Delisting date on Market Info

delistedAt field on GET /api/v4/public/marketsEvery market entry carries delistedAt — the announced delisting date as a Unix timestamp in seconds, or null when no delisting is announced. The field has been live since June 2026; this entry marks the point it became documented. A market with an announced delisting stays tradeable until the delisting runs; once the delisting runs, the platform cancels the active orders on the market and drops the market from the response. An announcement can be rescheduled or canceled, so read the value on each poll rather than caching the value for the lifetime of an integration.

Market info

Query delisting orders

Closed-position PNL on Collateral Trading

New POST /api/v4/collateral-account/positions/closed-pnl endpointThe Collateral Trading API now returns one aggregated profit-and-loss record per closed position — the same closed-position PNL the trading terminal shows. Each record carries grossPnl (realized PNL with trading fees already deducted), netPnl (grossPnl minus totalFunding), volume-weighted average entry and exit prices, total closed size, and informational fee totals. The optional startDate/endDate window filters by position close time, and a position opened before the window still returns complete lifetime aggregates. The amount field always returns "0" for closed positions.

Closed-position PNL

Positions history

RPI maker fee premiums on Query Market Fees

New rpi_maker_fee_premium and futures_rpi_maker_fee_premium fields on POST /api/v4/market/feeThe Query Market Fees response now returns the RPI maker fee premium — an additional fee component applied on top of the maker rate when a Retail Price Improvement (RPI) order executes. rpi_maker_fee_premium covers spot and margin markets; futures_rpi_maker_fee_premium covers futures markets. The effective RPI maker rate equals the base maker rate plus the applicable premium. Both fields return null when the RPI order mode is not enabled for the account or when no premium is configured.

Query market fees

Glossary — Retail Price Improvement

Express Withdraw for B2B partners

New POST /api/v4/main-account/express-withdraw/token endpoint for B2B partnersExpress Withdraw lets an approved B2B partner charge a specific amount from a WhiteBIT user’s balance through a signed, single-use payment token valid for 90 seconds. The partner integrates one endpoint; the user confirms the exact ticker and amount on a WhiteBIT-hosted page, and the funds settle instantly, off-chain, and fee-free into the partner’s Main balance.

Express Withdraw is not available to everyone: the endpoints are available only for B2B partner services and require a separate approval process. Request access at https://institutional.whitebit.com/.

Create express withdraw token

Payment Integration guide

Glossary — Express Withdraw

Granted permissions on OAuth API key info

New permissions array on GET /oauth2/api-key/infoGET /oauth2/api-key/info now returns a permissions array alongside exists, isEnabled, and externalId. Each entry is a permission group with a locale-independent name (for partner-side logic), a locale-dependent title (display only), and a urls list of { url, enable } pairs reflecting what the user granted during the OAuth handshake. The array is empty when no key exists; for a disabled key the array still reflects the grant-time permission set, so the partner can show the original scope.

Check key existence

Fast API Key integration guide

Abbreviated Self-Trade Prevention mode values

stp accepts cb, cn, co; long-form values deprecatedThe stp parameter on trade endpoints now uses abbreviated mode values: cb (cancel both), cn (cancel new), and co (cancel old); no is unchanged. The legacy values cancel_both, cancel_new, and cancel_old are deprecated. The long-form values remain accepted with identical behavior until a deprecation deadline is announced, after which the API rejects the long-form values. Responses always return the abbreviated form, regardless of which variant the request used. The parameter is documented on the five spot order endpoints (limit, market, stock market, stop-limit, stop-market) and the five collateral order endpoints (limit, market, stop-limit, trigger-market, OCO).

Self-Trade Prevention

Create Limit Order

Collateral Limit Order

Glossary — STP

Travel Rule API

New endpoints and structured format for Travel Rule complianceThe Travel Rule API enables B2B clients to submit originator and beneficiary data for cryptocurrency transactions as required by FATF and MiCA regulations. Available for accounts registered in the European Economic Area (EEA).New endpoints:

POST /api/v4/travel-rule/vasps — Retrieve the list of available VASPs for travel rule submissions.
POST /api/v4/travel-rule/deposit/verification — Submit originator data for deposits pending verification.

Updated travelRule format on withdrawals:The travelRule object on POST /api/v4/main-account/withdraw now uses a structured format with walletType, beneficiary, and vasp objects. The legacy flat format is deprecated.

Travel Rule Overview

Get VASPs

Submit Deposit Verification

Create Withdraw Request

TradFi Futures markets on Market Info

New tradfiFutures market type and isTradFiFutures flag on GET /api/v4/public/markets

Coming soon: TradFi futures are not yet returned by the endpoint.

Once live, GET /api/v4/public/markets will return traditional-finance (TradFi) futures markets — futures contracts on traditional financial assets such as equities (for example, AAPL_USD). A TradFi market will carry type: tradfiFutures together with isTradFiFutures: true. Availability is region-gated: markets you are not eligible to trade are omitted from the response entirely and do not appear under any other market type.

Market Info

Markets concept

Glossary — TradFi futures

Retail flag on Create Limit Order and Bulk Limit Order

New retail request parameter enables API clients to take RPI-maker liquidityA new optional retail boolean parameter on POST /api/v4/order/new and POST /api/v4/order/bulk marks an order as a retail-source taker. A retail taker is eligible to match against orders submitted by RPI makers and may receive price improvement at execution. The retail designation was previously available only on non-API sources (web, mobile, TV); approved WaaS/CaaS clients can now take RPI orders via API.Validation:

retail=true requires the Retail flag enabled on the account; the API returns error code 42 otherwise.
retail=true cannot be combined with rpi=true; the API returns error code 41 otherwise.
The flag has no effect on postOnly=true orders, because post-only orders are makers and cannot be retail takers.

Create Limit Order

Bulk Limit Order

Order Parameter Rules

Glossary — Retail flag

Fast API Key via OAuth

New OAuth flow for partner-issued API keysPartner platforms can now issue a WhiteBIT API key on behalf of a WhiteBIT user through the OAuth API key consent flow. The flow uses Authorization Code with PKCE (S256), a 4-hour access token without refresh, and partner-scoped IP restrictions on the resulting key. Three new OAuth2 endpoints support the flow.New endpoints (global server only — https://whitebit.com):

GET /oauth2/api-key/info — Check whether a partner-issued API key already exists for the authenticated user and OAuth2 client pair.
GET /oauth2/api-key/{externalId}/secret — Retrieve the API secret once. Subsequent calls return 409.
DELETE /oauth2/api-key/{externalId} — Delete a partner-owned API key. Sends an email notification to the user.

New OAuth scopes: apikeys.create, apikeys.read, apikeys.delete.

Fast API Key integration guide

Check key existence

Retrieve key secret

Delete key

Position History API update

Breaking change: positionSide field removed from Position History responseThe POST /api/v4/collateral-account/positions/history endpoint no longer returns the positionSide field. Two new fields replace it: side (same enum as the removed field — LONG, SHORT, BOTH) and isHedge (a boolean indicating whether the position was opened in hedge mode). The combination lets you attribute closed-position records to a specific direction and account mode for P&L tracking, compliance reporting, and strategy reconstruction.Migration guide:

Replace any reader of positionSide from /positions/history with side. The enum is unchanged: LONG, SHORT, BOTH.
Read isHedge to determine whether the record was produced under hedge mode (true) or one-way mode (false).
Other endpoints that return positionSide (/positions/open, /conditional-orders, order-create requests) are unchanged.

Sunset date: April 29, 2026.Replacement: Use side and isHedge on the same endpoint. See v4 - Positions history.Impact: Integrations parsing the response of POST /api/v4/collateral-account/positions/history and reading positionSide must migrate to side and isHedge. Other endpoint integrations are not affected.

v4 - Positions History

Bulk cancel orders endpoint

Cancel up to 100 spot orders in a single requestThe new POST /api/v4/order/cancel/bulk endpoint cancels up to 100 spot orders in a single request. Each item identifies a target order by market plus exactly one of orderId or clientOrderId. The response array preserves the order of the input — response[i] corresponds to request.orders[i].

Cancel Bulk Orders

Reduce-only order parameter

Position-closing guarantee for collateral ordersA new reduceOnly boolean parameter for collateral order endpoints. When set to true, the order can only decrease or close an existing position — the order never increases the position or opens a new one.Behavior:

If the order amount exceeds the current position size, the system automatically reduces the order to match
The API returns error code 116 if no open position exists or the order direction matches the position direction
Pending reduce-only orders are auto-canceled with status AUTO_CANCELED_REDUCE_ONLY when the associated position closes

Supported on 6 collateral order creation endpoints:

Collateral Limit Order

Collateral Bulk Limit Order

Collateral Market Order

Collateral Stop-Limit Order

Collateral Trigger Market Order

Collateral OCO Order

The reduceOnly field also appears in the response of query active orders, query executed orders, and query conditional orders.WebSocket channels:The reduce_only field is added to the Orders Pending and Orders Executed channels — both in query responses and real-time update events.See Order Types — Reduce-only orders for full details.

clientOrderId uniqueness scope change

Breaking change: clientOrderId is now unique only among open orders, not for a fixed time windowThe uniqueness rule for clientOrderId on spot and collateral order creation changed. Uniqueness is now enforced only among the account’s open (pending) orders on the same market. Once a previous order is filled or canceled, the same clientOrderId can be reused, including on the same market. The previous time-based uniqueness window no longer applies.Impact on retry and deduplication logic:Integrations that relied on a fixed-time uniqueness window to suppress duplicate submissions should not assume a resubmitted clientOrderId will be rejected after the original order leaves the open state. Before resubmitting an order whose response was not received, check whether an order with that clientOrderId already exists:

Query unexecuted orders (POST /api/v4/orders) — search open orders by clientOrderId.
Query executed orders (POST /api/v4/trade-account/order/history) — search filled and canceled orders by clientOrderId.

If the order is found in either result, the original submission was accepted and no retry is needed.

Client Order ID guide

Create Limit Order

Query unexecuted orders

Query executed orders

Previous Changes

Auto-Deleveraging (ADL)

Futures-market final-stage liquidation mechanismWhiteBIT futures markets now apply Auto-Deleveraging as the final stage of liquidation, activated only when standard market liquidity cannot fully cover a liquidated position. ADL closes profitable counterparty positions on the opposite side at a calculated price, ranked by an internal Rating, ensuring no user balance becomes negative.Integrator-relevant facts:

ADL fills carry source: "adl" on the ordersExecuted WebSocket stream and a client_order_id of the form adl_<order_id>_!. Over REST order history — where the payload does not include source — match the adl_ client_order_id prefix. The reduce_only flag remains false on ADL inserts, so do not use it for identification.
Pending reduce-only orders auto-cancel with the existing AUTO_CANCELED_REDUCE_ONLY status when ADL closes a counterparty position. No ADL-specific cancel status was introduced.
ADL Grade (0–4) indicates a position’s place in the per-market ADL ranking, with Grade 4 corresponding to the asymptotic top 5% of ranked positions.

Auto-Deleveraging Concept

Help Center Article

Mining Pool API

Comprehensive mining pool management endpointsIntroduced a complete Mining Pool API with 10 endpoints for managing mining operations, including account monitoring, payout configuration, worker management, and watcher link generation.Public endpoints:

Pool statistics and connection information

Mining account management:

Reward history with pagination
Account-level hashrate monitoring with configurable intervals (5m, 1h, 24h)
Fee and stratum connection details

Payout configuration:

Get and set payout destination (main balance or external BTC address)
Support for all standard Bitcoin address formats

Worker monitoring:

List online workers with pagination
Individual worker hashrate history

Watcher links:

Create read-only access links with granular permissions (dashboard, rewards, workers)
Configurable expiration periods (1h, 24h, 7d, always)
List active watcher links

All authenticated endpoints require the MINING_POOL feature to be enabled on the API key.

Pool Overview

Get Rewards

Account Hashrate

Get Payout Destination

Set Payout Destination

Miner Info

Worker Names

Worker Hashrate

Create Watcher Link

List Watcher Links

Mining Account Management

Create and list mining accountsAdded endpoints to create and manage mining pool accounts programmatically.Account creation:

Create named mining accounts with optional referral codes
Unique account names with alphanumeric and underscore support
Automatic validation for duplicate names

Account listing:

Retrieve all mining accounts or filter by name
Results sorted by creation date (newest first)

All endpoints require the MINING_POOL feature to be enabled on the API key.

Create Mining Account

Get Mining Accounts

API Documentation Updates

Sub-account transfer endpoints: add transactionId for correlationThe response of /api/v4/sub-account/transfer and /api/v4/sub-account/transfer/history includes the transactionId field.Use transactionId to correlate transfer operations with transfer history records.The id field in transfer history is deprecated. Replace id with transactionId.

Sub-Account Transfer

Get Sub-Account Transfer History

Documentation Updates

Clarified Book Ticker stream update intervalRefined the description of the Book Ticker WebSocket stream to explicitly state instant BBO snapshot with incremental updates.

ws - Book Ticker

Flex Earn Endpoints

Introduced Smart Flex private endpointsAdded documentation for Smart Flex (Flex Earn) endpoints: list plans, manage investments, view histories, and configure auto-reinvestment.

v4 - Get Flex Plans

v4 - Get User Flex Investments

v4 - Get Flex Investment History

v4 - Get Flex Payment History

v4 - Create Flex Investment

v4 - Withdraw from Flex Investment

v4 - Close Flex Investment

v4 - Update Flex Auto-Reinvestment

API Documentation Updates

Enhanced Query executed orders documentationUpdated documentation for /api/v4/trade-account/order/history endpoint to clarify date range filtering capabilities with startDate and endDate parameters.

Trade API - Query executed orders

Public API Update

New Funding History endpointAdded new endpoint /api/v4/public/funding-history/{market} to retrieve funding rate history for futures markets.

Public API - Funding History

Private API Update

Issue JWT Token for Private APINew endpoint to issue JWT token for private API access.

v4 - Issue JWT Token

Issue card token using JWTNew endpoint to issue a card token using JWT for secure transactions.

v4 - Issue Card Token

Withdraw endpoint updateAddress now accepts card tokens for withdrawals.

v4 - Create Withdraw Request

Public WebSocket Update

Added BookTicker WebSocket streamNew bookTicker stream added to WebSocket API, providing real-time updates of best bid/ask prices and quantities for markets. Includes subscription (bookTicker_subscribe) and unsubscription (bookTicker_unsubscribe) methods for managing the data feed.

ws - Book Ticker

Trade Engine Update

Event time and update id introduced in WebSocket eventsWebSocket events now include event_time and update_id fields. The event_time field provides the timestamp of the event, while the update_id field is a unique identifier for each update, allowing for better tracking and synchronization of events.

ws - Market Depth Subscribe

Hedge mode supportThe Hedge mode is now available for all users. This mode allows holding both long and short positions in the same asset simultaneously, providing greater flexibility in managing trades.

v4 - Collateral Limit Order

v4 - Collateral Stop Limit Order

v4 - Collateral Market Order

v4 - Collateral OCO Order

v4 - Collateral Trigger Market Order

v4 - Collateral Account Hedge Mode

v4 - Update Collateral Account Hedge Mode

ws - Orders Pending

ws - Orders Executed

ws - Positions

Queries Limited to the Last 6 MonthsTo enhance performance and focus on the most relevant data, the API limits data queries to the past 6 months. Data can be retrieved up to six months old from the current date.

v4 - Convert History

v4 - Executed order deals

v4 - Executed orders

v4 - Unexecuted (active) conditional orders

v4 - Collateral bulk limit order

v4 - Executed order history

v4 - Positions history

Withdraw update

HTTP Main V4 API - WithdrawThe paymentDescription field is now mandatory for withdrawal requests from whitebit-tr.com.

v4 - Withdraw

Travel Rule Update

HTTP Main V4 API - Travel RuleAdded new statuses DEPOSIT_TRAVEL_RULE_FROZEN (27) and DEPOSIT_TRAVEL_RULE_FROZEN_PROCESSING (28) to the deposit endpoint.

v4 - Get Deposit/Withdraw History

Convert History Update

HTTP Trade V4 API - ConvertAdded 30 days date range limit for convert history and default values for from and to parameters.

v4 - Convert History

Deposit and Withdrawal Updates

HTTP Main V4 API - Birth Date AdditionAdded beneficiary.birthDate field (Format: YYYY-MM-DD) to withdrawal requests and customer.birthDate (Format: YYYY-MM-DD) to deposit requests.

​bankBic parameter for SEPA and bank-rail fiat withdrawals

Create Withdraw Request

Create withdraw request (specific amount)

​Funding cap and floor on futures markets list

Available futures markets list

Funding history

​Delisting date on Market Info

Market info

Query delisting orders

​Closed-position PNL on Collateral Trading

Closed-position PNL

Positions history

​RPI maker fee premiums on Query Market Fees

Query market fees

Glossary — Retail Price Improvement

​Express Withdraw for B2B partners

Create express withdraw token

Payment Integration guide

Glossary — Express Withdraw

​Granted permissions on OAuth API key info

Check key existence

Fast API Key integration guide

​Abbreviated Self-Trade Prevention mode values

Self-Trade Prevention

Create Limit Order

Collateral Limit Order

Glossary — STP

​Travel Rule API

Travel Rule Overview

Get VASPs

Submit Deposit Verification

Create Withdraw Request

​TradFi Futures markets on Market Info

Market Info

Markets concept

Glossary — TradFi futures

​Retail flag on Create Limit Order and Bulk Limit Order

Create Limit Order

Bulk Limit Order

Order Parameter Rules

Glossary — Retail flag

​Fast API Key via OAuth

Fast API Key integration guide

Check key existence

Retrieve key secret

Delete key

​Position History API update

v4 - Positions History

​Bulk cancel orders endpoint

Cancel Bulk Orders

​Reduce-only order parameter

Collateral Limit Order

Collateral Bulk Limit Order

Collateral Market Order

Collateral Stop-Limit Order

Collateral Trigger Market Order

Collateral OCO Order

​clientOrderId uniqueness scope change

Client Order ID guide

Create Limit Order

Query unexecuted orders

Query executed orders

​Previous Changes

​Auto-Deleveraging (ADL)

Auto-Deleveraging Concept

Help Center Article

​Mining Pool API

Pool Overview

Get Rewards

Account Hashrate

Get Payout Destination

Set Payout Destination

Miner Info

Worker Names

Worker Hashrate

Create Watcher Link

List Watcher Links

​Mining Account Management

Create Mining Account

Get Mining Accounts

bankBic parameter for SEPA and bank-rail fiat withdrawals

Funding cap and floor on futures markets list

Delisting date on Market Info

Closed-position PNL on Collateral Trading

RPI maker fee premiums on Query Market Fees

Express Withdraw for B2B partners

Granted permissions on OAuth API key info

Abbreviated Self-Trade Prevention mode values

Travel Rule API

TradFi Futures markets on Market Info

Retail flag on Create Limit Order and Bulk Limit Order

Fast API Key via OAuth

Position History API update

Bulk cancel orders endpoint

Reduce-only order parameter

clientOrderId uniqueness scope change

Previous Changes

Auto-Deleveraging (ADL)

Mining Pool API

Mining Account Management

API Documentation Updates

Documentation Updates

Flex Earn Endpoints

API Documentation Updates

Public API Update

Private API Update

Public WebSocket Update

Trade Engine Update

Withdraw update

Travel Rule Update

Convert History Update

Deposit and Withdrawal Updates