Voting Power

The Voting Power feature exposes each token holder's delegated governance weight on chain.

Use this page when you need API paths for direct or relayed delegations, delegation history, or the current weight distribution. For the product model, see Voting Power architecture. For operator steps, see Voting Power how-to.

Configuration

No featureConfigs entry is required. voting-power is the API identifier for this feature. It accepts no feature-specific settings at token creation time. You can omit it from featureConfigs entirely, or pass an empty object.

Mutations

A direct delegation uses the selected wallet, which must be registered in the token identity registry. The signature-based path relays signed data; the Platform API validates the signer before queuing the transaction.

Reads

To query holder balances at a snapshot timepoint, use the historical-balances endpoints. The two features answer different questions: Voting Power tracks delegated governance weight, while Historical Balances tracks token balances and total supply over time.

Current voting power distribution

The distribution read returns a current weight breakdown: the largest delegates listed individually, with every remaining delegate rolled into one aggregate. This read powers a holder-concentration view without paging through the full delegate tail.

GET /api/v2/tokens/{tokenAddress}/voting-power/distribution?topN=50

The topN query parameter sets how many top delegates to return individually. The value ranges from 1 to 200 and defaults to 50. Every delegate beyond the top set is combined into a single other bucket.

The read returns the latest recorded weight per delegate. Delegates whose current weight is zero are excluded, so the result reflects live, non-zero voting power. A holder who delegates to another address counts toward that delegate's weight rather than appearing under their own address. If the token has no Voting Power feature attached, the read returns an empty distribution rather than an error.

The response is a single object under data:

Each entry in holders reports:

The other bucket reports:

Because total and the other bucket report the full set, you can compute each top delegate's share of the whole without reading the remaining delegates. To read a single delegate's exact frozen weight at a past block, use the snapshot-weights read below.

Snapshot weights at a block

A vote weights each holder by their voting power at a fixed record date, not their current power. An auditor, scrutineer, or governance integration needs to read that frozen weight set to verify quorum, recompute a tally, or reconstruct who could vote and with how much. This read returns exactly that set for any past block.

GET /api/v2/tokens/{tokenAddress}/voting-power/snapshot-weights?block=21000000

The block query parameter is required and sets the snapshot point. For each account, the read returns the most recent voting weight recorded at or before that block. The account is the address that carries the voting weight, which is the delegate the weight resolves to: a holder who delegates to another address contributes to that delegate's weight rather than appearing under their own address. Accounts whose voting weight was zero at the snapshot are omitted, so the response lists only accounts that carried votable weight at that block. If the token had no Voting Power feature attached at the requested block, the read returns an empty result rather than an error.

Each row reports:

Results page with the standard collection envelope (data, meta, links) and sort by votesExact descending by default, so the largest holders surface first. Sort instead by account, asOfBlockNumber, or asOfBlockTimestamp with sortBy and sortDirection. To read one account's snapshot weight, pass filter[account]=0x...; the account filter takes a single address and matches exact equality only.

Related

• Historical Balances: balance checkpoints and snapshot reads.
• Voting Power architecture: the feature model and constraints.
• Voting Power how-to: operator workflow steps.