Realized P&L statistics

Use the realized P&L statistics API when an integration needs to report the gains and losses a participant has already realized in a DALP system. A disposal is recorded each time the participant burns tokens or transfers them out to a different participant. Each disposal carries the proceeds, the cost of the disposed quantity, and the realized P&L in the organisation's base currency.

These endpoints report realized results only. They cover positions the participant has closed or reduced, not the unrealized gain on holdings the participant still owns. For current holdings and their cost basis, see User asset balances. For the unrealized gain on a holding charted over time, see Unrealized P&L over time. For the participant's total portfolio value over time, see Portfolio statistics.

Participant scope

Realized P&L is calculated for the authenticated participant, not for a single address. A participant can hold and dispose of assets through more than one linked wallet, typically a signing account (EOA) and a smart wallet under account abstraction. Both endpoints aggregate across the participant's full set of linked wallets in the active system, and never return another participant's disposals.

Results are scoped to the active system from the request context. If a participant holds assets in more than one DALP system, each system's result covers only that system's disposals.

Endpoints

The realized P&L statistics API exposes two read endpoints:

Both endpoints are read-only. They report results the platform has already indexed and do not move assets or change holdings. For authentication and base URL setup, see Getting started.

List disposals

GET /api/v2/user-realized-pnl returns one row per recorded disposal. The list uses the standard collection conventions: page[offset], page[limit], sort, and filter[<field>].

curl --globoff --request GET \
  "$DALP_API_URL/api/v2/user-realized-pnl?page[limit]=50&sort=-blockTimestamp" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Rows default to newest first (sort=-blockTimestamp). You can sort by blockTimestamp or realizedPnlInBase. You can filter on:

• tokenAddress: restrict to disposals of one token.
• blockTimestamp: a date range.
• pnlSign: the sign of the realized result, one of gain, loss, or zero.

The pnlSign filter narrows the rows on the page, but it does not change the all-time total in meta (see below).

List response shape

The response is a JSON:API paginated envelope. It carries the matching rows in data, summary fields in meta, and pagination URLs in links.

{
  "data": [
    {
      "id": "018f3a2b-7c4d-7e1a-9b2c-3d4e5f6a7b8c",
      "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "tokenSymbol": "BOND",
      "quantity": "100",
      "proceedsInBase": "120.00",
      "costOfDisposalInBase": "100.00",
      "realizedPnlInBase": "20.00",
      "priceUnresolved": false,
      "blockTimestamp": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "realizedPnlTotalInBase": "20.00"
  },
  "links": {
    "self": "/v2/user-realized-pnl?page[limit]=50&page[offset]=0"
  }
}

Each row reports:

• tokenAddress and tokenSymbol: the disposed token.
• quantity: the disposed amount, expressed in the token's own decimals.
• proceedsInBase: disposal proceeds in base currency, calculated as quantity times the price at the time of disposal.
• costOfDisposalInBase: the cost of the disposed quantity in base currency, calculated as quantity times the weighted-average cost at disposal.
• realizedPnlInBase: proceeds minus cost of disposal. A loss is negative.
• priceUnresolved: true when the platform could not resolve a price at the time of the disposal. Proceeds are recorded as 0 in that case, so the realized result for that row understates the true figure.
• blockTimestamp: the block timestamp at which the disposal occurred.

meta.total is the number of rows that match the current filters. meta.realizedPnlTotalInBase is the participant's all-time realized P&L across every disposal in their accounts, independent of the current page, sort, and filters. Use it to show one stable realized figure while the list view changes.

Read the time series

GET /api/v2/user-realized-pnl-metrics returns realized P&L bucketed over a trailing window. Pass a preset that fixes both the window and the bucket interval. Each preset resolves to either hourly or daily buckets, so a shorter window returns finer points. The supported presets are:

curl --request GET \
  "$DALP_API_URL/api/v2/user-realized-pnl-metrics?preset=trailing7Days" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Time-series response shape

The response returns the resolved range alongside one point per bucket, ordered oldest first so a chart can plot the series left to right.

{
  "range": {
    "interval": "day",
    "from": "2026-01-01T00:00:00.000Z",
    "to": "2026-01-08T00:00:00.000Z",
    "isPreset": true
  },
  "data": [
    {
      "timestamp": "2026-01-01T00:00:00.000Z",
      "realizedPnlInBase": "20.00",
      "cumulativeRealizedPnlInBase": "20.00"
    },
    {
      "timestamp": "2026-01-02T00:00:00.000Z",
      "realizedPnlInBase": "-15.50",
      "cumulativeRealizedPnlInBase": "4.50"
    }
  ]
}

Each point reports:

• timestamp: the start of the bucket in UTC, at the preset's interval.
• realizedPnlInBase: the sum of realized P&L across the participant's disposals in that bucket.
• cumulativeRealizedPnlInBase: the running sum from the start of the range through that bucket.

The series is evenly spaced. The platform fills every bucket in the range, so a bucket with no disposals reports 0 for that interval and carries the previous cumulative value forward. If the platform cannot resolve any wallet for the participant, the endpoint returns the requested range with an empty data list rather than provisioning a wallet as a side effect.

How proceeds and cost are calculated

Both endpoints draw on the same indexed disposal records. The platform values each disposal in the organisation's base currency at the time it occurs:

• Proceeds are the disposed quantity times the resolved price at the time of the disposal.
• Cost of disposal is the disposed quantity times the weighted-average cost the participant carried for that token at the moment of the disposal.
• Realized P&L is proceeds minus cost of disposal.

Monetary values are rounded once at the API boundary, so an integration can display the returned figures directly without applying another conversion. When a disposal carries priceUnresolved: true, treat its realized figure as a lower bound, because the platform recorded proceeds of 0 for the unpriced disposal.

Related

• Portfolio statistics for the participant's total portfolio value over time and asset-type breakdown.
• User asset balances for the participant's current holdings.
• Getting started with API integration
• Developer guides