LithosDocs
ProtocolPayoutsTokenStatsDocs
Start mining
Documentation home
Protocol
  • Lithos Protocol
  • LFSM
    • Rollups
    • NISPs
    • Emissions
    • Mining on Lithos
    • Candidate building
    • Ergo Voting
  • LithosDex
    • Trading with orders
    • Providing liquidity
Run Lithos
  • Startup guide
    • Setting up an Ergo testnet node
  • Configuration
    • Node connection and security
    • Stratum and difficulty
    • Block packages
    • Batching and orders
    • Collateral and emission
    • Wallet and consolidation
    • Statistics and web panels
    • Synchronization and storage
    • Tasks and dispatchers
    • Failure modes
    • Reporting issues
Client API
  • Overview
    • getLithos client information
    • getList UTXO ids for blocks
    • getUTXO ids by block height
    • getBlock info by UTXO id
    • postBlock info for multiple UTXO ids
    • getGet a block's miner set
    • getList all pool blocks
    • getGet Lithos payouts
    • getStatistics overview
    • getMining and payment totals
    • getMining statistics by hour or day
    • getEstimate Lithos hashrate
    • getNetwork difficulty by epoch
    • getThis client's own hashrate
    • getThis client's hashrate over time
    • getThis client's payouts and claims
    • getCollateral inventory
    • getLocal mining activity
    • getCollateral market snapshot
    • getList queue boxes
    • getList the active set
    • getPermit price history
    • getYour locked block rewards
    • postClaim unlocked block rewards
    • postQuote joining the queue
    • postJoin the collateral queue
    • getLithosDex pool state
    • getLithosDex fee vault state
    • getList your outstanding orders
    • postQuote a swap order
    • postPlace a swap order
    • postQuote a deposit order
    • postPlace a deposit order
    • postQuote a redeem order
    • postPlace a redeem order
    • postCancel an order
    • postQuote a swap
    • postQuote a swap by desired output
    • postExecute a swap
    • postQuote a liquidity deposit
    • postDeposit liquidity
    • postQuote a liquidity redemption
    • postRedeem liquidity
    • getList liquidity provisions
    • postClaim settled fees for a provision
    • postQuote a provision resize
    • postResize a provision
    • postCheck a pending fee flush
    • postFlush pending fees to the vault
    • getPool-wide fee history
    • getPool price history
    • getRecent pool activity
    • getFee history for one provision
    • getWallet balances and lending status
    • getGet Stratum information
    • getGet candidate settings
    • getGet difficulty commitment
    • postCommit a difficulty
    • getGet best NISP at height
Lithos

A decentralized mining pool protocol on Ergo. Miners build their own blocks; contracts pay them for proven work.

Live on Ergo mainnet
Protocol
  • How Lithos works
  • Mining on Lithos
  • NISPs
  • Emissions
  • LFSM contracts
Run Lithos
  • Startup guide
  • Configuration
  • LithosDex
  • Client API
  • Failure modes
Network
  • Live stats
  • Public stats API
  • Ergo Platform↗
  • SOAT Miner↗
Community
  • Telegram↗
  • X / Twitter↗
  • GitHub↗
Lithos
© 2026 Lithos Protocol. Open source under the MIT licence.λίθος — stone
Docs/Client API/Statistics

Mining statistics by hour or day

get/stats/mining/buckets

The totals from /stats/mining/totals split into UTC hour or day buckets — the shape a graph wants, for block counts, payments, fees, participation and difficulty. Buckets hold exact sums and counts, so averages are yours to compute: chain.difficultySum / chain.blocks for mean network difficulty, or batching.lithosdex.grossNanoErg / batching.lithosdex.orders for the mean LithosDex executor fee. A zero denominator has no average.

from is inclusive, until is exclusive, both must sit on a boundary of the chosen interval, and the range can cover at most 500 buckets. Buckets come oldest first, and a missing one means nothing was retained for it. Past the reported coverage a gap means the history is not available, not that nothing happened — check partial, retainedFrom and source.timestamp, since the first and last bucket may also be incomplete.

The query reads collected history and never contacts the node. A busy or unavailable history worker returns 503; retry after the delay it gives.

Query parameters

  • frominteger · int64required

    Inclusive start in Unix milliseconds, on a UTC hour or day boundary to match interval.

  • untilinteger · int64required

    Exclusive end in Unix milliseconds. On the same boundary, later than from, and at most 500 intervals after it.

  • intervalstringdefault "hour"hour | day

    Bucket size. Both range boundaries must be a whole number of these since the Unix epoch.

Responses

200Graph data for the requested range, with source status and coverage.MiningBucketHistory▶
  • ▶
    sourceMiningCursorrequired

    The processed chain point a statistics result was read from.

    • heightintegerrequired
    • blockIdstringrequired
    • parentIdstringrequired
    • timestampinteger · int64required

      The block's own timestamp in Unix milliseconds, not the time the client read it.

  • retainedFrominteger · int64

    Timestamp of the block before the first retained one. Absent when no block records remain.

  • frominteger · int64required

    The inclusive start you asked for, in Unix milliseconds.

  • untilinteger · int64required

    The exclusive end you asked for, in Unix milliseconds.

  • widthMsinteger · int64required
    one of360000086400000
  • ▶
    bucketsMiningBucket[]required

    Buckets with retained activity, oldest first. Use the coverage fields to tell a gap in history from a quiet hour.

    • startinteger · int64required

      Inclusive UTC bucket start in Unix milliseconds.

    • widthMsinteger · int64required

      Bucket duration in milliseconds.

      one of360000086400000
    • totalsMiningAccountingMetricsrequired

      Exact sums and counts for the period, as decimal strings. A missing key means nothing was collected for it, which is not evidence that nothing happened outside the coverage. Amounts ending in NanoErg are nanoERG and LIT amounts are base units. New keys get added over time, so ignore ones you do not recognise.

      Payout families hold outputs, grossNanoErg, rewardNanoErg, bondNanoErg, surplusNanoErg, rewardLit and receivedLit. Gross ERG is reward plus refunded bond plus any surplus. rewardLit is what the protocol owes; receivedLit is what the outputs actually carried. Network totals already contain the local ones — never add the two together.

      Batching families hold orders, grossNanoErg, transactionFeeNanoErg and afterTransactionFeesNanoErg, counting recognised execution layouts only, not all pool activity. Gross is newly earned executor fees and excludes takings carried in from earlier. Liquidity-provider fees are a different thing and live on the DEX API. pool.batching pays no transaction fee, so it holds only orders and grossNanoErg. It and local.batching never count the same execution.

      Rollup families hold count, miners, claimedScore, bondNanoErg and valueNanoErg, plus localCount, localValueNanoErg, localBondNanoErg and localClaimedScore where the local miner is identifiable — the submitting miner for submissions, the prover input for fraud proofs. So rollup.submission.localBondNanoErg is the bond this client posted, and rollup.fraudProof.localValueNanoErg is the slashed bonds it was paid for proving fraud. miners counts entries at that transition, not unique people. valueNanoErg means a different thing per kind: added holding value for a top-up, zero for a submission, the full box value at evaluation, the slashed bond for a fraud proof, and distributable ERG excluding bonds at payout readiness. These are stages of the same funds, so summing them is not income.

      transaction.<kind> covers genesis, the rollup kinds above, payout, registration, ergodex, lithosdex, ergodexOtherPoolSpend and lithosdexOtherPoolSpend. Those fees overlap the block fee totals.

      Priority fees. lithos.priorityFeeNanoErg / lithos.blocks is the mean fee across every Lithos block; divide by lithos.blocksWithPriorityFee instead for the mean across the blocks that carried one. The amount is the WHOLE fee the lender posted, not the share the block's finder keeps out of it. The pool's share went into the holding box and is already inside holding.genesisNanoErg, so there is deliberately no separate key for it.

      Divide a sum by its matching count for an average. claimedScore is protocol accounting, not measured hashrate. A transaction fee is a transaction's cost and not automatically this client's expense, holding top-ups and executor fees can describe the same proceeds, and no key here is a net-income figure.

  • partialbooleanrequired

    True when retained coverage does not span the whole requested range, including when the history is empty.

  • statusstringrequired

    How far collection has got. ready means it reached the last checked chain tip. catching-up and recovering mean replay or reorg work is still running, stale means the last successful check is too old, and unavailable means collection failed. On disabled or loading the numbers are not evidence that the period was quiet.

    one ofdisabledloadingreadystaleunavailablecatching-uprecovering
400A timestamp is missing, malformed, off a bucket boundary, or the range is too long; or `interval` is not hour or day.ApiError▶
  • errorintegerrequired

    Error code

  • reasonstringrequired

    Error message explaining the reason of the error

  • detailstringrequirednullable

    Detailed error description

503History is loading, disabled, busy, or unreadable. Check `mining.status` in /stats before retrying.ApiError▶
  • errorintegerrequired

    Error code

  • reasonstringrequired

    Error message explaining the reason of the error

  • detailstringrequirednullable

    Detailed error description

← PreviousMining and payment totalsNext →Estimate Lithos hashrate
Request
curl -X GET "http://localhost:9000/stats/mining/buckets?from=0&until=1"
Response
{
  "source": {
    "height": 0,
    "blockId": "string",
    "parentId": "string",
    "timestamp": 0
  },
  "retainedFrom": 0,
  "from": 0,
  "until": 0,
  "widthMs": 3600000,
  "buckets": [
    {
      "start": 0,
      "widthMs": 3600000,
      "totals": {
        "chain.blocks": "720",
        "lithos.blocks": "12",
        "local.payout.outputs": "3",
        "local.payout.rewardNanoErg": "1500000000",
        "local.payout.bondNanoErg": "3000000",
        "batching.lithosdex.orders": "20",
        "batching.lithosdex.grossNanoErg": "40000000"
      }
    }
  ],
  "partial": true,
  "status": "disabled"
}