Add key holders list endpoint so creators can see who holds their keys

[Chucks1093]

Summary

Creators currently have no way to see who is in their community. Knowing which wallets hold your keys — and how many — is basic information a creator needs to understand their audience and reward their most loyal supporters. This endpoint turns the key ownership read model into a useful creator-facing feature.

Scope

• Add GET /creators/:id/holders endpoint
• Response returns a paginated list of: { wallet_address, key_balance, held_since }
• held_since is the timestamp of the wallet's first buy for this creator
• Default sort is by key_balance descending (largest holders first)
• Support sort=held_since to surface earliest supporters first
• Entries are sourced from the indexer's ownership read model

Acceptance Criteria

• Returns paginated list of holder wallets with correct balances
• Default sort is largest balance first
• sort=held_since returns earliest buyers first
• held_since reflects the timestamp of the wallet's first buy transaction for that creator
• Returns 404 if the creator does not exist
• Returns empty list (not 404) if creator exists but has no holders
• Integration test covers: multiple holders, empty holders, both sort modes

---

Coordinate on Telegram

[shadrach68]

I would like to work on this issue because I am a full-stack developer with 5+ years experience. I focus on identifying root causes and delivering clean, efficient, and maintainable solutions, with thorough testing to ensure reliable results.

[funds0033-cmyk]

Hello, I can take this on. Adding the GET /creators/:id/holders endpoint and setting up the paginated response from the indexer's ownership model is straightforward.

I'll build out the endpoint to return the required fields (wallet_address, key_balance, held_since), implement the default sorting by largest balance, and support the sort=held_since parameter for earliest supporters. I'll also ensure the proper 404 handling for non-existent creators and write the integration tests covering multiple holders, empty lists, and both sorting modes. kindly assign this to me

[chiscookeke11]

Hello chief, please I would like to work on this, ETA: 48 hrs

[Emmy123222]

Hi,

I'd like to take on this issue.

I understand the goal is to expose the ownership read model through a creator-facing endpoint that allows creators to view and analyze their key holders.

My implementation plan:

• Add GET /creators/:id/holders with pagination support.
• Return wallet_address, key_balance, and held_since for each holder.
• Use the indexer's ownership read model as the source of truth.
• Implement default sorting by key_balance descending.
• Add sort=held_since to return earliest supporters first.
• Ensure held_since is derived from the wallet's first buy transaction for the creator.
• Return 404 when the creator does not exist.
• Return an empty list when a creator exists but has no holders.
• Add integration tests covering multiple holders, empty holders, creator not found, and both sorting modes.

I have experience working with TypeScript, APIs, indexing/data models, and Web3 applications, and I'm confident I can deliver this feature according to the acceptance criteria.

Looking forward to contributing. Thanks!

[Temi-suwa18]

Gm GM, I will approach this by adding a new GET /creators/:id/holders endpoint that retrieves holder data from the indexer's ownership read model. I will validate the creator exists before processing the request and return a 404 if it does not. The endpoint will expose wallet_address, key_balance, and held_since, where held_since is derived from the holder's first buy transaction. I will implement pagination support and default sorting by key_balance in descending order. I will also add support for sort=held_since to highlight earliest supporters. Finally, I will create integration tests covering multiple holders, empty holder lists, creator-not-found scenarios, and both sorting modes.
Please assign me this

[grantfox-oss]

🦊 GrantFox — @Temi-suwa18 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #422)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Temi-suwa18's PR #428 was approved and merged by @Chucks1093.

🏆 @Temi-suwa18: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (118 total points). Track your full progress on GrantFox.

👏 Great work, @Temi-suwa18! Keep contributing to accesslayerorg.