> ## 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.
# Funding history
> Retrieve funding rate payment history for collateral trading positions via the WhiteBIT V4 API.
* [Open positions](/api-reference/collateral-trading/open-positions) — List current open positions
* [Positions history](/api-reference/collateral-trading/positions-history) — View closed position history
* [Collateral account summary](/api-reference/collateral-trading/collateral-account-summary) — View account-level margin and equity
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/collateral-account/funding-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/collateral-account/funding-history:
post:
tags:
- Collateral Trading
summary: Funding History
description: >
The endpoint returns the funding rate payment history for
[collateral](/glossary#balance-collateral) positions. Each record
includes the funding rate, settlement price, position amount, and the
resulting funding payment. Use the optional `market` parameter to filter
results to a single trading pair. The response supports pagination via
`limit` and `offset` parameters. Results are ordered by funding time
(`fundingTime`), newest first.
Rate limit: 12000 requests/10 sec.
This endpoint supports pagination. Use `limit` (default: 100) and
`offset` (default: 0) to page through results. The response does not
include a `total` field — detect the last page when `records.length <
limit`. An empty `records` array means you have paged past the end;
receiving exactly `limit` records does not guarantee that another page
exists.
- `30` - default validation error code (invalid pagination — `limit` outside 1–100 or negative `offset`)
- `31` - market validation failed (the `market` filter is unknown or not available for collateral trading)
operationId: getFundingHistory
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
market:
type: string
description: |
Filter by specific market. For example: BTC_PERP
If not specified, returns funding history for all markets.
example: BTC_PERP
limit:
type: integer
description: Number of records to return
example: 100
default: 100
offset:
type: integer
description: Number of records to skip
example: 0
default: 0
request:
type: string
description: Request signature
example: '{{request}}'
nonce:
type: integer
description: Unique request identifier
example: 1594297865000
example:
market: BTC_PERP
limit: 100
offset: 0
request: '{{request}}'
nonce: 1594297865000
responses:
'200':
description: Successful response - returns paginated funding history
content:
application/json:
schema:
type: object
properties:
records:
type: array
description: Array of funding history entries
items:
type: object
properties:
market:
type: string
description: Market name
example: BTC_PERP
fundingTime:
type: string
description: Funding time in Unix timestamp format
example: '1734451200'
fundingRate:
type: string
description: Funding rate applied
example: '0.00017674'
fundingAmount:
type: string
description: Funding amount paid or received
example: '-0.171053531892'
positionAmount:
type: string
description: Position amount at funding time
example: '0.019'
settlementPrice:
type: string
description: Settlement price used for funding calculation
example: '50938.2'
rateCalculatedTime:
type: string
description: >-
Time when the funding rate was calculated in Unix
timestamp format
example: '1734364800'
limit:
type: integer
description: Number of records per page
example: 100
offset:
type: integer
description: Number of records skipped
example: 0
example:
records:
- market: BTC_PERP
fundingTime: '1734451200'
fundingRate: '0.00017674'
fundingAmount: '-0.171053531892'
positionAmount: '0.019'
settlementPrice: '50938.2'
rateCalculatedTime: '1734364800'
- market: BTC_PERP
fundingTime: '1734451200'
fundingRate: '-0.000177877800093587'
fundingAmount: '-0.0054997859133136'
positionAmount: '-0.001'
settlementPrice: '30918.9'
rateCalculatedTime: '1734364800'
limit: 100
offset: 0
'422':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service temporarily unavailable
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
components:
schemas:
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)).
````