Skip to content
TraceFast Docs

Native balance history of an address

Open this address in TraceFast →

The address's native ETH balance at the end of each day it changed, oldest first: the balance, the net change over the day, the number of blocks in which it changed, and the USD value at the day's close. A summary gives the balance before the window, the extremes, and the total inflow and outflow.

GET https://tracefast.xyz/api/v1/chains/1/entities/{address}/balance-history
ParameterInTypeNotes
addresspathstring0x-prefixed, 40 hex characters, any case
limitqueryinteger, optionalhow many of the most recent days with a balance change to return, 1..365. Default 90

Access — an API key on the Enriched Data plan or higher (plans), or no key at all: pay per call with x402 at the same path on https://mpp.tracefast.xyz/api/v1, at the price its 402 states. As a tool for AI agents: get_entity_balance_history on the MCP server. Stable — see stability.

chains/1 is a literal: the method serves Ethereum mainnet data. Other chain ids answer 404 chain_not_supported. There are no other parameters — an unknown one is refused rather than ignored.

What it covers, and what it does not

  • Native ETH only. Token balances are in address portfolio and address token balance.
  • Days, not calendar spans. limit=30 returns the last 30 days on which the balance changed, which for a quiet address can reach back years. A day without a change has no point: the balance simply stayed as it was.
  • Daily granularity only, stated in granularity.
  • USD only on closed days. Each value is priced at the day's last hour, 23:00 UTC. The current, unfinished day has no usd, and neither has a day whose closing hour has no price yet.

Response

200 application/json, here with ?limit=3:

{
  "data": {
    "chainId": 1,
    "address": "0xf977814e90da44bfa03b6295a0616a897441acec",
    "granularity": "day",
    "points": [
      {
        "timestamp": 1790985600,
        "blockNumber": 26114036,
        "balanceWei": "439595909609796107385158",
        "changeWei": "-240187560065092",
        "txCount": 5,
        "usd": {
          "valueUsd": 1180696561.151992,
          "priceUsd": 2685.86794222,
          "priceHour": 1791068400,
          "priceCarried": false
        }
      },
      {
        "timestamp": 1791072000,
        "blockNumber": 26117644,
        "balanceWei": "439595909538342553172777",
        "changeWei": "-71453554212381",
        "txCount": 1,
        "usd": {
          "valueUsd": 1201660276.4826207,
          "priceUsd": 2733.55654684,
          "priceHour": 1791154800,
          "priceCarried": false
        }
      },
      {
        "timestamp": 1791158400,
        "blockNumber": 26125555,
        "balanceWei": "519397739206669881510062",
        "changeWei": "79801829668327328337285",
        "txCount": 7
      }
    ],
    "summary": {
      "startBalanceWei": "439595909849983667450250",
      "endBalanceWei": "519397739206669881510062",
      "minBalanceWei": "439595909538342553172777",
      "maxBalanceWei": "519397739206669881510062",
      "totalInflowWei": "79801829668327328337285",
      "totalOutflowWei": "311641114277473",
      "totalTxCount": 13,
      "firstActivityTimestamp": 1562683760,
      "lastActivityTimestamp": 1791195899
    }
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1791239773171,
    "cached": false,
    "asOfBlock": 26129087,
    "docs": "https://docs.tracefast.xyz/api/address-balance-history"
  }
}

The last point has no usd: when this response was produced, no price for that day's closing hour was available yet.

data

FieldMeaning
chainIdthe chain the facts are about; 1 is Ethereum mainnet
addressthe address, lowercase
granularitythe granularity of points. day is the only value
points[]one point per day on which the balance changed, oldest first — at most limit of the most recent such days
summarytotals over the returned window — see below

A point

FieldMeaning
timestampthe start of the day, Unix seconds, UTC
blockNumberthe last block of that day in which the balance changed
balanceWeithe balance at the end of the day, in wei, a decimal string
changeWeithe net change over the day, in wei, a decimal string; negative when the balance fell
txCountthe number of blocks in which the balance changed that day. Despite the name, not a number of transactions: several transactions in one block count once, and a change made by an internal call or a block reward counts too
usdthe USD value at the day's close. Absent for the current day and for a day with no price at its closing hour

usd

FieldMeaning
valueUsdbalanceWei / 10^18 × priceUsd — a floating-point estimate; the exact figure follows from balanceWei and priceUsd
priceUsdthe USD price of one ETH at priceHour
priceHourthe start of the UTC hour the price is for — the day's last hour, 23:00 UTC — in Unix seconds
priceCarriedtrue when no price was observed in that hour and the latest earlier one was used

summary

FieldMeaning
startBalanceWeithe balance before the first point: the first point's balance minus its change
endBalanceWeithe balance of the last point
minBalanceWei, maxBalanceWeithe lowest and highest balance over the window, startBalanceWei included
totalInflowWeithe sum of the positive daily changes over the window
totalOutflowWeithe sum of the negative daily changes, as a positive number
totalTxCountthe sum of txCount over the window: blocks in which the balance changed, not transactions
firstActivityTimestamp, lastActivityTimestampthe first and last account-state change of the address ever, Unix seconds — not limited to the window. Absent when the address never changed account state

startBalanceWei + totalInflowWei − totalOutflowWei = endBalanceWei.

Errors

StatuscodeWhendetails
400bad_requestlimit outside 1..365reason: limit_out_of_range, limit, maxLimit: 365
404chain_not_supporteda chain id other than 1—

Malformed input, unknown parameters and the key check's 401/403/429 are the same for every method — see conventions and API keys.

Last updated 22 Oct 2026, 08:06 UTC · verified against TraceFast v1.0.261 · Markdown