Skip to content

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.

bash
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) and coverage (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 (0x and 64 hex characters).
  • Days are UTC. The first and the last indexed day can be partial.
json
{
  "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 checkpoint shows the point they are current to.
  • Network totals are cached for 30 seconds.

Endpoints ​

EndpointUse
GET /v1/accounts/{address}/balances-atBalances at a point in history
GET /v1/coins/{coinType}/holdersHolder count and top holders of a coin
GET /v1/accounts/{address}/activityActivity of an address per day
GET /v1/chain/stats/dailyNetwork activity per day
GET /v1/chain/stats/totalsNetwork totals
GET /v1/accounts/{address}/stakesStaking positions and rewards
GET /v1/validators/{address}/stakersCurrent stakers of a validator
GET /v1/stakersTop stakers across all validators
GET /v1/validators/{address}/rewardsRewards of a validator per epoch
GET /v1/validators/{address}/stake-historyStake added and withdrawn per epoch
GET /v1/packages/{packageId}/statsCalls and unique users of a package

Balances at a Point in History ​

bash
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.

ParameterRequiredDescription
atNoISO 8601 time or Unix milliseconds (not seconds)
checkpointNoA checkpoint number. Use at or checkpoint, not both
(none)Without at and checkpoint: the last indexed checkpoint

Response 200:

json
{
  "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": {}
}
  • balances has 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.
  • staked is the SUI in StakedSui objects at that point. It is not in balances. See Staking for the fields.
  • A time or checkpoint after the last indexed checkpoint gets 422 OUT_OF_INDEX_RANGE.

Coin Holders ​

bash
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.

ParameterRequiredDescription
limitNo1 to 100. Default 20
cursorNonextCursor from the previous page

Response 200:

json
{
  "data": {
    "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
    "holderCount": 1843211,
    "holders": [{ "address": "0x...", "balance": "912000000000" }],
    "nextCursor": "MTIzOjQ1"
  },
  "checkpoint": 345001999,
  "coverage": {}
}
  • holderCount is set on the first page only. On later pages it is null.
  • nextCursor is null on 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: 0 and no holders.

Address Activity ​

bash
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"
ParameterRequiredDescription
fromNoFirst day, YYYY-MM-DD. Default: 366 days up to to, or less
toNoLast 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:

json
{
  "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 its txSent or txTouched.
  • activeDays - days with at least one sent transaction.
  • firstSeenTimestamp - the first transaction that touched the address. null when it is not known.
  • A day with no activity has no row in days.

Daily Network Stats ​

bash
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"
ParameterRequiredDescription
fromNoFirst day, YYYY-MM-DD. Default: 31 days up to to, or less
toNoLast day, YYYY-MM-DD, included. Default: the last indexed day

The longest range is 31 days.

Response 200:

json
{
  "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 be null for an older day.

Network Totals ​

bash
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:

json
{
  "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": {}
}
FieldMeaning
addressestotal addresses seen on chain, and last24h new ones
coinTypestotal coin types seen in a balance change
commandstotal commands in programmable transactions. null until the daily totals have every day
packagestotal packages created on chain (publish and upgrade), and last24h
tpsHighest 10-second average in 24 hours, 7 days and 30 days, avg24h, and series24h
checkpointsPerSecond24hCheckpoints per second over the last 24 hours
gas24hLast 24 hours, per user transaction: avgFee, medianFee, minFee, maxFee, avgStorageRebate, avgComputationFee
windowsThe time windows used
  • series24h - the average TPS per step over the last 24 hours, oldest first. fromMs and stepMs are in Unix milliseconds. The last step ends at checkpoint and 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 avgFee down, so use medianFee for the typical fee. avgComputationFee is 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 ​

bash
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:

json
{
  "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 by epoch.
  • unrealisedRewards - rewards accrued and not paid out yet.
  • realisedRewards - rewards paid out by unstakes before that point.
  • validator can be null when the pool has no known validator.

Stakers of a Validator ​

bash
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.

ParameterRequiredDescription
limitNo1 to 100. Default 20
cursorNonextCursor from the previous page

Response 200:

json
{
  "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 StakedSui objects, largest principal first. principal has no rewards.
  • positions is the number of StakedSui objects.
  • stakerCount and totalPrincipal are set on the first page only. On later pages they are null.

Rewards of a Validator ​

bash
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"
ParameterRequiredDescription
epochsNoThe last N epochs. 1 to 366. Default 30

Response 200, newest epoch first:

json
{
  "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: commission plus storageFundReward.
  • 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. null when it cannot be calculated.

Stake History of a Validator ​

bash
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:

json
{
  "data": {
    "validator": "0x4fffd0005522be4bc029724c7f0f6ed7093a6bf3a09b90e62f61dc15181e1a3e",
    "epochs": [
      {
        "epoch": 1311,
        "staked": "24520000000",
        "stakeRequests": 1,
        "unstakedPrincipal": "23868449168",
        "unstakedRewards": "210094372",
        "unstakeRequests": 6,
        "fungibleRedeemed": "0"
      }
    ]
  },
  "checkpoint": 345001999,
  "coverage": {}
}
  • staked is by request epoch. unstakedPrincipal and unstakedRewards are by unstaking epoch.
  • fungibleRedeemed - SUI that left the pool by FungibleStakedSui redemption.

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.
  • FungibleStakedSui positions are not included. Redemptions show in stake-history as fungibleRedeemed.
  • The chain caps a reward at the rewards balance of the pool. The index does not apply that cap.

Package Stats ​

bash
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:

json
{
  "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.
  • uniqueSenders at 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 ​

ts
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.

StatusCodeCause
400NETWORK_NOT_SUPPORTEDThe project is not on mainnet
400VALIDATION_FAILEDAn address, package id or number has the wrong format
400INVALID_REQUESTA bad parameter, for example limit, epochs, at, or both at and checkpoint
400INVALID_RANGEfrom or to is not a valid day, from is after to, or the range is too long
400INVALID_CURSORThe cursor is not one that the API gave
409INDEX_NOT_FROM_GENESISThe index does not start at genesis, so it cannot give absolute values
422OUT_OF_INDEX_RANGEThe time, checkpoint or days are outside coverage
503INDEX_UNAVAILABLEThe index cannot be read now. Try again
503INDEX_QUERY_FAILEDThis query failed or timed out. Other endpoints can still work. Try again

The full-stack Sui data layer.