Indexed Stats API
Use the Indexed Stats API for questions that need the full history of the chain:
- What balances did a wallet have on a given date? For example, at the end of a tax year.
- How many addresses hold a coin, and which addresses hold the most?
- How active is an address, day by day?
- How many wallets were active or new each day?
- What did an address stake, and what rewards did it get?
- How many users call a package?
The data comes from Inodra's own index of Sui mainnet. The index starts at genesis. It counts address balances as well as Coin objects, so funds sent with 0x2::coin::send_funds are included.
Authentication
Send an API key with the data scope in the x-api-key header.
curl "https://mainnet-api.inodra.com/v1/chain/stats/totals" \
-H "x-api-key: YOUR_API_KEY"Rules for All Endpoints
- Mainnet only. The network follows your project. A testnet project gets
400 NETWORK_NOT_SUPPORTED. - Each call costs 2 credits.
- Every response has
data,checkpoint(the data is current to this checkpoint) andcoverage(the indexed range). - Amounts are strings in the smallest unit of the coin (MIST for SUI).
- Coin types are returned in the long form, for example
0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI. You can send the short form. - Addresses and package ids must be the full 32-byte form (
0xand 64 hex characters). - Days are UTC. The first and the last indexed day can be partial.
{
"data": {},
"checkpoint": 345001999,
"coverage": {
"firstCheckpoint": 0,
"lastCheckpoint": 345001999,
"firstTimestamp": "2023-04-12T17:00:00.000Z",
"lastTimestamp": "2026-11-14T03:14:24.737Z",
"fromGenesis": true
}
}Freshness
The index follows the chain. To see how current a response is, read checkpoint and coverage.lastTimestamp.
- Balances and staking positions at a point in history are exact to the checkpoint.
- Coin holders can be some minutes behind the index. Their
checkpointshows the point they are current to. - Network totals are cached for 30 seconds.
Endpoints
| Endpoint | Use |
|---|---|
GET /v1/accounts/{address}/balances-at | Balances at a point in history |
GET /v1/coins/{coinType}/holders | Holder count and top holders of a coin |
GET /v1/accounts/{address}/activity | Activity of an address per day |
GET /v1/chain/stats/daily | Network activity per day |
GET /v1/chain/stats/totals | Network totals |
GET /v1/accounts/{address}/stakes | Staking positions and rewards |
GET /v1/validators/{address}/stakers | Current stakers of a validator |
GET /v1/stakers | Top stakers across all validators |
GET /v1/validators/{address}/rewards | Rewards of a validator per epoch |
GET /v1/validators/{address}/stake-history | Stake added and withdrawn per epoch |
GET /v1/packages/{packageId}/stats | Calls and unique users of a package |
Balances at a Point in History
ADDRESS=0x... # a full 32-byte address
curl "https://mainnet-api.inodra.com/v1/accounts/$ADDRESS/balances-at?at=2025-12-31T23:59:59Z" \
-H "x-api-key: YOUR_API_KEY"Returns every non-zero coin balance of the address after the given checkpoint, or after the last checkpoint at or before the given time.
| Parameter | Required | Description |
|---|---|---|
at | No | ISO 8601 time or Unix milliseconds (not seconds) |
checkpoint | No | A checkpoint number. Use at or checkpoint, not both |
| (none) | Without at and checkpoint: the last indexed checkpoint |
Response 200:
{
"data": {
"address": "0x...",
"asOfCheckpoint": 213450112,
"asOfTimestamp": "2025-12-31T23:59:59.412Z",
"balances": [
{
"coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
"balance": "1500000000"
}
],
"staked": {
"epoch": 980,
"principal": "1000000000000",
"value": "1041250000000",
"unrealisedRewards": "41250000000",
"realisedRewards": "0",
"byValidator": [
{
"validator": "0x...",
"poolId": "0x...",
"principal": "1000000000000",
"value": "1041250000000",
"unrealisedRewards": "41250000000",
"realisedRewards": "0"
}
]
}
},
"checkpoint": 345001999,
"coverage": {}
}balanceshas coins owned by the address and its address balance. It does not have coins held inside other objects, for example in a pool, a kiosk or a vault.stakedis the SUI inStakedSuiobjects at that point. It is not inbalances. See Staking for the fields.- A time or checkpoint after the last indexed checkpoint gets
422 OUT_OF_INDEX_RANGE.
Coin Holders
curl "https://mainnet-api.inodra.com/v1/coins/0x2::sui::SUI/holders?limit=20" \
-H "x-api-key: YOUR_API_KEY"Returns the addresses with a positive balance of the coin, largest first.
| Parameter | Required | Description |
|---|---|---|
limit | No | 1 to 100. Default 20 |
cursor | No | nextCursor from the previous page |
Response 200:
{
"data": {
"coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
"holderCount": 1843211,
"holders": [{ "address": "0x...", "balance": "912000000000" }],
"nextCursor": "MTIzOjQ1"
},
"checkpoint": 345001999,
"coverage": {}
}holderCountis set on the first page only. On later pages it isnull.nextCursorisnullon the last page.- If a balance changes between two page reads, a holder can move between pages.
- Holders are addresses. Coins held inside objects (pools, kiosks, dynamic fields) are not counted, so the sum of holder balances can be less than the total supply.
- An unknown coin type gets
holderCount: 0and no holders.
Address Activity
ADDRESS=0x4483dd1b153465279d4483930b929e6709a5ed7815c1258733106a529ed284f8
curl "https://mainnet-api.inodra.com/v1/accounts/$ADDRESS/activity?from=2026-11-14&to=2026-11-14" \
-H "x-api-key: YOUR_API_KEY"| Parameter | Required | Description |
|---|---|---|
from | No | First day, YYYY-MM-DD. Default: 366 days up to to, or less |
to | No | Last day, YYYY-MM-DD, included. Default: the last indexed day |
The longest range is 366 days. A default from does not go before the first indexed day. A day outside coverage gets 422 OUT_OF_INDEX_RANGE.
Response 200:
{
"data": {
"address": "0x4483dd1b153465279d4483930b929e6709a5ed7815c1258733106a529ed284f8",
"from": "2026-11-14",
"to": "2026-11-14",
"firstSeenTimestamp": "2024-03-02T09:41:17.204Z",
"totals": {
"txSent": 10784,
"txTouched": 10784,
"gasPaid": "1132913796",
"activeDays": 1
},
"days": [{ "day": "2026-11-14", "txSent": 10784, "txTouched": 10784, "gasPaid": "1132913796" }]
},
"checkpoint": 345001999,
"coverage": {}
}txSent- transactions the address sent.txTouched- transactions that the address sent or that changed one of its balances.gasPaid- net gas paid by the address as gas owner, in MIST. Storage rebates make it lower, and it can be negative. A sponsor pays gas for transactions that it did not send. These are not in itstxSentortxTouched.activeDays- days with at least one sent transaction.firstSeenTimestamp- the first transaction that touched the address.nullwhen it is not known.- A day with no activity has no row in
days.
Daily Network Stats
curl "https://mainnet-api.inodra.com/v1/chain/stats/daily?from=2026-11-01&to=2026-11-14" \
-H "x-api-key: YOUR_API_KEY"| Parameter | Required | Description |
|---|---|---|
from | No | First day, YYYY-MM-DD. Default: 31 days up to to, or less |
to | No | Last day, YYYY-MM-DD, included. Default: the last indexed day |
The longest range is 31 days.
Response 200:
{
"data": [
{
"day": "2026-11-14",
"transactions": 86932,
"userTransactions": 62321,
"failedTransactions": 5962,
"activeWallets": 1371,
"newWallets": 112,
"commands": 241087
}
],
"checkpoint": 345001999,
"coverage": {}
}activeWallets- distinct senders on that day.newWallets- addresses seen on chain for the first time, as a sender or as the owner of a balance change.commands- commands in the programmable transactions of the day. It can benullfor an older day.
Network Totals
curl "https://mainnet-api.inodra.com/v1/chain/stats/totals" \
-H "x-api-key: YOUR_API_KEY"No parameters. Every caller gets the same result. It is cached for 30 seconds.
Response 200:
{
"data": {
"addresses": { "total": 187263540, "last24h": 210334 },
"coinTypes": { "total": 98124 },
"commands": { "total": 9182736455 },
"packages": { "total": 151870, "last24h": 412 },
"tps": {
"peak24h": 512.4,
"peak7d": 903.1,
"peak30d": 1276,
"avg24h": 178.39,
"series24h": { "fromMs": 1763003664737, "stepMs": 900000, "points": [171.2, 180.05] }
},
"checkpointsPerSecond24h": 4.1,
"gas24h": {
"userTransactions": 9874210,
"avgFee": "322582",
"medianFee": "103007",
"minFee": "-53398516",
"maxFee": "49746879",
"avgStorageRebate": "45558773",
"avgComputationFee": "269256"
},
"windows": {
"dayFrom": "2026-11-13T03:14:24.737Z",
"weekFrom": "2026-11-07T03:14:24.737Z",
"peakFrom": "2026-10-15T03:14:24.737Z",
"to": "2026-11-14T03:14:24.737Z"
}
},
"checkpoint": 345001999,
"coverage": {}
}| Field | Meaning |
|---|---|
addresses | total addresses seen on chain, and last24h new ones |
coinTypes | total coin types seen in a balance change |
commands | total commands in programmable transactions. null until the daily totals have every day |
packages | total packages created on chain (publish and upgrade), and last24h |
tps | Highest 10-second average in 24 hours, 7 days and 30 days, avg24h, and series24h |
checkpointsPerSecond24h | Checkpoints per second over the last 24 hours |
gas24h | Last 24 hours, per user transaction: avgFee, medianFee, minFee, maxFee, avgStorageRebate, avgComputationFee |
windows | The time windows used |
series24h- the average TPS per step over the last 24 hours, oldest first.fromMsandstepMsare in Unix milliseconds. The last step ends atcheckpointand can be shorter.- The fee is the net gas that the gas owner paid, in MIST: computation plus storage, minus the storage rebate. It can be negative when a transaction deletes objects. A few large rebates pull
avgFeedown, so usemedianFeefor the typical fee.avgComputationFeeis the computation part only. - TPS counts all transactions, also system transactions.
- "24 hours", "7 days" and "30 days" end at
checkpoint.
Staking
Staking positions come from 0x3::staking_pool::StakedSui objects. The index keeps every change to these objects, so it knows the positions an address held at any point, not only now. Rewards come from the validator epoch info events of each epoch change.
A reward is valued the same way that the chain pays it at unstake: the principal is converted to pool tokens at the exchange rate of its activation epoch, and back to SUI at the rate of the epoch. The index does not say how staking rewards are taxed. It gives both views: accrued over time and realised at unstake.
For stakers and stake-history, the {address} of a validator is its Sui address or the id of its staking pool. rewards takes the Sui address only. A validator with no stake or unstake request in the index has no known pool, so its endpoints return empty results.
Staking Positions of an Address
ADDRESS=0x... # a full 32-byte address
curl "https://mainnet-api.inodra.com/v1/accounts/$ADDRESS/stakes?at=2025-12-31T23:59:59Z" \
-H "x-api-key: YOUR_API_KEY"The parameters are the same as for balances: at or checkpoint, default the last indexed checkpoint.
Response 200:
{
"data": {
"address": "0x...",
"asOfCheckpoint": 213450112,
"asOfTimestamp": "2025-12-31T23:59:59.412Z",
"epoch": 980,
"positions": [
{
"objectId": "0x...",
"poolId": "0x...",
"validator": "0x...",
"principal": "1000000000000",
"activationEpoch": 912,
"value": "1041250000000",
"reward": "41250000000"
}
],
"summary": {
"principal": "1000000000000",
"value": "1041250000000",
"unrealisedRewards": "41250000000",
"realisedRewards": "0"
},
"byValidator": [
{
"validator": "0x...",
"poolId": "0x...",
"principal": "1000000000000",
"value": "1041250000000",
"unrealisedRewards": "41250000000",
"realisedRewards": "0"
}
]
},
"checkpoint": 345001999,
"coverage": {}
}value- principal plus the rewards accrued byepoch.unrealisedRewards- rewards accrued and not paid out yet.realisedRewards- rewards paid out by unstakes before that point.validatorcan benullwhen the pool has no known validator.
Stakers of a Validator
VALIDATOR=0x... # the validator's Sui address or pool id
curl "https://mainnet-api.inodra.com/v1/validators/$VALIDATOR/stakers?limit=20" \
-H "x-api-key: YOUR_API_KEY"GET /v1/stakers takes the same parameters and returns the largest stakers across all validators, without validator.
| Parameter | Required | Description |
|---|---|---|
limit | No | 1 to 100. Default 20 |
cursor | No | nextCursor from the previous page |
Response 200:
{
"data": {
"validator": "0x...",
"stakerCount": 5120,
"totalPrincipal": "312500000000000000",
"stakers": [{ "address": "0x...", "principal": "25000000000000000", "positions": 3 }],
"nextCursor": "MjUwMDAwMDAwMDAwMDAwMDA6MHg..."
},
"checkpoint": 345001999,
"coverage": {}
}- The stakers are the owners of the current
StakedSuiobjects, largest principal first.principalhas no rewards. positionsis the number ofStakedSuiobjects.stakerCountandtotalPrincipalare set on the first page only. On later pages they arenull.
Rewards of a Validator
VALIDATOR=0x... # the validator's Sui address
curl "https://mainnet-api.inodra.com/v1/validators/$VALIDATOR/rewards?epochs=30" \
-H "x-api-key: YOUR_API_KEY"| Parameter | Required | Description |
|---|---|---|
epochs | No | The last N epochs. 1 to 366. Default 30 |
Response 200, newest epoch first:
{
"data": {
"validator": "0x...",
"apy": 0.0231,
"epochs": [
{
"epoch": 1310,
"poolReward": "21043000000000",
"commissionRate": 500,
"commission": "1052150000000",
"storageFundReward": "312000000000",
"validatorReward": "1364150000000",
"stakersReward": "19678850000000",
"exchangeRate": { "sui": "52301000000000000", "token": "49150000000000000" },
"stake": "52301000000000000"
}
]
},
"checkpoint": 345001999,
"coverage": {}
}poolReward- the reward of the pool for the epoch.validatorReward- the validator's own reward:commissionplusstorageFundReward.stakersReward- what was left for stakers.commissionRate- in basis points (500 = 5%).exchangeRate- the pool exchange rate after the epoch.apy- the growth of the exchange rate over the returned epochs, per year.nullwhen it cannot be calculated.
Stake History of a Validator
VALIDATOR=0x4fffd0005522be4bc029724c7f0f6ed7093a6bf3a09b90e62f61dc15181e1a3e
curl "https://mainnet-api.inodra.com/v1/validators/$VALIDATOR/stake-history" \
-H "x-api-key: YOUR_API_KEY"No parameters. Returns every epoch, oldest first. Response 200:
{
"data": {
"validator": "0x4fffd0005522be4bc029724c7f0f6ed7093a6bf3a09b90e62f61dc15181e1a3e",
"epochs": [
{
"epoch": 1311,
"staked": "24520000000",
"stakeRequests": 1,
"unstakedPrincipal": "23868449168",
"unstakedRewards": "210094372",
"unstakeRequests": 6,
"fungibleRedeemed": "0"
}
]
},
"checkpoint": 345001999,
"coverage": {}
}stakedis by request epoch.unstakedPrincipalandunstakedRewardsare by unstaking epoch.fungibleRedeemed- SUI that left the pool byFungibleStakedSuiredemption.
Staking Limits
- A staked object that a protocol keeps inside its own objects shows under the id of the object that owns it (for a dynamic object field, the field object). A wrapped staked object is not visible. So some liquid staking positions are not included.
FungibleStakedSuipositions are not included. Redemptions show instake-historyasfungibleRedeemed.- The chain caps a reward at the rewards balance of the pool. The index does not apply that cap.
Package Stats
PACKAGE=0x0000000000000000000000000000000000000000000000000000000000000002
curl "https://mainnet-api.inodra.com/v1/packages/$PACKAGE/stats?from=2026-11-14&to=2026-11-14" \
-H "x-api-key: YOUR_API_KEY"from and to are the same as for address activity. The longest range is 366 days.
Response 200:
{
"data": {
"packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
"uniqueSenders": 270,
"days": [{ "day": "2026-11-14", "calls": 25541, "transactions": 5904, "uniqueSenders": 270 }]
},
"checkpoint": 345001999,
"coverage": {}
}calls- Move calls into the package.transactions- transactions that call the package.uniqueSendersat the top is the number of distinct senders over the full range.- Each package version has its own id, so the stats of an upgraded package are per version.
TypeScript Example
const address = process.env.SUI_ADDRESS!
const res = await fetch(
`https://mainnet-api.inodra.com/v1/accounts/${address}/balances-at?at=2025-12-31T23:59:59Z`,
{ headers: { 'x-api-key': process.env.INODRA_API_KEY! } }
)
if (!res.ok) {
const { code, error } = await res.json()
throw new Error(`${code}: ${error}`)
}
const { data } = await res.json()
for (const { coinType, balance } of data.balances) {
console.log(coinType, balance)
}Errors
Every error body has error and code. A 409 or 422 error also has coverage. An error costs no credits.
| Status | Code | Cause |
|---|---|---|
400 | NETWORK_NOT_SUPPORTED | The project is not on mainnet |
400 | VALIDATION_FAILED | An address, package id or number has the wrong format |
400 | INVALID_REQUEST | A bad parameter, for example limit, epochs, at, or both at and checkpoint |
400 | INVALID_RANGE | from or to is not a valid day, from is after to, or the range is too long |
400 | INVALID_CURSOR | The cursor is not one that the API gave |
409 | INDEX_NOT_FROM_GENESIS | The index does not start at genesis, so it cannot give absolute values |
422 | OUT_OF_INDEX_RANGE | The time, checkpoint or days are outside coverage |
503 | INDEX_UNAVAILABLE | The index cannot be read now. Try again |
503 | INDEX_QUERY_FAILED | This query failed or timed out. Other endpoints can still work. Try again |