Skip to main content

94. Direct Bybit API Integration

Status: Accepted Date: 2025-07-06

Context​

The Apollo portfolio analysis engine requires real-time access to a user's portfolio data, including their current positions, P&L, margin, and leverage. The primary exchange supported by the Mercury system is Bybit. We need a way to fetch this data reliably and securely.

Decision​

The Apollo module will integrate directly with the official Bybit REST API (v5) to fetch portfolio data.

A dedicated BybitService will be created to encapsulate all the logic for interacting with the Bybit API. This service will be responsible for:

  • Making authenticated requests to the relevant Bybit endpoints (e.g., /v5/position/list, /v5/account/wallet-balance).
  • Handling Bybit's specific authentication requirements (API key, secret, and signature generation).
  • Parsing the API responses into clean, strongly-typed internal data models.
  • Managing API rate limits and handling connection errors gracefully.

The user will be required to provide their Bybit API key and secret, which will be stored securely and used by the BybitService to make requests on their behalf.

Consequences​

Positive:

  • Real-Time Data: Integrating directly with the exchange API ensures that our analysis is based on the most up-to-date data possible.
  • Single Source of Truth: The exchange is the ultimate source of truth for a user's portfolio. By going directly to the source, we avoid any potential discrepancies that could arise from an intermediate data layer.
  • Full Access to Data: Direct integration gives us access to the full richness of data provided by the Bybit API, allowing us to build more sophisticated analysis features in the future.

Negative:

  • Dependency on an External Service: Our portfolio analysis feature is now directly dependent on the availability and reliability of the Bybit API. An outage at Bybit will cause our feature to fail.
  • Security Risk: The system needs to store and manage sensitive user API keys. If these keys are compromised, an attacker could potentially access or even trade on the user's account.
  • Complexity of API Integration: Exchange APIs can be complex and have quirks. We are responsible for correctly implementing the authentication, handling rate limits, and keeping up with any changes to the API.

Mitigation:

  • Resilient Service Design: The BybitService will be built with resilience in mind. It will implement robust error handling, connection retries with exponential backoff, and graceful degradation. If the Bybit API is down, the system will report a clear error to the user.
  • Secure Key Management: User API keys will be encrypted at rest and in transit. They will be stored in a secure vaulting system (like HashiCorp Vault) and only accessed by the BybitService when needed. The API keys will be configured with the minimum required permissions (e.g., read-only access, no withdrawal rights).
  • Use Official SDKs/Libraries: We will use the official bybit-api library or a well-maintained community equivalent to handle the low-level details of authentication and request signing, reducing the risk of implementation errors.