Search
K

Prime Services Core Concepts

This guide defines the core patterns you should adopt before building against Galaxy APIs.

1. Operating Model

Galaxy is an API-first organization:

  • Galaxy provides a the GalaxyOne Prime UI to customers.
  • Galaxy provides FIX and REST APIs for various services (Trading, Custody, Lending)

2. Authentication Model

Galaxy APIs use OAuth 2.0 Client Credentials for machine-to-machine access.

  • Request a token from your environment's auth endpoint
  • Include Authorization: Bearer <token> on each API request
  • Cache tokens and refresh before expiration

See Authentication for full details.

3. Environment Isolation

Each environment has distinct API and auth endpoints, credentials, and policy scopes.

  • UAT: end-to-end acceptance validation
  • Production: live traffic only

Do not mix credentials or resource identifiers across environments.

See Environments.

4. Access Control

Successful authentication does not guarantee endpoint access.

Access is controlled by:

  • OAuth scopes (for example api:read, api:write)
  • Consumer-group / ACL policy mappings

Typical outcomes:

  • 401: token problem (missing, invalid, expired)
  • 403: authenticated but not authorized for that resource

5. Spot Trading and Settlement Behavior

For the documented spot workflow pattern:

  • Trading is pre-funded
  • Execution behavior is modeled as Fill-or-Kill
  • A successful fill is treated as final
  • Balance updates and settlement effects are immediate in workflow terms

Application implications:

  • Drive post-trade state transitions directly from successful fill outcomes
  • Avoid designs that assume delayed settlement for this workflow pattern

6. Request Design

For reliable integrations:

  • Set explicit timeouts on all outbound requests
  • Include correlation IDs in requests/logs where supported
  • Validate request payloads before submission
  • Use pagination parameters on list endpoints

7. Custody and Asset Movement Controls

Baseline custody workflow assumptions:

  • Deposit addresses are retrieved programmatically and deposits are credited after required confirmations
  • Withdrawals are API-initiated with destination control constraints
  • Withdrawal processing may include approval-path behavior above configured thresholds

Design your client operations to handle both automated and approval-path withdrawal states.

8. Idempotent Write Operations

All write operations should be designed for safe retries.

  • Use idempotency keys where supported
  • Reuse the same key only for retries of the same logical operation
  • Never reuse a key with a different payload

See Idempotency.

9. Event-Driven Integration and Security

Use webhooks as a first-class integration surface for custody/staking lifecycle updates.

Recommended controls:

  • Verify webhook signatures and claims
  • Validate payload integrity against raw request bytes
  • Implement replay-safe processing
  • Reconcile event streams with API query state

10. Error and Retry Strategy

Build explicit handling for:

  • Non-retryable client errors (400, 403, 404, 422)
  • Retryable pressure/transient responses (429, 500, 502, 503, 504)
  • Token refresh flow for 401

Use bounded exponential backoff with jitter for retries.

See Errors and Rate Limits.

11. Observability and Operations

At minimum, monitor:

  • Authentication failures
  • Request latency and error rate
  • Rate-limit events
  • Retry attempt volume and exhaustion

Log structured request metadata and error classification, but never secrets or tokens.

12. Build Sequence

Recommended implementation order:

  1. Environment + credential setup
  2. Token acquisition and caching
  3. First successful read request
  4. Error classification and retry framework
  5. Core workflow integration (trading, custody, and asset servicing in scope)
  6. Webhook/event integration and reconciliation
  7. Idempotent write flows
  8. Monitoring, alerting, and production readiness checks