---
title: "GET /v4/tokens/prices/history"
method: GET
path: "/v4/tokens/prices/history"
tags: ["Tokens"]
---

# GET /v4/tokens/prices/history

`GET /v4/tokens/prices/history`

## 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/tokens/prices/history`
- Auth: `apiKey` (a scheme the document does not define)

Get historical price snapshots for a token, newest first. Resolve by symbol (optionally scoped to a chainId) or by exact chainId+address. Snapshots are stored on change, so pass `fill=carry-forward` for one row per day of the range.

## Query parameters

- `symbol` string: Token symbol (case-insensitive). Matches symbol or displaySymbol.
- `address` string: Token address. Requires chainId for a unique result.
- `chainId` union: Chain ID. Required alongside address for a unique result; optional when using symbol.
  - string, numeric
  - number: Chain ID. Required alongside address for a unique result; optional when using symbol.
- `from` union: Start day as Unix day integer (days since 1970-01-01 UTC). Defaults to today - 365 days.
  - string, integer
  - integer: Start day as Unix day integer (days since 1970-01-01 UTC). Defaults to today - 365 days.
- `to` union: End day as Unix day integer (days since 1970-01-01 UTC). Defaults to today UTC.
  - string, integer
  - integer: End day as Unix day integer (days since 1970-01-01 UTC). Defaults to today UTC.
- `fill` string: Emit one row per day of the range, each carrying the newest price at or before it (anchored on the last row before `from`). Snapshots are stored on change only, so an absent day means 'unchanged' — use this to average or plot a range without re-deriving that. Days before the token's first snapshot stay absent.

## Response `200`

Response for status 200

- object[]
  - `day` union, required: Unix day (days since 1970-01-01 UTC)
    - string, integer
    - integer: Unix day (days since 1970-01-01 UTC)
  - `open` number, required
  - `close` number, required
  - `min` number, required
  - `max` number, required
  - `avg` number, nullable, required: Mean of the day's samples. Null for a row written before grains.
  - `samples` union, required: Number of samples folded into the day
    - string, integer
    - integer: Number of samples folded into the day
  - `source` string, nullable, required

## Changes

- **2026-09-09** `c51d2a5209b9`: 3 info
  - added the new optional `query` request parameter `fill`
  - added the required property `items/avg` to the response with the `200` status
  - added the required property `items/samples` to the response with the `200` status

[Operation history](https://skmtc.dev/merkl/apis/merkl-api/changes/v4/tokens/prices/history/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)