> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raze.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Time-series FIFO PnL with unrealized valuation

> Time-series PnL with FIFO cost-basis and unrealized position valuation.
Each bucket includes cumulative **realized** PnL, **unrealized** PnL (open lots marked
from OHLCV closes), and **total** PnL (realized + unrealized) in SOL.

**Wallet-wide (no `mint`):** `from` and `to` (Unix seconds) are **required**. All trades
for the wallet up to `limit` (time-ordered) feed a single multi-token FIFO simulation.

**Per-token (`mint` set):** FIFO and marks apply **only to that token mint**. Use **either**
both `from` and `to`, **or** omit both to span **first trade on that mint** (bucket-aligned)
through **now**; the response echoes the resolved window as `from` / `to` when applicable.
One continuous series across exit and re-entry for the same mint (same methodology as
wallet-wide, sliced to one asset).


## Overview

FIFO time-series PnL in SOL. `realizedPnlSol` is the **per-bucket delta** — the realized PnL booked during that bucket, not a running cumulative total. `unrealizedPnlSol` (open lots marked from OHLCV) and `totalPnlSol` (`realized` + `unrealized`) are **point-in-time** values at the bucket. Wallet-wide and per-mint modes use the **same** accounting; per-mint is a slice of that engine for one `mint`.

## Requests

**Wallet-wide** — `from` and `to` (Unix seconds) are required:

```http theme={null}
GET /api/sol/wallets/{address}/pnl/history?from=1730995200&to=1731600000&resolution=1h
```

**Per-token, auto window** — first trade on that mint (hour/day aligned) through **now**; omit `from` and `to`:

```http theme={null}
GET /api/sol/wallets/{address}/pnl/history?mint=So11111111111111111111111111111111111111112&resolution=1h
```

**Per-token, explicit window:**

```http theme={null}
GET /api/sol/wallets/{address}/pnl/history?mint=So11111111111111111111111111111111111111112&from=1730995200&to=1731600000&resolution=1h
```

Optional: `limit` (default 50000) caps how many trades are read (globally for wallet-wide; per mint for `mint=`).

## Example responses

Wallet-wide (excerpt):

```json theme={null}
{
  "success": true,
  "address": "VJSDW6S74YXR4rRR9P4xwhMvLZJQMhrUb8XMFirUsy1",
  "resolution": "1h",
  "data": [
    {
      "bucket": "2024-11-14T10:00:00+00:00",
      "realizedPnlSol": 0.15,
      "unrealizedPnlSol": 0.02,
      "totalPnlSol": 0.17,
      "solPriceUsd": 245.3
    }
  ],
  "count": 1,
  "tradesProcessed": 420,
  "truncated": false,
  "tokensTracked": 12,
  "solPriceUsd": 246.5,
  "timestamp": "2024-11-14T12:05:00Z"
}
```

Per-mint with auto window (note `mint`, `from`, `to`, no `tokensTracked`):

```json theme={null}
{
  "success": true,
  "address": "VJSDW6S74YXR4rRR9P4xwhMvLZJQMhrUb8XMFirUsy1",
  "mint": "So11111111111111111111111111111111111111112",
  "from": 1730995200,
  "to": 1731600000,
  "resolution": "1h",
  "data": [
    {
      "bucket": "2024-11-07T16:00:00+00:00",
      "realizedPnlSol": 0,
      "unrealizedPnlSol": -0.05,
      "totalPnlSol": -0.05,
      "solPriceUsd": 168.2
    },
    {
      "bucket": "2024-11-07T17:00:00+00:00",
      "realizedPnlSol": 0.12,
      "unrealizedPnlSol": 0,
      "totalPnlSol": 0.12,
      "solPriceUsd": 169.0
    }
  ],
  "count": 2,
  "tradesProcessed": 28,
  "truncated": false,
  "solPriceUsd": 170.1,
  "timestamp": "2024-11-14T12:05:00Z"
}
```

When `truncated` is `true`, raise `limit` or narrow the time range; the FIFO replay may not include older trades.


## OpenAPI

````yaml openapi-spec/history.yaml get /api/sol/wallets/{address}/pnl/history
openapi: 3.0.3
info:
  title: Raze Database API
  description: >
    Paid subscription API for Solana transaction data and history.


    Also hosts write utilities (`/utils/sol/*`): token launch, transfer, burn,

    consolidate, fees claim/config, and agent initialize — previously on

    `router.raze.bot`. Mixer/distribute removed 2026-07-25.


    ## Batch Requests

    All endpoints with path parameters (mint, signer, address, tokenMint,
    ownerAddress) support batch queries

    via comma-separated values. For example:
    `/api/sol/trades/mint/mint1,mint2,mint3?limit=50`


    - Maximum 10 values per batch request

    - Each value must be a valid address (>= 32 characters)

    - Single values behave identically to non-batch requests

    - Batch response format: `{ "success": true, "results": { "value1": {...},
    "value2": {...} }, "count": N, "timestamp": "..." }`

    - Each key in `results` contains the full single-entity response

    - Queries run in parallel for maximum performance
  version: 1.0.0
servers:
  - url: https://api.raze.bot
    description: >-
      Raze global History API — GeoDNS routes to the nearest region
      automatically
security:
  - ApiKeyAuth: []
paths:
  /api/sol/wallets/{address}/pnl/history:
    get:
      summary: Time-series FIFO PnL with unrealized valuation
      description: >
        Time-series PnL with FIFO cost-basis and unrealized position valuation.

        Each bucket includes cumulative **realized** PnL, **unrealized** PnL
        (open lots marked

        from OHLCV closes), and **total** PnL (realized + unrealized) in SOL.


        **Wallet-wide (no `mint`):** `from` and `to` (Unix seconds) are
        **required**. All trades

        for the wallet up to `limit` (time-ordered) feed a single multi-token
        FIFO simulation.


        **Per-token (`mint` set):** FIFO and marks apply **only to that token
        mint**. Use **either**

        both `from` and `to`, **or** omit both to span **first trade on that
        mint** (bucket-aligned)

        through **now**; the response echoes the resolved window as `from` /
        `to` when applicable.

        One continuous series across exit and re-entry for the same mint (same
        methodology as

        wallet-wide, sliced to one asset).
      operationId: getWalletPnlHistory
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          example: VJSDW6S74YXR4rRR9P4xwhMvLZJQMhrUb8XMFirUsy1
        - name: mint
          in: query
          required: false
          schema:
            type: string
          description: >-
            Token mint (base58). When set, series is scoped to this mint only;
            `from`/`to` are both required unless both omitted (auto window).
          example: So11111111111111111111111111111111111111112
        - name: from
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Start timestamp (Unix seconds). Required when `mint` is omitted;
            with `mint`, omit together with `to` for auto window.
        - name: to
          in: query
          required: false
          schema:
            type: integer
          description: >-
            End timestamp (Unix seconds). Required when `mint` is omitted; with
            `mint`, omit together with `from` for auto window.
        - name: resolution
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 1d
            default: 1h
          description: Time bucket resolution
        - name: limit
          in: query
          schema:
            type: integer
            default: 50000
            maximum: 50000
          description: >-
            Maximum trades to process (wallet-wide uses global trade cap;
            per-mint uses cap on trades for that mint only)
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletPnlHistoryResponse'
              examples:
                walletWide:
                  summary: Wallet-wide (multi-token) bucket series
                  value:
                    success: true
                    address: VJSDW6S74YXR4rRR9P4xwhMvLZJQMhrUb8XMFirUsy1
                    resolution: 1h
                    data:
                      - bucket: '2024-11-14T10:00:00+00:00'
                        realizedPnlSol: 0.15
                        unrealizedPnlSol: 0.02
                        totalPnlSol: 0.17
                        solPriceUsd: 245.3
                      - bucket: '2024-11-14T11:00:00+00:00'
                        realizedPnlSol: 0.15
                        unrealizedPnlSol: -0.01
                        totalPnlSol: 0.14
                        solPriceUsd: 246.1
                    count: 2
                    tradesProcessed: 420
                    truncated: false
                    tokensTracked: 12
                    solPriceUsd: 246.5
                    timestamp: '2024-11-14T12:05:00Z'
                perMintAutoWindow:
                  summary: Single mint — omitted from/to (window = first trade → now)
                  value:
                    success: true
                    address: VJSDW6S74YXR4rRR9P4xwhMvLZJQMhrUb8XMFirUsy1
                    mint: So11111111111111111111111111111111111111112
                    from: 1730995200
                    to: 1731600000
                    resolution: 1h
                    data:
                      - bucket: '2024-11-07T16:00:00+00:00'
                        realizedPnlSol: 0
                        unrealizedPnlSol: -0.05
                        totalPnlSol: -0.05
                        solPriceUsd: 168.2
                      - bucket: '2024-11-07T17:00:00+00:00'
                        realizedPnlSol: 0.12
                        unrealizedPnlSol: 0
                        totalPnlSol: 0.12
                        solPriceUsd: 169
                    count: 2
                    tradesProcessed: 28
                    truncated: false
                    solPriceUsd: 170.1
                    timestamp: '2024-11-14T12:05:00Z'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Database error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WalletPnlHistoryResponse:
      type: object
      properties:
        success:
          type: boolean
        address:
          type: string
        mint:
          type: string
          description: Present when the request scoped PnL to a single token mint.
        from:
          type: integer
          description: >-
            Resolved window start (Unix seconds); included for mint-scoped
            responses with an explicit or auto-derived range.
        to:
          type: integer
          description: >-
            Resolved window end (Unix seconds); included for mint-scoped
            responses.
        resolution:
          type: string
          enum:
            - 1h
            - 1d
        data:
          type: array
          items:
            type: object
            properties:
              bucket:
                type: string
                format: date-time
              realizedPnlSol:
                type: number
                description: >
                  Per-bucket realized PnL DELTA for this bucket (SOL) — the
                  realized PnL booked during this bucket, NOT a running
                  cumulative total.
              unrealizedPnlSol:
                type: number
                description: >
                  Point-in-time value of open positions minus their cost basis
                  at the end of this bucket (SOL).
              totalPnlSol:
                type: number
                description: Point-in-time realized + unrealized PnL at this bucket (SOL).
              solPriceUsd:
                type: number
                description: SOL/USD price at this bucket (from OHLCV data)
        count:
          type: integer
        tradesProcessed:
          type: integer
        truncated:
          type: boolean
          description: >-
            True if trade rows hit `limit` (wallet-wide or per-mint); PnL may be
            incomplete past the cap.
        tokensTracked:
          type: integer
          description: >-
            Number of unique tokens in the processed trade set (wallet-wide
            only).
        solPriceUsd:
          type: number
        timestamp:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        success:
          type: boolean
      example:
        error: Unauthorized
        message: Invalid API key
        code: INVALID_KEY
        success: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey

````