---
updatedAt: 2026-04-22T14:36:37.000Z
agentTools:
  projectIndex: https://docs.tatum.io/llms.txt
---

# Get Price Change by Symbol

<p style="display: none">/v4/data/rate/price-change</p>
<p><b>200 credits per API call</b></p>
<p>Get price change data for a symbol over a specified time range or interval.</p>
<p>This endpoint calculates the price change (both absolute and percentage) for a given symbol between two points in time. You can either specify an explicit time range using <code>timeFrom</code> and <code>timeTo</code>, or use a predefined interval that computes the change from the last fully closed candle.</p>
<p><b>Supported symbols:</b> We support 439+ trading pairs. The symbol parameter accepts the base currency (e.g., "BTC", "ETH").</p>
<p><b>Base pair:</b> By default, the base pair is "USDT". You can specify a different quote asset (e.g., "ETH", "USDC") using the <code>basePair</code> parameter.</p>
<p><b>Time range options:</b></p>
<ul>
<li><b>Explicit time range:</b> Provide both <code>timeFrom</code> and <code>timeTo</code> to calculate price change over a specific period. Both parameters must be in ISO 8601 date-time format.</li>
<li><b>Interval-based:</b> Provide an <code>interval</code> parameter (e.g., "1h", "1d", "1w", "1M") to calculate price change from the last fully closed candle of that interval. Supported intervals: 1m, 5m, 15m, 30m, 45m, 1h, 2h, 4h, 1d, 1w, 1M, 1y.</li>
</ul>
<p><b>Important:</b> You must provide either (<code>timeFrom</code> + <code>timeTo</code>) OR <code>interval</code>, but not both.</p>


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "servers": [
    {
      "url": "https://api.tatum.io"
    }
  ],
  "info": {
    "version": "1.2",
    "title": "Blockchain Data"
  },
  "tags": [
    {
      "name": "Exchange rate"
    }
  ],
  "paths": {
    "/v4/data/rate/price-change": {
      "get": {
        "description": "<p style=\"display: none\">/v4/data/rate/price-change</p>\n<p><b>200 credits per API call</b></p>\n<p>Get price change data for a symbol over a specified time range or interval.</p>\n<p>This endpoint calculates the price change (both absolute and percentage) for a given symbol between two points in time. You can either specify an explicit time range using <code>timeFrom</code> and <code>timeTo</code>, or use a predefined interval that computes the change from the last fully closed candle.</p>\n<p><b>Supported symbols:</b> We support 439+ trading pairs. The symbol parameter accepts the base currency (e.g., \"BTC\", \"ETH\").</p>\n<p><b>Base pair:</b> By default, the base pair is \"USDT\". You can specify a different quote asset (e.g., \"ETH\", \"USDC\") using the <code>basePair</code> parameter.</p>\n<p><b>Time range options:</b></p>\n<ul>\n<li><b>Explicit time range:</b> Provide both <code>timeFrom</code> and <code>timeTo</code> to calculate price change over a specific period. Both parameters must be in ISO 8601 date-time format.</li>\n<li><b>Interval-based:</b> Provide an <code>interval</code> parameter (e.g., \"1h\", \"1d\", \"1w\", \"1M\") to calculate price change from the last fully closed candle of that interval. Supported intervals: 1m, 5m, 15m, 30m, 45m, 1h, 2h, 4h, 1d, 1w, 1M, 1y.</li>\n</ul>\n<p><b>Important:</b> You must provide either (<code>timeFrom</code> + <code>timeTo</code>) OR <code>interval</code>, but not both.</p>\n",
        "operationId": "getPriceChange",
        "parameters": [
          {
            "description": "The base symbol of the trading pair (e.g., \"BTC\", \"ETH\").",
            "in": "query",
            "name": "symbol",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/HistoricalPriceSymbol"
            },
            "example": "BTC"
          },
          {
            "description": "Quote asset (e.g., \"USDT\", \"ETH\"). Defaults to \"USDT\" when not provided.",
            "in": "query",
            "name": "basePair",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/HistoricalPriceSymbol"
            },
            "example": "USDT"
          },
          {
            "description": "Range start (ISO 8601 date-time). Must be provided together with <code>timeTo</code> if not using <code>interval</code>.",
            "in": "query",
            "name": "timeFrom",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-01T00:00:00Z"
          },
          {
            "description": "Range end (ISO 8601 date-time). Must be provided together with <code>timeFrom</code> if not using <code>interval</code>. Must be greater than <code>timeFrom</code>.",
            "in": "query",
            "name": "timeTo",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-02T00:00:00Z"
          },
          {
            "description": "Interval computed from the last fully closed candle (e.g. \"1h\", \"1d\", \"1w\", \"1M\"). Must be provided if not using <code>timeFrom</code> and <code>timeTo</code>.",
            "in": "query",
            "name": "interval",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "15m",
                "30m",
                "45m",
                "1h",
                "2h",
                "4h",
                "1d",
                "1w",
                "1M",
                "1y"
              ]
            },
            "example": "1d"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceChangeResponse"
                }
              }
            },
            "description": "OK - Returns price change data for the requested symbol and time range/interval."
          },
          "400": {
            "description": "Bad Request - Invalid parameters (e.g., both time range and interval provided, or neither provided, or invalid symbol, or timeTo not greater than timeFrom)."
          },
          "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."
          },
          "404": {
            "description": "Not Found - No price data found for the requested symbol and time range/interval."
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "security": [
          {
            "X-API-Key": []
          }
        ],
        "x-codeSamples": [],
        "summary": "Get Price Change by Symbol",
        "tags": [
          "Exchange rate"
        ]
      }
    }
  },
  "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": {
      "HistoricalPriceSymbol": {
        "description": "Enum for trading pair symbols used in historical prices. These are the base symbols that are supported for historical price queries.",
        "type": "string",
        "enum": [
          "BTC",
          "ETH",
          "BNB",
          "NEO",
          "LTC",
          "QTUM",
          "ADA",
          "XRP",
          "TUSD",
          "IOTA",
          "XLM",
          "ONT",
          "TRX",
          "ETC",
          "ICX",
          "VET",
          "USDC",
          "LINK",
          "ONG",
          "HOT",
          "ZIL",
          "ZRX",
          "FET",
          "BAT",
          "ZEC",
          "IOST",
          "CELR",
          "DASH",
          "THETA",
          "ENJ",
          "ATOM",
          "TFUEL",
          "ONE",
          "ALGO",
          "DOGE",
          "DUSK",
          "ANKR",
          "WIN",
          "COS",
          "MTL",
          "DENT",
          "WAN",
          "FUN",
          "CVC",
          "CHZ",
          "BAND",
          "XTZ",
          "RVN",
          "HBAR",
          "NKN",
          "STX",
          "KAVA",
          "ARPA",
          "IOTX",
          "RLC",
          "BCH",
          "FTT",
          "EUR",
          "OGN",
          "LSK",
          "BNT",
          "MBL",
          "COTI",
          "DATA",
          "SOL",
          "CTSI",
          "HIVE",
          "CHR",
          "ARDR",
          "MDT",
          "KNC",
          "LRC",
          "COMP",
          "SC",
          "ZEN",
          "SNX",
          "VTHO",
          "DGB",
          "SXP",
          "DCR",
          "STORJ",
          "MANA",
          "YFI",
          "JST",
          "CRV",
          "SAND",
          "NMR",
          "DOT",
          "LUNA",
          "RSR",
          "PAXG",
          "TRB",
          "SUSHI",
          "KSM",
          "EGLD",
          "DIA",
          "RUNE",
          "FIO",
          "UMA",
          "BEL",
          "UNI",
          "OXT",
          "SUN",
          "AVAX",
          "UTK",
          "XVS",
          "AAVE",
          "NEAR",
          "FIL",
          "INJ",
          "AUDIO",
          "CTK",
          "AXS",
          "STRAX",
          "ROSE",
          "AVA",
          "SKL",
          "GRT",
          "JUV",
          "PSG",
          "1INCH",
          "OG",
          "ATM",
          "ASR",
          "CELO",
          "RIF",
          "TRU",
          "CKB",
          "TWT",
          "SFP",
          "DODO",
          "CAKE",
          "ACM",
          "FIS",
          "OM",
          "POND",
          "DEGO",
          "ALICE",
          "SUPER",
          "CFX",
          "TKO",
          "PUNDIX",
          "TLM",
          "BAR",
          "FORTH",
          "SLP",
          "SHIB",
          "ICP",
          "AR",
          "MASK",
          "LPT",
          "XVG",
          "ATA",
          "GTC",
          "PHA",
          "MLN",
          "DEXE",
          "C98",
          "QNT",
          "FLOW",
          "MINA",
          "RAY",
          "FARM",
          "QUICK",
          "MBOX",
          "REQ",
          "GHST",
          "WAXP",
          "GNO",
          "XEC",
          "DYDX",
          "IDEX",
          "USDP",
          "GALA",
          "ILV",
          "YGG",
          "SYS",
          "DF",
          "FIDA",
          "AGLD",
          "RAD",
          "RARE",
          "LAZIO",
          "CHESS",
          "ADX",
          "AUCTION",
          "MOVR",
          "CITY",
          "ENS",
          "QI",
          "PORTO",
          "POWR",
          "JASMY",
          "AMP",
          "PYR",
          "ALCX",
          "SANTOS",
          "BICO",
          "FLUX",
          "FXS",
          "VOXEL",
          "HIGH",
          "CVX",
          "PEOPLE",
          "SPELL",
          "JOE",
          "ACH",
          "IMX",
          "GLMR",
          "SCRT",
          "API3",
          "BTTC",
          "ACA",
          "XNO",
          "WOO",
          "ALPINE",
          "T",
          "ASTR",
          "GMT",
          "APE",
          "BIFI",
          "STEEM",
          "NEXO",
          "REI",
          "LDO",
          "OP",
          "STG",
          "LUNC",
          "GMX",
          "POLYX",
          "APT",
          "OSMO",
          "HFT",
          "PHB",
          "HOOK",
          "MAGIC",
          "RP",
          "GNS",
          "SYN",
          "SSV",
          "LQTY",
          "USTC",
          "GAS",
          "GLM",
          "PROM",
          "QKC",
          "ID",
          "ARB",
          "RDNT",
          "WBTC",
          "EDU",
          "SUI",
          "PEPE",
          "FLOKI",
          "MAV",
          "PENDLE",
          "ARKM",
          "WBETH",
          "WLD",
          "FDUSD",
          "SEI",
          "CYBER",
          "ARK",
          "IQ",
          "NTRN",
          "TIA",
          "MEME",
          "ORDI",
          "BEAMX",
          "PIVX",
          "VIC",
          "BLUR",
          "VANRY",
          "AEUR",
          "JTO",
          "1000SATS",
          "BONK",
          "ACE",
          "NFP",
          "AI",
          "XAI",
          "MANTA",
          "ALT",
          "JUP",
          "PYTH",
          "RONIN",
          "DYM",
          "PIXEL",
          "STRK",
          "PORTAL",
          "AXL",
          "WIF",
          "METIS",
          "AEVO",
          "BOME",
          "ETHFI",
          "ENA",
          "W",
          "TNSR",
          "SAGA",
          "TAO",
          "REZ",
          "BB",
          "NOT",
          "IO",
          "ZK",
          "LISTA",
          "ZRO",
          "G",
          "BANANA",
          "RENDER",
          "TON",
          "DOGS",
          "EURI",
          "POL",
          "NEIRO",
          "TURBO",
          "1MBABYDOGE",
          "CATI",
          "HMSTR",
          "EIGEN",
          "SCR",
          "BNSOL",
          "LUMIA",
          "KAIA",
          "COW",
          "CETUS",
          "PNUT",
          "ACT",
          "USUAL",
          "THE",
          "ACX",
          "ORCA",
          "MOVE",
          "ME",
          "VELODROME",
          "VANA",
          "1000CAT",
          "PENGU",
          "BIO",
          "D",
          "AIXBT",
          "CGPT",
          "COOKIE",
          "S",
          "SOLV",
          "TRUMP",
          "ANIME",
          "BERA",
          "1000CHEEMS",
          "TST",
          "LAYER",
          "HEI",
          "KAITO",
          "SHELL",
          "RED",
          "GPS",
          "EPIC",
          "BMT",
          "FORM",
          "XUSD",
          "NIL",
          "PARTI",
          "MUBARAK",
          "TUT",
          "BROCCOLI714",
          "BANANAS31",
          "GUN",
          "BABY",
          "ONDO",
          "BIGTIME",
          "VIRTUAL",
          "KERNEL",
          "WCT",
          "HYPER",
          "INIT",
          "SIGN",
          "STO",
          "SYRUP",
          "KMNO",
          "SXT",
          "NXPC",
          "AWE",
          "HAEDAL",
          "USD1",
          "HUMA",
          "A",
          "SOPH",
          "RESOLV",
          "HOME",
          "SPK",
          "NEWT",
          "SAHARA",
          "LA",
          "ERA",
          "C",
          "TREE",
          "A2Z",
          "TOWNS",
          "PROVE",
          "BFUSD",
          "PLUME",
          "DOLO",
          "MITO",
          "WLFI",
          "SOMI",
          "OPEN",
          "USDE",
          "LINEA",
          "HOLO",
          "PUMP",
          "AVNT",
          "ZKC",
          "SKY",
          "BARD",
          "0G",
          "HEMI",
          "XP",
          "MIRA",
          "FF",
          "EDEN",
          "NOM",
          "2Z",
          "MORPH",
          "ASTER",
          "WAL",
          "EUL",
          "ENSO",
          "YB",
          "ZBT",
          "TURTLE",
          "GIGGLE",
          "F",
          "KITE",
          "MMT",
          "SAPIEN",
          "ALLO",
          "BANK",
          "MET"
        ],
        "example": "BTC"
      },
      "PriceChangeResponse": {
        "description": "Price change data for a trading pair over a specified time range or interval. Includes open and close prices, timestamps, and calculated absolute and percentage changes.",
        "type": "object",
        "properties": {
          "symbol": {
            "description": "Base symbol of the trading pair (e.g., \"BTC\").",
            "type": "string",
            "example": "BTC"
          },
          "basePair": {
            "description": "Quote asset of the trading pair (e.g., \"USDT\", \"ETH\").",
            "type": "string",
            "example": "USDT"
          },
          "open": {
            "description": "Opening price at the start of the time range/interval.",
            "type": "string",
            "example": "45000.50"
          },
          "close": {
            "description": "Closing price at the end of the time range/interval.",
            "type": "string",
            "example": "46500.75"
          },
          "openTime": {
            "description": "Opening time in milliseconds (Unix timestamp).",
            "type": "number",
            "example": 1704067200000
          },
          "closeTime": {
            "description": "Closing time in milliseconds (Unix timestamp).",
            "type": "number",
            "example": 1704153600000
          },
          "absoluteChange": {
            "description": "Absolute price change (close - open) as a string.",
            "type": "string",
            "example": "1500.25"
          },
          "percentageChange": {
            "description": "Percentage price change as a number.",
            "type": "number",
            "format": "double",
            "example": 3.33
          },
          "batchId": {
            "description": "Echoed from the request for identification.",
            "type": "string",
            "example": "one"
          }
        },
        "required": [
          "symbol",
          "basePair",
          "open",
          "close",
          "openTime",
          "closeTime",
          "absoluteChange",
          "percentageChange"
        ]
      }
    }
  }
}
```