---
title: "Token Price History"
method: GET
path: "/gateway/v1/market/price"
tags: ["Market"]
---

# Token Price History

`GET /gateway/v1/market/price`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/market/price`
- Auth: HTTP bearer

Returns historical price data points for a token over a specified time range.

**Time range options:**
- Predefined: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `max`
- Custom: use `from` / `to` (Unix seconds or `YYYY-MM-DD`)

**Granularity** is automatic based on range:
- `1d` → 5-minute intervals
- `7d`–`90d` → hourly
- `180d`+ → daily

## Query parameters

- `symbol` string, required: Single token ticker symbol like `BTC`, `ETH`, or `SOL` (multi-symbol not supported)
- `time_range` '1d' | '7d' | '14d' | '30d' | '90d' | '180d' | '365d' | 'max': Window of historical data to return: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, or `max`. Ignored when `from`/`to` are set. This endpoint uses `time_range` only — it does NOT accept `interval`; bucket granularity is chosen server-side based on the window size.
- `from` string: Start of custom date range (Unix timestamp or YYYY-MM-DD). Must be used together with `to`. Overrides `time_range` when set.
- `to` string: End of custom date range (Unix timestamp or YYYY-MM-DD). Must be used together with `from`. Overrides `time_range` when set.
- `currency` string: Quote currency like `usd`, `eur`, or `btc`

## Response `200`

OK

- MarketPriceResponse
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` MarketMetricPoint[], nullable, required: Historical price points
    - `exchange` string: Exchange filter used for exchange-flow metrics. Omitted for non-exchange-flow metrics.
    - `exchange_name` string: Human-readable exchange name for exchange-flow metrics. Omitted for non-exchange-flow metrics.
    - `metric` string: Metric name like `nupl`, `sopr`, or `exchange-flows/inflow`
    - `project_id` string: Surf project UUID this symbol resolved to, for frontend entity linking. Empty when unmapped.
    - `symbol` string: Token symbol this data point belongs to
    - `timestamp` integer, required: Unix timestamp in seconds for this data point
    - `value` number, double, required: Metric value at this timestamp
  - `meta` ObjectResponseMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
  - `project_id` string: Surf project UUID the `--symbol` resolved to, for frontend entity linking. Empty when the symbol is unmapped.
  - `summary` MarketPriceSummary, required
    - `change_abs` number, double, required: Absolute change in the quote currency: last - first
    - `change_pct` number, double, required: Percentage change rounded to 4 decimals: (last - first) / first * 100. Zero when first is zero.
    - `first` number, double, required: Value of the earliest-timestamp point in the requested time range
    - `high` number, double, required: Highest value observed in the requested time range
    - `last` number, double, required: Value of the latest-timestamp point in the requested time range
    - `latest_dt` integer, required: Unix seconds of the latest-timestamp point
    - `low` number, double, required: Lowest value observed in the requested time range
    - `n_points` integer, required: Number of points in the underlying time-series
  - `symbol` string: The queried ticker, normalized.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)