> ## 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.

# Closed-position PNL

> The endpoint returns one aggregated profit-and-loss record per closed [collateral](/glossary#balance-collateral) position for the authenticated account — the same closed-position PNL the trading terminal shows. Records are sorted by `closeDate` descending, then `positionId` descending. Use the optional `startDate` and `endDate` parameters to narrow the window; the filter applies to the position close time.

<Note>
The endpoint supports pagination via `limit` (default: 50, max: 100) and `offset` (default: 0); the sum of `offset` and `limit` must not exceed 10000. A response that returns fewer than `limit` records indicates the last page.
</Note>

<Note>
**Close-time windowing:** a position opened before the requested window but closed inside the window returns complete aggregates — fees, average prices, and closed size cover the full position lifetime, not only the requested window.
</Note>

<Warning>
Rate limit: 12000 requests/10 sec.
</Warning>


POST

<select value={baseUrl} onChange={(function (e) {
setBaseUrl(e.target.value);
})} onClick={(function (e) {
e.stopPropagation();
})}><option value="https://whitebit.com">[https://whitebit.com](https://whitebit.com)</option>
<option value="https://whitebit.eu">[https://whitebit.eu](https://whitebit.eu)</option></select>

Copy URL

Copy URL

## Related resources

* [Positions history](/api-reference/trading/positions-history) — View per-event position state changes
* [Open positions](/api-reference/trading/open-positions) — List current open positions
* [Close position](/api-reference/trading/close-position) — Close an open position
* [Funding history](/api-reference/trading/funding-history) — Review funding payments on positions


## OpenAPI

````yaml openapi/private/http-trade-v4.yaml POST /api/v4/collateral-account/positions/closed-pnl
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
  - url: https://whitebit.tr
    description: WhiteBIT TR Server
  - url: https://whitebit.ge
    description: WhiteBIT GE 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/positions/closed-pnl:
    post:
      tags:
        - Collateral Trading
      summary: Closed-position PNL
      description: >
        The endpoint returns one aggregated profit-and-loss record per closed
        [collateral](/glossary#balance-collateral) position for the
        authenticated account — the same closed-position PNL the trading
        terminal shows. Records are sorted by `closeDate` descending, then
        `positionId` descending. Use the optional `startDate` and `endDate`
        parameters to narrow the window; the filter applies to the position
        close time.


        <Note>

        The endpoint supports pagination via `limit` (default: 50, max: 100) and
        `offset` (default: 0); the sum of `offset` and `limit` must not exceed
        10000. A response that returns fewer than `limit` records indicates the
        last page.

        </Note>


        <Note>

        **Close-time windowing:** a position opened before the requested window
        but closed inside the window returns complete aggregates — fees, average
        prices, and closed size cover the full position lifetime, not only the
        requested window.

        </Note>


        <Warning>

        Rate limit: 12000 requests/10 sec.

        </Warning>
      operationId: getClosedPositionsPnl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                startDate:
                  type: integer
                  description: >-
                    Start of the query window as a Unix timestamp in seconds,
                    applied to the position close time. Optional, no default.
                    Must be ≤ `endDate`.
                  example: 1778000000
                endDate:
                  type: integer
                  description: >-
                    End of the query window as a Unix timestamp in seconds,
                    applied to the position close time. Optional, no default.
                    Must be ≥ `startDate` and ≤ `now + 1s`.
                  example: 1778100000
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 50
                  description: >-
                    Maximum number of records to return. Default: `50`. Minimum:
                    `1`. Maximum: `100`.
                  example: 50
                offset:
                  type: integer
                  minimum: 0
                  default: 0
                  description: >-
                    Number of records to skip. Default: `0`. The sum of `offset`
                    and `limit` must not exceed 10000.
                  example: 0
                request:
                  type: string
                  example: '{{request}}'
                nonce:
                  type: integer
                  example: 1594297865000
            example:
              startDate: 1778000000
              endDate: 1778100000
              limit: 50
              offset: 0
              request: '{{request}}'
              nonce: 1594297865000
      responses:
        '200':
          description: >-
            Successful response - returns an array with one aggregated record
            per closed position, sorted by `closeDate` descending, then
            `positionId` descending. Returns an empty array when no closed
            positions match the filters.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    positionId:
                      type: integer
                      description: Unique identifier of the closed position.
                      example: 111
                    market:
                      type: string
                      description: 'Market of the position. Format: `BASE_QUOTE`.'
                      example: BTC_USDT
                    grossPnl:
                      type: string
                      description: >-
                        Realized profit and loss of the position before funding.
                        Trading fees are already deducted from the value;
                        `totalTradeFee` is informational and must not be
                        subtracted again.
                      example: '43.85'
                    netPnl:
                      type: string
                      description: >-
                        Net profit and loss of the position: `grossPnl` minus
                        `totalFunding`.
                      example: '42.6'
                    totalTradeFee:
                      type: string
                      description: >-
                        Sum of trading fees across all fills of the position,
                        both opening and closing. Informational — already
                        reflected in `grossPnl` and `netPnl`.
                      example: '6.15'
                    totalFunding:
                      type: string
                      description: Cumulative funding fee over the whole position lifetime.
                      example: '1.25'
                    avgEntryPrice:
                      type: string
                      description: >-
                        Volume-weighted average price of the fills that
                        increased the position, trimmed to the market money
                        precision.
                      example: '61000'
                    avgExitPrice:
                      type: string
                      description: >-
                        Volume-weighted average price of the fills that reduced
                        the position, trimmed to the market money precision.
                      example: '62000'
                    closedSize:
                      type: string
                      description: >-
                        Total closed volume in base currency — the sum of fills
                        that reduced the position.
                      example: '0.05'
                    amount:
                      type: string
                      description: >-
                        Remaining position size. Always returns `"0"` — a closed
                        position holds no size.
                      example: '0'
                    side:
                      type: string
                      enum:
                        - LONG
                        - SHORT
                        - BOTH
                      description: >-
                        Position direction. Returns `BOTH` for positions opened
                        with hedge mode disabled. See
                        [positionSide](/glossary#position-side).
                      example: LONG
                    isHedge:
                      type: boolean
                      description: >-
                        Whether the position was opened in [hedge
                        mode](/glossary#hedge-mode).
                      example: true
                    openDate:
                      type: integer
                      description: Position open time as a Unix timestamp in seconds.
                      example: 1778000000
                    closeDate:
                      type: integer
                      description: >-
                        Position close time as a Unix timestamp in seconds.
                        Primary sort key, descending.
                      example: 1778077400
              example:
                - positionId: 111
                  market: BTC_USDT
                  grossPnl: '43.85'
                  netPnl: '42.6'
                  totalTradeFee: '6.15'
                  totalFunding: '1.25'
                  avgEntryPrice: '61000'
                  avgExitPrice: '62000'
                  closedSize: '0.05'
                  amount: '0'
                  side: LONG
                  isHedge: true
                  openDate: 1778000000
                  closeDate: 1778077400
                - positionId: 98
                  market: ETH_USDT
                  grossPnl: '-82.425'
                  netPnl: '-83.225'
                  totalTradeFee: '7.425'
                  totalFunding: '0.8'
                  avgEntryPrice: '2500'
                  avgExitPrice: '2450'
                  closedSize: '1.5'
                  amount: '0'
                  side: BOTH
                  isHedge: false
                  openDate: 1777900000
                  closeDate: 1778050000
        '400':
          description: >
            Inner validation failed


            Error codes:

            - `30` - default validation error code (invalid pagination — `limit`
            outside 1–100, or `offset` + `limit` above 10000 — or a date filter
            that violates `startDate` ≤ `endDate` ≤ `now + 1s`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
        '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)).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.