Add wallet holdings endpoint returning all creator keys a fan owns

[Chucks1093]

Summary

Fans have no way to see everything they own in one place. To check their portfolio they would have to query each creator individually, which is not practical. A dedicated holdings endpoint that takes a wallet address and returns all creator keys that wallet holds — with quantities and current values — is the foundation of any portfolio view on the client.

Scope

• Add GET /wallets/:address/holdings endpoint
• Response returns an array of entries: { creator_id, creator_handle, key_balance, current_price, total_value }
• Data is read from the key ownership read model maintained by the indexer (not a live on-chain call)
• Wallet address is validated as a well-formed Stellar address before querying
• Entries with a balance of zero are excluded from the response
• Support pagination for wallets with large holdings

Acceptance Criteria

• Endpoint returns all creators a wallet holds keys in, with correct balances
• Zero-balance entries are excluded
• total_value is calculated as key_balance × current_price from the price snapshot
• Returns 400 for a malformed Stellar address
• Returns an empty array (not 404) for a valid address with no holdings
• Integration test covers: wallet with multiple holdings, wallet with no holdings, invalid address

---

Coordinate on Telegram

[funds0033-cmyk]

Hello, I can pick this up. Adding the GET /wallets/:address/holdings endpoint to pull down a clean portfolio breakdown is straightforward.

I'll ensure the endpoint validates the incoming wallet address as a well-formed Stellar address (returning a 400 if malformed), pulls entries efficiently from the key ownership read model, calculates the total_value, and filters out zero-balance entries. I will also build in pagination support for high-volume wallets and write the necessary integration tests to cover the full range of asset balances and validation states.

I would love to work on this, please assign this to me

[xx7412421-cloud]

Hi maintainers, I'd like to take this issue if it's available.

Planned approach:

• inspect the existing wallet/creator key ownership models and auth context
• add a scoped wallet holdings endpoint for the authenticated fan
• return all creator keys the fan currently owns without exposing unrelated wallet data
• add focused request/response tests for empty, single, and multiple holdings cases

I will wait for assignment before opening a PR so the workflow stays fair.

[Akanimoh12]

Hi, I'd love to work on this issue. I'm a full-stack blockchain developer specializing in web apps and Smart Contracts, with experience in Next.js, TypeScript, Tailwind, and blockchain integration's and writing tests. I can handle this confidently, here's my portfolio and key projects:

• https://frontend-nine-mocha.vercel.app/
• https://i-predict.vercel.app/
• https://somnia-screams.vercel.app/
• https://chessflip-celo.vercel.app/

Active OSS contributor.

[grantfox-oss]

🦊 GrantFox — @Akanimoh12 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 #421)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🦊 GrantFox — @Akanimoh12 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 #421)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.