Feature: Add Wallet Status Balance and History API

[3m1n3nc3]

Description

Expose safe wallet status, public address, exact supported balances, and paginated history.

File Location

Wallet controller/routes/schemas/service, Stellar service, DTOs, and tests

Design Reference

API Roadmap Phase 1: Add Wallet Status Balance and History API.

Dependencies

• Status: Blocked
• Blocked by: Feature: Add Custodial Wallet Persistence and KMS References #135 (Add Custodial Wallet Persistence and KMS References) — done; Feature: Implement Sponsored Stellar Account Funding #91 (Implement Sponsored Stellar Account Funding) — done; Feature: Standardize API Contracts Pagination and Versioning #61 (Standardize API Contracts Pagination and Versioning) — done
• Blocks: Feature: Add Identity Profile Wallet Integration Test Suite #137 (Add Identity Profile Wallet Integration Test Suite)

Tasks

• Add current-user wallet status/address endpoint
• Add supported balance response with asset/issuer/exact amount/source time
• Add stable paginated history with direction, status, amount, hash, ledger, and memo policy
• Normalize Horizon timeout/unavailable/stale behavior
• Prevent arbitrary address lookup
• Test auth, precision, pagination, provider failure, and redaction

Acceptance Criteria

• Only owner wallet is exposed
• Amounts retain exact precision/asset identity
• Pending/failed does not appear as zero balance
• Pagination is stable
• Tests/OpenAPI pass

Verification Evidence

• Attach redacted endpoint examples and Horizon auth/precision/failure tests

Difficulty

Advanced

[Listoncrypt]

Hello, can you assign this issue to me, Expect PR in no time.

[feranmiba]

I’d like to take this task. I’m comfortable working with authenticated APIs, wallet integrations, Stellar data, and blockchain transaction flows.

I’ll focus on strict owner-only wallet access, exact asset/amount precision, stable pagination, proper Horizon failure handling, and comprehensive tests around auth, precision, pagination, and redaction.

I’m happy to take this on as an advanced task and integrate it with the existing wallet architecture.

[Paranoa-dev]

I’d like to take this on. I have experience working across TypeScript backend APIs, Stellar integrations, authentication/authorization boundaries, and pagination-heavy data flows, so I’m comfortable implementing this as a contract-focused wallet API without exposing custodial or provider-sensitive data.

My approach:

• First trace the existing wallet controller/routes, DTOs/schemas, Stellar service, custodial wallet persistence/KMS-reference model from Feature: Add Custodial Wallet Persistence and KMS References #135, sponsored funding flow from Feature: Implement Sponsored Stellar Account Funding #91, and the standardized pagination/versioning conventions from Feature: Standardize API Contracts Pagination and Versioning #61. I’ll also inspect the existing OpenAPI definitions and tests so the new endpoints follow the repository’s established API contract rather than introducing a parallel pattern.
• Add an authenticated current-user wallet status/address endpoint that derives the wallet strictly from the authenticated identity. I’ll explicitly avoid accepting an arbitrary Stellar address as a lookup parameter, preventing the endpoint from becoming an account-enumeration or cross-user wallet-disclosure surface.
• Implement the supported-balance response with the asset code, issuer/network identity, exact amount representation, and source timestamp. Amounts will remain lossless rather than being converted through JavaScript floating-point numbers, and provider failures/stale responses will be represented explicitly instead of silently returning 0 or an apparently valid balance.
• Add stable, deterministic pagination for wallet history. Each record will expose the requested direction/status/amount/hash/ledger fields while applying the existing memo/redaction policy. I’ll use the repository’s pagination contract consistently and make ordering/cursors stable when multiple records share the same timestamp or ledger so records cannot be skipped or duplicated between pages.
• Normalize Horizon/provider failure states into predictable API responses, distinguishing timeout/unavailable/stale data from an actual empty balance/history result. This is particularly important for avoiding the dangerous behavior where a provider outage is interpreted as a zero wallet balance.
• Keep the response limited to safe wallet information. Custodial secret material, KMS references, internal provider details, or another user's wallet information will not be exposed through these endpoints.
• Add focused tests for authentication and ownership boundaries, exact amount/asset preservation, pending and failed transaction handling, stable pagination, duplicate/edge cursor behavior, Horizon timeout/unavailable/stale responses, and sensitive-field redaction.
• Update the OpenAPI contract and ensure the endpoint examples used as verification evidence are redacted and contain no secret material or unnecessary personal data.

I’ll specifically verify that:

1. an authenticated user can only retrieve their own wallet;
2. exact Stellar amounts and asset identity survive the API/service boundary without floating-point rounding;
3. pending/failed operations cannot be represented as a misleading zero balance;
4. pagination remains deterministic across repeated requests and boundary conditions; and
5. Horizon failures cannot be mistaken for successful empty results.

I’ll keep this scoped to the wallet status/balance/history API and its required service, DTO, schema, OpenAPI, and test changes. I won’t redesign the custodial/KMS architecture already delivered by #135 or duplicate the sponsored-funding work from #91.

Estimate: I can open the first draft PR within 2–3 days of maintainer assignment.

[daxvinci]

hello, I would love to work on this with you....i am sure i can put my skills to work here