Farbeam
Docs / Core concepts

USD valuation

Every transfer row has a usd value. It equals amount times the price the service held at the moment it indexed the row. It is computed once and never updated.

#Price source

Prices come from the CoinGecko simple/price endpoint, in USD, for one list of ids. The poller refreshes them every 60 seconds. Read the same values with Asset prices.

CoinGecko idUsed for
ethereumETH, WETH on all chains, ETH on BNB Chain
binancecoinBNB, WBNB
polygon-ecosystem-tokenPOL (fees and wallets only, no index on Polygon)
solanaSOL, wSOL
usd-coinUSDC on all chains, USDbC on Base
tetherUSDT on all chains
wrapped-bitcoinWBTC, cbBTC on Base, BTCB on BNB Chain
daiDAI

This sample of GET /prices was captured on 2026-11-04 UTC. It is an example, and values change every minute.

JSON
{
  "ethereum": { "usd": 2423.51, "change_24h_pct": 5.86 },
  "binancecoin": { "usd": 716.72, "change_24h_pct": 2.86 },
  "polygon-ecosystem-token": { "usd": 0.096378, "change_24h_pct": 4.66 },
  "solana": { "usd": 95.35, "change_24h_pct": 2.23 },
  "usd-coin": { "usd": 0.999692, "change_24h_pct": 0.01 },
  "tether": { "usd": 0.999402, "change_24h_pct": 0.03 },
  "wrapped-bitcoin": { "usd": 80237, "change_24h_pct": 3.67 },
  "dai": { "usd": 1, "change_24h_pct": 0.01 }
}

#Stablecoins are not fixed at $1

Stablecoins use their market price from the same source. There is no hard-coded peg. This has one visible effect at the $100,000 threshold.

TransferPrice at index timeusdStored
100,000 USDT0.99940299,940.20No
100,100 USDT0.999402100,040.14Yes
100,000 DAI1100,000.00Yes

The threshold test is usd >= 100000. Rows at round numbers can fall on either side, depending on the price that minute. The figures above are worked examples using the sample prices.

#Mapped assets

A wrapped or bridged token uses the price of its reference asset. The service does not read a separate market for each one.

TokenPriced asConsequence
USDbC on Baseusd-coinA USDbC depeg would not show in usd
cbBTC on Basewrapped-bitcoinSame approach
BTCB on BNB Chainwrapped-bitcoinSame approach
ETH on BNB ChainethereumSame approach
wSOL on SolanasolanaSame approach

#Price at index time

The usd value is a record of one moment, and it does not follow the market after that.

  • The price can be up to about a minute old when the row is stored.
  • A row from yesterday keeps yesterday's price.
  • Summing usd over time gives a sum of values at different prices, which is not a current value.

For a current value, multiply amount by a current price from /prices.

#Where other USD values come from

Not every USD figure in the API has the same origin. Compare them with care.

FieldSourceTime
transfers[].usdCoinGeckoIndex time, fixed
native.usd, tokens[].usd on EVM walletsCoinGeckoCurrent, 30 s cache
tokens[].usd on Solana walletsHelius price data when Helius is in use, else CoinGecko for curated tokens onlyCurrent, 30 s cache
value.usd on GET /txCoinGeckoCurrent, not the price when the transaction ran
market.price_usd in a token reportMedian implied price across DexScreener pools60 s cache
native_price_usd on GET /gasCoinGeckoCurrent

A token report's price_usd and a /prices value for the same asset will usually differ by a small amount. The first comes from DEX pools, and the second from an aggregator.

#Limits

  • Price failures. If a refresh fails, the service keeps the last good prices and goes on valuing rows with them. There is no marker on the row. coingecko on Status shows the failure.
  • No price at start. Until the first refresh succeeds after a restart, rows are skipped, because a row needs a price. This window is normally seconds.
  • No fee or slippage logic. usd values the transferred amount only.
  • Precision. amount and usd are doubles. The raw integer value from the chain is not stored. For exact amounts, read the transaction from the chain.
  • Not a trade price. usd values a transfer at a reference price. It is not what any party paid or received. See transfers vs trades.

Market prices are for information only and are not financial advice.