---
title: "GET /v4/opportunities/tvl-records"
method: GET
path: "/v4/opportunities/tvl-records"
tags: ["Opportunities"]
---

# GET /v4/opportunities/tvl-records

`GET /v4/opportunities/tvl-records`

## Request

- Base URL: `https://api.merkl.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.merkl.xyz/v4/opportunities/tvl-records`
- Auth: `apiKey` (a scheme the document does not define)

Get compact historical TVL series for several opportunities at once. Repeat `ids` once per opportunity.

## Query parameters

- `ids` string[], required: Opportunity IDs (numeric hash) to read history for. Repeat the parameter once per id.
- `from` number: Lower bound (inclusive) for the record's unix timestamp, in seconds.
- `to` number: Upper bound (inclusive) for the record's unix timestamp, in seconds.
- `grain` union: Resolution of the returned records. `DAY` (the default) is one point per UTC day and is kept indefinitely. `RAW` (one point per sample) and `HOUR` are kept for a limited window. SOFR_SPREAD_RATCHET opportunities have no `DAY` series; the default still returns one point per UTC day for them.
  - string
  - string
  - string
  - string

## Response `200`

TVL series per opportunity id, ascending by timestamp. Ids with no record are absent.

- object: TVL series per opportunity id, ascending by timestamp. Ids with no record are absent.

## Other responses

- `400`: Response for status 400
- `500`: Response for status 500

## Changes

- **2026-09-28** `2df507505e38`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/merkl/apis/merkl-api/changes/v4/opportunities/tvl-records/get.md)

---

[API](https://skmtc.dev/merkl/apis/merkl-api.md) - [All operations](https://skmtc.dev/merkl/apis/merkl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/merkl/apis/merkl-api/revisions/60ffe2c7d887?raw)