---
title: "Prime Services Core Concepts"
description: "This guide defines the core patterns you should adopt before building against Galaxy APIs."
url: "https://docs.api.galaxy.com/guides/galaxyone/core-concepts"
image: "https://docs.api.galaxy.com/_og/d/c_Ocean.takumi,title_Prime+Services+Core+Concepts,description_This+guide+defines+the+core+patterns+you+should+adopt+before+building+against+Galaxy+APIs.,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiI2ZmNWExZiJ9fX0,p_Ii9ndWlkZXMvZ2FsYXh5b25lL2NvcmUtY29uY2VwdHMi,s_sgY5q4HfLmxx8hUF.png"
---

# Prime Services Core Concepts

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

## [1\. Operating Model](#_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](#_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](https://docs.api.galaxy.com/guides/authentication.md) for full details.

## [3\. Environment Isolation](#_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](https://docs.api.galaxy.com/guides/getting-started/environments.md).

## [4\. Access Control](#_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](#_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](#_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](#_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](#_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](https://docs.api.galaxy.com/guides/galaxyone/idempotency.md).

## [9\. Event-Driven Integration and Security](#_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](#_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](https://docs.api.galaxy.com/guides/galaxyone/errors.md) and [Rate Limits](https://docs.api.galaxy.com/guides/galaxyone/rate-limits.md).

## [11\. Observability and Operations](#_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](#_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

## [Related Pages](#related-pages)

-   [Getting Started](https://docs.api.galaxy.com/guides/galaxyone/getting-started.md)
-   [Authentication](https://docs.api.galaxy.com/guides/galaxyone/authentication.md)
-   [Errors](https://docs.api.galaxy.com/guides/galaxyone/errors.md)
-   [Rate Limits](https://docs.api.galaxy.com/guides/galaxyone/rate-limits.md)
-   [Idempotency](https://docs.api.galaxy.com/guides/galaxyone/idempotency.md)