---
updatedAt: 2026-05-27T08:47:41.000Z
agentTools:
projectIndex: https://docs.tatum.io/llms.txt
---
# Get Exchange Rate History by Symbol
/v4/data/rate/history
50 credits per API call
Retrieves token prices, FDV, and liquidity at any block or timestamp, including percentage change for specified lookback periods.
Supported blockchains:
- Ethereum - ethereum-mainnet
- Base - base-mainnet
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"servers": [
{
"url": "https://api.tatum.io"
}
],
"info": {
"version": "1.2",
"title": "Blockchain Data"
},
"tags": [
{
"name": "Token API"
}
],
"paths": {
"/v4/data/rate/history": {
"get": {
"description": "/v4/data/rate/history
\n50 credits per API call
\nRetrieves token prices, FDV, and liquidity at any block or timestamp, including percentage change for specified lookback periods.
\nSupported blockchains:
\n\n- Ethereum - ethereum-mainnet
\n- Base - base-mainnet
\n
\n",
"operationId": "getExchangeRateHistoryBySymbol",
"parameters": [
{
"name": "chain",
"description": "The blockchain to work with.",
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/ChainEnumForTrendingTokens"
}
},
{
"name": "contractAddress",
"description": "Contract address of token. Mutually exclusive with symbol.",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
}
},
{
"name": "blockNumber",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/BlockNumber"
}
},
{
"name": "timestamp",
"description": "Date-time UTC timestamp in format YYYY-MM-DDTHH:mm:ssZ (ignored if blockNumber is present)",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"example": "2025-09-25T16:00:01Z"
}
},
{
"name": "symbol",
"description": "The fiat or crypto asset to exchange. Mutually exclusive with contractAddress.",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/CurrencySymbol"
}
},
{
"name": "basePair",
"description": "The target asset to get the exchange rate for",
"in": "query",
"required": true,
"schema": {
"type": "string",
"example": "USD",
"enum": [
"USD",
"BTC",
"ETH"
]
}
},
{
"name": "lookbackMinutes",
"description": "Minutes to calculate price change over time, comparing to defined point of time in blockNumber or timestamp, comma separated",
"in": "query",
"schema": {
"type": "string",
"example": "15,30"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateHistoryResponse"
},
"examples": {
"bySymbol": {
"summary": "By symbol, with a 24-hour lookback window",
"value": {
"price": 84858.18087819443,
"priceChanges": [
{
"minutes": 1440,
"priceChange": "0.72%"
}
]
}
},
"byContractAddress": {
"summary": "By contract address, with 24-hour and 7-day lookback windows",
"value": {
"address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
"price": 85271.9988889883,
"liquidity": 314135928,
"priceChanges": [
{
"minutes": 1440,
"priceChange": "1.08%"
},
{
"minutes": 10080,
"priceChange": "-0.27%"
}
]
}
},
"atTimestampWithoutLookback": {
"summary": "At a past timestamp, with no lookback windows requested",
"value": {
"price": 85393.22824652209,
"priceChanges": []
}
}
}
}
},
"description": "OK"
},
"401": {
"$ref": "#/components/responses/Error401"
},
"403": {
"description": "Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions."
},
"500": {
"$ref": "#/components/responses/Error500"
}
},
"security": [
{
"X-API-Key": []
}
],
"x-codeSamples": [],
"summary": "Get Exchange Rate History by Symbol",
"tags": [
"Token API"
]
}
}
},
"components": {
"securitySchemes": {
"X-API-Key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"description": "Your **API key** is used to identify your account & your plan, including the number of API calls per second and total monthly calls you have.\n\nEach key is for individual use only.\n\nIf you don't have a key already you can [Sign up for a Free Tatum account](https://co.tatum.io/signup) to get two keys (testnet and mainnet), allowing up to 5 API calls per second and 1,000,000 Credits.\n\nFor testing purposes, you can use the following key which only works inside docs and has limited functionality (e.g. you cannot create virtual accounts or notification subscriptions with it):\n* t-66a730ccccfd17001c479705-2f597d14ad7543f289a03418\n\nFor more details on limits and plans, [click here](https://docs.tatum.io/docs/plans-limits).\n"
}
},
"responses": {
"Error401": {
"description": "Unauthorized. Not valid or inactive subscription key present in the HTTP Header.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"errorCode": {
"example": "subscription.not.active",
"description": "subscription.not.active",
"type": "string"
},
"message": {
"example": "Subscription not active anymore.",
"description": "Subscription not active anymore.",
"type": "string"
},
"statusCode": {
"example": 401,
"description": "401",
"type": "number"
}
},
"required": [
"errorCode",
"message",
"statusCode"
],
"type": "object"
},
{
"properties": {
"errorCode": {
"example": "subscription.invalid",
"description": "subscription.invalid",
"type": "string"
},
"message": {
"example": "Unable to find valid subscription for '${apiKey}'",
"description": "Unable to find valid subscription for '${apiKey}'",
"type": "string"
},
"statusCode": {
"example": 401,
"description": "401",
"type": "number"
}
},
"required": [
"errorCode",
"message",
"statusCode"
],
"type": "object"
}
]
}
}
}
},
"Error500": {
"description": "Internal server error. There was an error on the server during the processing of the request.",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"example": "Internal server error",
"description": "Internal server error",
"type": "string"
},
"statusCode": {
"example": 500,
"description": "500",
"type": "number"
}
},
"required": [
"statusCode",
"message"
],
"type": "object"
}
}
}
}
},
"schemas": {
"CurrencySymbol": {
"type": "string",
"description": "The fiat or crypto asset to exchange.",
"example": "BTC"
},
"BlockNumber": {
"type": "number",
"example": 16499510,
"minimum": 0
},
"RateHistoryPriceChange": {
"description": "Price change over one lookback window, relative to the priced instant.",
"properties": {
"minutes": {
"description": "The lookback window in minutes, echoing one value from lookbackMinutes.",
"example": 1440,
"type": "number"
},
"priceChange": {
"description": "Signed percentage change over the window, with a trailing percent sign.",
"example": "0.72%",
"type": "string"
}
},
"required": [
"minutes",
"priceChange"
],
"type": "object"
},
"RateHistoryResponse": {
"description": "Price of the asset at the requested block or timestamp, with the percentage change over each requested lookback window.",
"properties": {
"price": {
"description": "Price of the asset in the requested basePair at the priced instant. Returns 0 when no observation is available for the request, which is not distinguishable from a genuine price of 0.",
"example": 84858.18087819443,
"type": "number"
},
"priceChanges": {
"description": "One entry per requested lookbackMinutes value. Empty when lookbackMinutes is omitted, or when no observation covers the window.",
"items": {
"$ref": "#/components/schemas/RateHistoryPriceChange"
},
"type": "array"
},
"address": {
"description": "Contract address of the priced token. Returned only when the upstream holds it for this token, and never for symbol lookups.",
"example": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
"type": "string"
},
"fdv": {
"description": "Fully diluted valuation, in the requested basePair. Returned only when the upstream holds it for this token.",
"example": 39410377,
"type": "number"
},
"liquidity": {
"description": "Pool liquidity for the token, in the requested basePair. Returned only when the upstream holds it for this token.",
"example": 314135928,
"type": "number"
}
},
"required": [
"price",
"priceChanges"
],
"type": "object"
},
"ChainEnumForTrendingTokens": {
"type": "string",
"description": "Chains supported by the tokens and wallets endpoints.\n",
"enum": [
"ethereum-mainnet",
"base-mainnet"
]
}
}
}
}
```