Centrifuge Indexer — queries & opportunities

query InvestorPosition($tokenId: String!, $centrifugeId: String!, $account: String!) {
  tokenInstancePosition(tokenId: $tokenId, centrifugeId: $centrifugeId, accountAddress: $account) {
    balance costBasis cumulativeEarnings cumulativeRealizedPnl tokenPriceAtLastChange isFrozen updatedAt
  }
}

Why it matters

The Portfolio tab currently has no earnings number, and deriving one client-side means replaying every deposit at its execution price. The indexer already does this. costBasis is in pool currency (18dp), balance in share base units.

Watch out

Position rows are per token instance (share class × chain). When we add a second chain a wallet will have one row per chain and the app must sum them.

query InvestorActivity($tokenId: String!, $accounts: [String], $limit: Int!, $after: String) {
  investorTransactions(
    where: { tokenId: $tokenId, account_in: $accounts }
    orderBy: "createdAt", orderDirection: "desc", limit: $limit, after: $after
  ) {
    totalCount
    items { type tokenAmount currencyAmount tokenPrice createdAt createdAtTxHash fromAccount toAccount }
    pageInfo { hasNextPage endCursor }
  }
}

Why it matters

We already run this exact entity for a boolean. Selecting the items instead gives us a history view for free, including wallet-to-wallet transfers that no other source records.

Watch out

On our test pool every row is TRANSFER_IN / TRANSFER_OUT — 120 rows, zero SYNC_DEPOSIT or REDEEM_*. Sync deposits appear as the share leg only, with currencyAmount and tokenPrice both 0. So this entity is a share ledger, not a USDC ledger — pair it with #3 for economics, and re-verify the type distribution on mainnet.

query Issuances($tokenId: String!, $since: String!) {
  tokenIssuances(
    where: { tokenId: $tokenId, createdAt_gt: $since }
    orderBy: "createdAt", orderDirection: "desc", limit: 1000
  ) {
    totalCount
    items { type shares pricePoolPerShare isManual account createdAt createdAtTxHash }
  }
}

Why it matters

Daily net inflow in USD without diffing issuance snapshots, and it is the only place the execution price is attached to the flow. isManual separates manager-side issuance from investor deposits — exactly the split we want when reporting organic growth.

Watch out

On REVOKE the account is the escrow, not the redeeming investor, so this cannot attribute redemptions per user.

query EarningsTimeline($tokenId: String!, $account: String!) {
  investorPositionCheckpoints(
    where: { tokenId: $tokenId, accountAddress: $account }
    orderBy: "createdAt", orderDirection: "asc", limit: 1000
  ) {
    items { balanceBefore balanceAfter tokenPrice periodEarnings cumulativeEarnings realizedPnl trigger createdAt }
  }
}

Why it matters

Turns #1 from a single number into a chart. trigger tells you why the checkpoint exists (tokenInstance:Transfer, price update, …), which makes it readable as a statement.

Watch out

Checkpoints fire on balance changes, not daily — a dormant holder has a flat line with no points.

query Capacity($tokenId: String!) {
  vaults(where: { tokenId: $tokenId, status: "Linked" }) {
    items { id kind status maxReserve assetAddress }
  }
  holdingEscrows(where: { tokenId: $tokenId }) {
    items { assetId assetAmount assetPrice escrowAddress updatedAt }
  }
}

Why it matters

Today the “instant liquidity available” number needs a connected client and an RPC multicall, so the landing page cannot show it and the server cannot cache it. This makes capacity a server-rendered, cacheable number.

Watch out

Indexer state lags the chain by a block or two — fine for a marketing figure, not for the pre-sign gate. Keep the RPC read as the authority at transaction time. On Sepolia maxReserve is uint128 max (effectively uncapped).

query RedemptionQueue($tokenId: String!) {
  epochOutstandingRedeems(where: { tokenId: $tokenId }) {
    items { assetId pendingSharesAmount queuedSharesAmount updatedAt }
  }
  epochOutstandingInvests(where: { tokenId: $tokenId }) {
    items { assetId pendingAssetsAmount queuedAssetsAmount }
  }
}

Why it matters

This is the single number that tells the manager how much USDC must be raised to clear the queue, and it is the honest input to any user-facing “current wait time” copy. We have no visibility into it today — vault.investment() only shows the connected wallet’s own pending amount.

Watch out

Empty on our test pool right now (the queue is clear), so the shape is confirmed but not the population. Pair with #7 before publishing a wait-time estimate.

query RedeemEpochs($tokenId: String!) {
  epochRedeemOrders(
    where: { tokenId: $tokenId }
    orderBy: "index", orderDirection: "desc", limit: 100
  ) {
    totalCount
    items {
      index approvedAt approvedSharesAmount approvedPercentageOfTotalPending
      revokedAt revokedSharesAmount revokedAssetsAmount revokedWithNavAssetPerShare
    }
  }
}

Why it matters

approvedAt → revokedAt is the measured processing time; the historical distribution is what should drive the “typically N days” copy in the redeem flow instead of a hardcoded guess. approvedPercentageOfTotalPending exposes partial fills — on our test pool epoch 16 was approved at 50%.

Watch out

Amounts are per asset id; with one asset (USDC) this is a clean series. Percentages are scaled 1e18 × 100 (1000000000000000000000 = 100%).

{ _meta { status } }
# { "ethereum": { "id": 11155111, "block": { "number": 11363759, "timestamp": 1785181896 } }, ... }

Why it matters

We currently trust the indexer blindly: if it stalls, the landing hero and the chart silently show yesterday’s numbers with no alert. One cheap field turns that into a warning and, if we want, a “data may be delayed” badge.

Watch out

status is untyped JSON, so it needs its own runtime schema rather than generated types.

query VaultInventory($tokenId: String!) {
  vaults(where: { tokenId: $tokenId }) {
    items { id kind status isActive assetAddress manager factory centrifugeId updatedAt }
  }
}

Why it matters

Our test share class has three vaults, two of them Unlinked, and one is an Async vault on the same USDC address as our linked SyncDepositAsyncRedeem one. Picking the wrong one is a silent, total breakage. A CI or boot-time assertion against this query makes the configured vault and router addresses self-verifying — which matters most at mainnet cutover.

Watch out

status can be LinkInProgress / UnlinkInProgress mid-governance; treat anything but Linked as a failed assertion, not as a reason to switch vaults.

query PricePublications($tokenId: String!) {
  tokenSnapshots(
    where: { id: $tokenId, trigger_contains: "UpdatePricePoolPerShare" }
    orderBy: "timestamp", orderDirection: "desc", limit: 30
  ) {
    totalCount
    items { timestamp tokenPriceComputedAt tokenPrice }
  }
}

Why it matters

A stale price is exactly the precondition for the InvalidPrice revert that our deposit flow already has copy for (“The current deposit price is unavailable”). Watching the publication cadence turns a user-visible failure into an internal alert hours earlier. We already fetch tokenPriceComputedAt and carry it in the payload — nothing consumes it.

Watch out

timestamp (when indexed) and tokenPriceComputedAt (the manager’s valuation date) differ by days on our test pool. The staleness that matters is the latter.

query Restrictions($tokenId: String!, $account: String!, $centrifugeId: String!) {
  whitelistedInvestor(tokenId: $tokenId, centrifugeId: $centrifugeId, accountAddress: $account) {
    isFrozen validUntil updatedAt
  }
  tokenInstancePositions(where: { tokenId: $tokenId, isFrozen: true }) {
    totalCount
    items { accountAddress balance updatedAt }
  }
}

Why it matters

We deliberately run without KYC or allowlisting, so the eligibility half of this entity is irrelevant — but isFrozen is not. A frozen wallet gets TransferBlocked, for which our deposit and redeem flows both show the vague “can’t be completed for this wallet right now”. Reading the flag lets us say something accurate, and lets ops see the freeze list. The test pool has 7 whitelist rows with validUntil at uint32 max — i.e. permanent, which is what “no allowlist” looks like in this schema.

Watch out

Freezes propagate cross-chain via UpdateRestriction messages, so the indexer may show a freeze that has not landed on the spoke yet (see #14).

query Holders($tokenId: String!) {
  tokenInstancePositions(
    where: { tokenId: $tokenId, balance_gt: "0" }
    orderBy: "balance", orderDirection: "desc", limit: 100
  ) {
    totalCount
    items { accountAddress balance updatedAt }
  }
}

Why it matters

A “N holders” stat tile next to TVL, and a concentration figure for the transparency page. It is one query with no wallet connection required.

Watch out

The pool escrow appears as a holder. On our test pool 0x8fcd…3acd is both the escrow address in holdingEscrows and a top position in this list, because pending redeem shares are custodied there. Filter escrow addresses out before publishing a count.

query YieldSurface($tokenId: String!) {
  tokenSnapshots(where: { id: $tokenId }, orderBy: "timestamp", orderDirection: "desc", limit: 1) {
    items {
      yield7d365 yield30d365 yield90d365 yield180d365
      yield30dComp365 yieldTtm yieldYtd yieldSinceInception
    }
  }
}

Why it matters

We read exactly one of these. yield30dComp365 is null for the first 30 days of a pool’s life — which is precisely the mainnet launch window where we most want a number on the page. yieldSinceInception is populated from day one and is the honest headline for a young pool.

Watch out

All Ray-scaled (1e27). Short windows are extremely noisy when annualised — our test pool shows a 7-day figure of ~341% after a few manual price bumps. Pick windows deliberately, not because they exist.

query PoolMessages($poolId: BigInt!) {
  crosschainMessages(
    where: { poolId: $poolId }
    orderBy: "createdAt", orderDirection: "desc", limit: 50
  ) {
    items { messageType status failReason fromCentrifugeId toCentrifugeId createdAt executedAt }
  }
  poolSpokeBlockchains(where: { poolId: $poolId }) { items { centrifugeId createdAt } }
}

Why it matters

The moment we add a second chain, “is the share class actually live over there?” becomes a real question, and this is the answer. It is already useful: our test pool has 5 messages, several stuck at AwaitingBatchDelivery since deployment, including SetRequestManager and UpdateRestriction to centrifugeId 2.

Watch out

A stuck message is normal during batching; only sustained non-delivery is a signal. Alert on age, not on status alone.

query Backing($tokenId: String!) {
  holdings(where: { tokenId: $tokenId }) {
    items { assetId assetQuantity totalValue isLiability valuation updatedAt }
  }
  holdingEscrows(where: { tokenId: $tokenId }) {
    items { assetId assetAmount assetPrice maxAssetPriceAge escrowAddress updatedAt }
  }
  holdingSnapshots(
    where: { tokenId: $tokenId }, orderBy: "timestamp", orderDirection: "desc", limit: 90
  ) {
    items { timestamp assetId assetQuantity totalValue }
  }
}

Why it matters

The Asset Allocation panel is currently sourced outside Centrifuge. As holdings move on-chain, this is the query that makes that panel verifiable — and holdingSnapshots gives it history for free.

Watch out

Confirmed empty on our test pool. holdings returns no items while holdingEscrows returns the 14.04 USDC reserve, i.e. hub-side holdings are not initialised on this deployment. Re-verify against mainnet before designing UI on it.