Skip to main content

​
Overview

Returns paginated historical price data for a specified cryptocurrency. Supports optional date range filters and page-based pagination. Results are ordered by newest first.

​
Endpoint

GET /v1/price/:coinId/history

​
Authentication

Required: Bearer token authentication Include the JWT token from the login endpoint in the Authorization header: 
Authorization: Bearer <your_access_token>

​
Path Parameters

​
coinId
string
required
CoinGecko coin identifier (lowercase letters, numbers, and hyphens)Example: bitcoin, ethereum, binancecoin

​
Query Parameters

​
from
string
Start date for filtering results (ISO 8601 format)Example: 2026-01-01T00:00:00.000Z
​
to
string
End date for filtering results (ISO 8601 format)Example: 2026-12-31T23:59:59.999Z
​
limit
integer
required
Number of items per page
  • Minimum: 1
  • Maximum: 100
  • Default: 20
Example: 20
​
page
integer
required
Page number (1-based)
  • Minimum: 1
  • Default: 1
Example: 1

​
Response

​
coinId
string
The cryptocurrency identifierExample: bitcoin
​
vsCurrency
string
The currency the prices are denominated in (always “usd”)Example: usd
​
items
array
Array of historical price records
​
items[].price
number
USD price at the time of fetchExample: 67210.45
​
items[].fetchedAt
string
ISO 8601 timestamp when the price was recordedExample: 2026-02-28T03:55:00.000Z
​
page
integer
Current page number (1-based)Example: 1
​
limit
integer
Number of items per pageExample: 20
​
totalItems
integer
Total number of items matching the queryExample: 57
​
totalPages
integer
Total number of pages availableExample: 3
​
hasNextPage
boolean
Whether there are more pages availableExample: true

​
Example Request

​
Basic Request

curl -X GET "http://localhost:3000/v1/price/bitcoin/history?limit=20&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
With Date Range Filter

curl -X GET "http://localhost:3000/v1/price/bitcoin/history?from=2026-01-01T00:00:00.000Z&to=2026-01-31T23:59:59.999Z&limit=50&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Example Response

{
  "coinId": "bitcoin",
  "vsCurrency": "usd",
  "items": [
    {
      "price": 67210.45,
      "fetchedAt": "2026-02-28T03:55:00.000Z"
    },
    {
      "price": 67101.22,
      "fetchedAt": "2026-02-28T03:50:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "totalItems": 57,
  "totalPages": 3,
  "hasNextPage": true
}

​
Error Codes

Status CodeDescription
200History page returned successfully
400Invalid query parameters (coinId format, date format, limit/page bounds, or from > to)
401Missing or invalid bearer token
429Rate limit exceeded
503Rate limiter backend unavailable

​
Error Response Format

All errors follow this format: 
{
  "statusCode": 400,
  "message": "limit must not be greater than 100",
  "error": "Bad Request"
}

​
Pagination Notes

  • Results are always ordered by newest first (most recent prices first)
  • Use hasNextPage to determine if more pages are available
  • Calculate total pages using: totalPages = Math.ceil(totalItems / limit)
  • To fetch the next page, increment the page parameter

Build docs developers (and LLMs) love

Get started for freeTalk to us