Skip to content

feat(wallet): add wallet status, balance, and history endpoints - #157

Merged
Kaylahray merged 2 commits into
learnault:mainfrom
daxvinci:feat/wallet-status
Aug 30, 2026
Merged

feat(wallet): add wallet status, balance, and history endpoints#157
Kaylahray merged 2 commits into
learnault:mainfrom
daxvinci:feat/wallet-status

Conversation

@daxvinci

Copy link
Copy Markdown
Contributor

Closes #151

Wallet Status, Balance, and History API

Overview

Implements the Phase 1 roadmap item "Add wallet provisioning status,
public address, supported asset balance, and transaction history
endpoints" as specified in the API Roadmap and the linked issue.

Depends on #135 (custodial wallet persistence + KMS references), #91
(sponsored account funding), and #61 (pagination/versioning
conventions) — all done. Unblocks #137 (identity/profile/wallet
integration test suite).

Changes Made

New Files

  • src/types/wallet-status.types.ts — status/balance/history view
    types and WalletStatusError
  • src/schemas/wallet-status.schema.ts — zod query schema for
    history pagination/direction
  • src/services/wallet-status.service.ts — orchestrates the
    authenticated user's own wallet only
  • src/controllers/wallet-status.controller.ts — status/balances/
    history handlers
  • src/routes/v1/wallet.routes.ts — mounts /api/v1/wallet
  • tests/wallet-status.service.test.ts,
    tests/wallet-status.controller.test.ts,
    tests/stellar-wallet-status.service.test.ts — 32 tests

Modified Files

  • src/services/stellar.service.ts — added getAccountSnapshot()
    and getPaymentHistory(), plus Horizon error classification and
    memo-redaction helpers
  • src/routes/index.ts — registered wallet routes

Implemented Endpoints

GET /api/v1/wallet/status

Returns provisioning status (NOT_PROVISIONED / PENDING /
ACTIVE / UNAVAILABLE), network, custody, public key (only when
ACTIVE), and provisionedAt.

GET /api/v1/wallet/balances

Returns exact balances (assetType, assetCode, issuer, amount
as a string) plus the account's Horizon sourceTime. An account that
hasn't received its ledger entry yet returns an empty balance list,
not an error or a fabricated zero.

GET /api/v1/wallet/history

Cursor-paginated (cursor, limit, direction=all|incoming|outgoing)
payment history: direction, status (success/failed), asset,
amount, transactionHash, ledger, createdAt, and a policy-applied
memo/memoType. Cursor is Horizon's own paging_token, so results
stay stable under concurrent ledger writes.

Security / Design Notes

  • No address parameter is accepted anywhere — only req.user.id's own
    wallet can ever be read.
  • Horizon 404 (account not yet funded) is treated as a normal empty
    state, never as a false zero balance.
  • Horizon timeouts/unavailability are normalized to stable
    HORIZON_TIMEOUT (504) / HORIZON_UNAVAILABLE (503) responses
    instead of leaking provider internals.
  • Text memos are stripped of control characters and length-capped;
    hash/id/return memos are passed through as-is (already public
    on-chain data).

Tests

32 new unit tests — auth/ownership, exact-precision balances,
unfunded-account handling, provider failure normalization, direction
filtering, cursor stability, and redaction of internal errors. All
passing via pnpm exec vitest run tests/wallet-status.service.test.ts tests/wallet-status.controller.test.ts tests/stellar-wallet-status.service.test.ts.

image

@Kaylahray
Kaylahray merged commit 41056eb into learnault:main Aug 30, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Add Wallet Status Balance and History API

2 participants