> ## 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 order history
> Retrieve the history of fully and partially executed spot orders via the WhiteBIT V4 API.
* [Query executed orders](/api-reference/spot-trading/query-executed-orders) — view executed order history
* [Query executed order deals](/api-reference/spot-trading/query-executed-order-deals) — view individual trade fills
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/trade-account/executed-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/executed-history:
post:
tags:
- Spot Trading
summary: Query executed order history
description: >
The endpoint retrieves executed order history for all trading types —
spot, margin, and futures — across all markets. Can be filtered by a
single market if needed. Results are ordered by trade 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.
The endpoint can retrieve data not older than 6 months from the current
month. For older data, use the Report on the History page.
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.
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": {
"limit": ["Limit field should be an integer."],
"offset": ["Offset field should be an integer."]
}
}
```
```json
{
"code": 31,
"message": "Validation failed",
"errors": {
"market": ["Market field format is invalid."]
}
}
```
```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: getExecutedOrderHistory
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
market:
type: string
description: 'Requested [market](/glossary#market). Example: BTC_USDT'
example: BTC_USDT
clientOrderId:
type: string
description: >-
Look up by custom client order identifier. When supplied,
the endpoint switches to single-order lookup mode and
returns the matching order's deal history. Returns `422`
with `"OrderHistory was not found."` if no order matches on
the calling account.
example: customId11
startDate:
type: integer
description: Start date in Unix-time format
example: 1593233939
endDate:
type: integer
description: End date in Unix-time format
example: 1593233939
offset:
type: integer
default: 0
description: 'Starting line index (OFFSET). Default: 0, Min: 0'
example: 0
limit:
type: integer
minimum: 1
maximum: 500
default: 50
description: >-
LIMIT is a special clause used to limit records a particular
query can return. Default: 50, Min: 1, Max: 500
example: 50
request:
type: string
example: '{{request}}'
nonce:
type: integer
example: 1594297865000
responses:
'200':
description: >-
Executed order history. Response shape depends on whether the market
filter is provided: with market filter returns a flat array; without
market filter returns an object keyed by market name.
content:
application/json:
schema:
oneOf:
- description: >-
Returned when the market request parameter is provided.
Flat array of deal objects for the specified market.
type: array
items:
$ref: '#/components/schemas/ExecutedDeal'
- description: >-
Returned when no market filter is provided. Object keyed
by market name (e.g., "BTC_USDT"), each value is an array
of deal objects for that market.
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/ExecutedDeal'
'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:
ExecutedDeal:
type: object
properties:
id:
type: integer
description: Unique deal identifier assigned by the matching engine.
clientOrderId:
type: string
description: >-
Custom order identifier supplied in the original order request.
Returns an empty string when not specified.
time:
type: number
description: Unix timestamp of the deal execution, with microsecond precision.
side:
type: string
enum:
- buy
- sell
description: 'Order side that produced the deal. Possible values: `buy`, `sell`.'
role:
type: integer
description: >-
Execution role in the deal. `1` = maker (order was resting on the
book), `2` = taker (order matched immediately).
amount:
type: string
description: >-
Executed quantity in base (stock) currency, regardless of order
direction.
price:
type: string
description: Execution price per unit in quote currency.
deal:
type: string
description: Total deal value in quote (money) currency. Equals `amount * price`.
fee:
type: string
description: >-
Fee charged for the deal, denominated in the asset specified by
`feeAsset`.
orderId:
type: integer
description: Identifier of the parent order that produced the deal.
feeAsset:
type: string
description: Currency ticker of the asset used to pay the trading fee.
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)).
````