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.

[CollinsKRO]

@CollinsKRO has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Good Day maintainer, pls assign me this issue. I'd love to work on it. Thanks.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @CollinsKRO to this issue.

[Jonathan-ai9]

@Jonathan-ai9 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi,I’d like to work on this issue. I’ll implement GET /wallets/:address/holdings with Stellar address validation, pagination, zero-balance filtering, and portfolio value calculation from the ownership read model. I’ll also add integration tests covering multiple holdings, empty holdings, and invalid address scenarios thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Jonathan-ai9 to this issue.

[pre-cious-Igwealor]

@pre-cious-Igwealor has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, my name is pre-cious-Igwealor, and I am a fullstack and smart contract developer skilled in React, Next.js, JavaScript, TypeScript, Tailwind CSS, and Soroban. For this task, I will:

1. Implement the GET /wallets/:address/holdings endpoint with strict validation logic to return a 400 error for any malformed Stellar address.
2. Query the indexer-maintained key ownership read model to retrieve and map creator IDs, handles, key balances, and current asset prices.
3. Apply server-side database filtering to exclude zero-balance entries, calculate total_value as balance multiplied by current price, and implement cursor or page-based pagination.
4. Write comprehensive integration tests covering a wallet with multiple holdings, an empty wallet returning a 200 status with an empty array, and an invalid address.

ETA: 10 hours

ℹ️ Repo Maintainers: To accept this application, review their application or assign @pre-cious-Igwealor to this issue.