feat: add market imbalance and ledger timing endpoints, implement account counterparties analysis, and modularize asset parsing logic

[Folex1275]

Summary

This PR implements four new developer utility endpoints to provide advanced analytics for Stellar DEX, accounts, and network health. It also includes a refactoring of the asset parsing logic to improve codebase maintainability.

Features

1. DEX Order Book Imbalance Detector (#148)

• Endpoint: GET /dex/imbalance/:sellAsset/:buyAsset
• Analyzes buy vs. sell volume in the order book (limit 200).
• Calculates imbalanceRatio and identifies market pressure ("buy", "sell", or "neutral").
• Provides a plain-English signal for developers.

2. Payment Counterparty Frequency Analyzer (#149/150)

• Endpoint: GET /account/:id/counterparties
• Analyzes the last 100 payment operations for an account.
• Identifies the top 10 senders and top 10 receivers based on transaction count.
• Includes validation for account IDs.

3. Network Ledger Close Time Analyzer (#151)

• Endpoint: GET /network/ledger-timing
• Fetches the last 50 ledgers and analyzes close intervals.
• Calculates avgCloseTimeSeconds, minCloseTime, maxCloseTime, and stdDeviation.
• Categorizes network consistency as "stable", "variable", or "unstable".

Architectural Changes

• Refactored Asset Parsing: Extracted parseStellarAsset into a standalone utility (src/utils/asset.js) to reduce code duplication and ensure consistent handling of CODE:ISSUER and XLM:native formats across the API.

Technical Details

• Added detailed JSDoc documentation for all new endpoints.
• Updated root API documentation in src/index.js.
• Added comprehensive test suites for all new features in the tests/ directory.

Acceptance Criteria Checklist

• GET /dex/imbalance/:sellAsset/:buyAsset implemented and tested.
• GET /account/:id/counterparties implemented and tested.
• GET /network/ledger-timing implemented and tested.
• Refactored asset parsing logic.
• Updated root API documentation.

Closes #148
Closes #149
Closes #150
Closes #151

[drips-wave]

@Folex1275 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits