> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Query executed orders
> Query recently executed spot orders with optional filtering by market via the WhiteBIT V4 API.
* [Query executed order deals](/api-reference/spot-trading/query-executed-order-deals) — view individual trade fills
* [Query executed order history](/api-reference/spot-trading/query-executed-order-history) — view full execution history
* [Query unexecuted orders](/api-reference/spot-trading/query-unexecuted-orders) — list open orders
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/trade-account/order/history
openapi: 3.0.3
info:
title: Private HTTP API V4 - Collateral Trading
description: |
WhiteBIT Private HTTP API V4 for collateral/margin trading operations.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
For receiving responses from API calls please use http method POST.
Authentication required for all endpoints.
version: 4.0.0
license:
name: WhiteBIT Terms of Service
url: https://whitebit.com/terms
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Collateral Trading
description: Endpoints for collateral/margin trading operations
- name: Spot Trading
description: Endpoints for spot trading operations
- name: Market Fee
description: Endpoints for querying trading fees
paths:
/api/v4/trade-account/order/history:
post:
tags:
- Spot Trading
summary: Query executed orders
description: >
The endpoint retrieves the history of executed and cancelled orders. The
response groups orders by market name. Use the `market` parameter to
filter by a single trading pair, or omit the parameter to retrieve
orders across all markets. The endpoint supports pagination with `limit`
(default 50, max 500) and `offset` parameters. Results are ordered by
time, newest first.
Rate limit: 12000 requests/10 sec.
Requests with `limit` values above 100 return large payloads. Use high
limits only when necessary and ensure the client application can handle
large response sizes.
This endpoint supports pagination. Use `limit` (default: 50, max: 500)
and `offset` (default: 0) to page through results. The response does not
include a `total` field — detect the last page when fewer than `limit`
records are returned (sum the records across all markets when no
`market` filter is set). An empty response means you have paged past the
end; receiving exactly `limit` records does not guarantee that another
page exists.
**Date filter window:** the maximum span between `startDate` and
`endDate` is **31 days**, and the earliest reachable date is **6 months
ago (00:00 UTC)**. Requests that exceed the 31-day window or fall below
the 6-month floor are rejected with a validation error. `endDate` values
greater than the current time are silently clamped to `now`.
For B2B accounts, canceled order recording is disabled by default. To
include canceled orders in the history, contact support to enable
canceled order storage.
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"orderHistory": ["OrderHistory was not found."]
}
}
```
Returned when `clientOrderId` is supplied but no order matches it on the
calling account.
operationId: getOrderHistory
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
market:
type: string
description: >-
Trading pair to filter by. Format: `BASE_QUOTE` (e.g.,
`BTC_USDT`). Omit to retrieve orders across all markets.
example: BTC_USDT
clientOrderId:
type: string
description: >-
Look up a specific order by the custom client identifier.
When supplied, the endpoint switches to single-order lookup
mode and the `startDate`, `endDate`, and `status` filters
are ignored. Returns `422` with `"OrderHistory was not
found."` if no order matches. Ignored when `orderId` is also
provided.
example: customId11
orderId:
type: integer
description: >-
Look up a specific order by the exchange-assigned
identifier. When supplied, the endpoint switches to
single-order lookup mode and the `startDate`, `endDate`, and
`status` filters are ignored. Returns an empty result on no
match (no `422`). Takes precedence over `clientOrderId` when
both are supplied.
example: 4986126152
status:
type: string
enum:
- ALL
- FILLED
- CANCELED
- PARTIALLY_FILLED
default: ALL
description: >-
Filter list-mode results by order status. Ignored when
`orderId` or `clientOrderId` is supplied.
example: FILLED
startDate:
type: integer
description: >-
Start of the query window as a Unix timestamp in seconds.
Default: `now - 1 month`. The earliest reachable date is 6
months ago (00:00 UTC) — requests with an older `startDate`
are rejected with a validation error.
example: 1697000000
endDate:
type: integer
description: >-
End of the query window as a Unix timestamp in seconds.
Default: `now`. Values greater than the current time are
silently clamped to `now`. The maximum span between
`startDate` and `endDate` is 31 days.
example: 1699000000
offset:
type: integer
default: 0
minimum: 0
description: 'Number of records to skip. Default: `0`.'
example: 0
limit:
type: integer
minimum: 1
maximum: 500
default: 50
description: >-
Maximum number of records to return. Default: `50`. Minimum:
`1`. Maximum: `500`.
example: 50
request:
type: string
example: '{{request}}'
nonce:
type: integer
example: 1594297865000
responses:
'200':
description: >-
Successful response - returns order history grouped by market. Empty
response if order is not yours.
content:
application/json:
schema:
type: object
description: >-
Object with market names as keys, each containing an array of
orders
additionalProperties:
type: array
items:
type: object
properties:
amount:
type: string
description: >-
Order quantity in base currency for limit orders, or
in quote currency for buy market orders.
example: '0.0009'
price:
type: string
description: >-
Limit price per unit in quote currency. Returns `"0"`
for market orders.
example: '40000'
type:
type: string
description: >-
Order type. Possible values: `limit`, `market`, `stock
market`, `stop limit`, `stop market`.
example: limit
id:
type: integer
description: >-
Unique order identifier assigned by the matching
engine.
example: 4986126152
clientOrderId:
type: string
description: >-
Custom client order identifier supplied in the
request. Returns an empty string when not specified.
example: customId11
side:
type: string
description: 'Order side. Possible values: `buy`, `sell`.'
enum:
- buy
- sell
example: sell
ctime:
type: number
description: >-
Unix timestamp in seconds (UTC) of order creation,
with microsecond precision.
example: 1597486960.311311
ftime:
type: number
description: >-
Unix timestamp when the order reached its final status
(FILLED or CANCELLED). For partially-filled orders
that are subsequently cancelled, the timestamp
reflects the cancellation time, not the last fill
time.
example: 1597486960.311332
dealFee:
type: string
description: >-
Cumulative trading fee charged for filled portions,
denominated in the fee asset.
example: '0.041258268'
dealStock:
type: string
description: Filled amount in base (stock) currency.
example: '0.0009'
dealMoney:
type: string
description: Filled amount in quote (money) currency.
example: '41.258268'
postOnly:
type: boolean
description: >-
Post-only flag. When `true`, the order executed only
as a maker order.
example: false
ioc:
type: boolean
description: >-
Immediate-or-cancel flag. When `true`, the order
executed available quantity immediately and cancelled
the rest.
example: false
activated:
type: integer
description: >-
Stop/conditional orders only — Unix timestamp at which
the trigger price was reached and the order was
activated. Absent for unconditional orders.
example: 1597486960
activationPrice:
type: string
description: >-
Stop/conditional orders only — the trigger price that,
when reached, activates the order. Absent for
unconditional orders.
example: '39500'
activationCondition:
type: string
description: >-
Stop/conditional orders only — comparison operator
that decides when `activationPrice` is met. Absent for
unconditional orders.
example: <=
status:
$ref: '#/components/schemas/OrderStatus'
feeAsset:
type: string
description: >-
Currency ticker of the asset used to pay the trading
fee.
example: USDT
positionSide:
type: string
description: >-
Position side for futures/margin orders. Omitted for
spot orders without position context.
example: BOTH
rpi:
type: boolean
description: >-
Retail Price Improvement flag. `true` when the order
used RPI pricing.
example: false
reduceOnly:
type: boolean
description: >-
Reduce-only flag. When `true`, the order could only
reduce or close an existing position. See
[reduce-only](/glossary#reduce-only).
example: false
example:
BTC_USDT:
- amount: '0.0009'
price: '40000'
type: limit
id: 4986126152
clientOrderId: customId11
side: sell
ctime: 1597486960.311311
ftime: 1597486960.311332
dealFee: '0.041258268'
dealStock: '0.0009'
dealMoney: '41.258268'
postOnly: false
ioc: false
status: CANCELED
feeAsset: USDT
positionSide: BOTH
rpi: false
reduceOnly: false
'400':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service temporarily unavailable
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
components:
schemas:
OrderStatus:
type: string
description: >-
Order lifecycle status. `NEW` — accepted, not yet matched. `FILLED` —
fully executed. `CANCELED` — canceled before execution. `PARTIAL_FILLED`
— partially executed, remainder still active. `PARTIAL_CANCELED` —
partially filled, remainder canceled. `CANCELED_TAKER_BAND` — partially
filled up to the taker band limit, remainder canceled to protect against
excessive order book slippage. `AUTO_CANCELED_REDUCE_ONLY` — pending
reduce-only order auto-canceled because the associated position was
closed. `AUTO_CANCELED_LIQUIDATION` — pending order auto-canceled
because the associated position was force-liquidated. `CANCELED_STP` —
order canceled by [Self-Trade
Prevention](/platform/self-trade-prevention).
example: FILLED
ErrorResponse:
type: object
properties:
code:
type: integer
description: Error code
example: 30
message:
type: string
description: Error message
example: Validation failed
errors:
type: object
additionalProperties:
type: array
items:
type: string
description: Detailed error information
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-TXC-APIKEY
description: The public WhiteBIT API key.
PayloadAuth:
type: apiKey
in: header
name: X-TXC-PAYLOAD
description: Base64-encoded JSON request body.
SignatureAuth:
type: apiKey
in: header
name: X-TXC-SIGNATURE
description: >-
HMAC-SHA512 signature of the payload, hex-encoded. Computed as
hex(HMAC-SHA512(payload, api_secret)).
````