Core Concepts

This document explains the fundamental entities and relationships in the PRIME platform. Understanding these concepts is essential for working with the API effectively.

Trading Venues

PRIME supports two trading modes:

Sub-accounts are configured for a specific venue, determining which trading mode is available.

---

Entity Hierarchy

┌─────────────────────────────────────────────────────────────────────────┐
│                              Platform                                   │
│                                                                         │
│   ┌─────────────┐         ┌──────────────────┐         ┌─────────────┐  │
│   │    User     │────────►│  Client Account  │────────►│ Sub-Account │  │
│   │             │   N:1   │                  │   1:N   │ (Portfolio) │  │
│   └─────────────┘         └──────────────────┘         └─────────────┘  │
│         │                          │                          │         │
│         │                          │                          │         │
│    Authentication            Compliance/KYC              Trading        │
│    Permissions               Verification                Balances       │
│    Roles                     Fee Agreements              Orders         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

User

A User is an authentication identity that operates within a Client Account.

Key Properties

Permissions

User permissions are controlled through Actions applied to Domains. See the Permission Model section for details.

Roles

Users have role-based access control:

Front Office Roles:

• ROLE_FO_CA_OWNER - Client Account owner (full access)
• ROLE_FO_TRADER - Trading permissions only
• ROLE_FO_ISSUER - Issuer-specific operations

---

Client Account

A Client Account represents a legal entity (individual or company) that has a relationship with the platform. This is the compliance and regulatory boundary.

Key Properties

Verification Status

Client Accounts must be verified before trading is enabled:

Trading Eligibility

A Client Account can trade only when:

• status = ACTIVE
• verificationStatus = VERIFIED

---

Sub-Account (Portfolio)

A Sub-Account (also called a Portfolio) is a segregated trading account under a Client Account. It enables clients to partition their holdings and trading activity.

Why Portfolios?

• Segregation: Separate balances and trading history
• Access Control: Different users can access different portfolios
• Pair Restrictions: Limit which trading pairs are available
• Venue Separation: Exchange vs OTC trading

Key Properties

Trading Eligibility

A Sub-Account can trade only when:

• Parent Client Account can trade (verified and active)

---

Instruments

An Instrument represents any tradable asset on the platform.

Instrument Types

Key Properties

Usage Pattern

Fetch instruments first to obtain UUIDs needed for other operations:

GET /api/rest/v1/instruments
→ Returns list with id, symbol, type, decimals, etc.
→ Use the `id` field in balance queries, deposit addresses, etc.

---

Pairs

A Pair represents a trading relationship between two instruments (base/quote).

Structure

Pair: BTC/CHF
├── Base Instrument: BTC (what you're buying/selling)
├── Quote Instrument: CHF (what you're paying/receiving)
└── Symbol: "BTC/CHF"

Key Properties

Trading Constraints

When placing orders, respect the pair's constraints:

• Quantity: Must be between minOrderQuantity and maxOrderQuantity
• Precision: Quantity must respect quantityDecimalPoints and quantityTicks
• Price: Must respect priceDecimalPoints and priceTicks
• Status: Pair must be OPEN to trade

Usage Pattern

Fetch pairs to understand available markets and get IDs for orders:

GET /api/rest/v1/pairs
→ Returns list with id, symbol, base/quote instruments, constraints
→ Use the `id` field when placing orders

---

ID References Across APIs

Most API operations require entity IDs obtained from previous queries:

Typical Flow

1. Authenticate → Receive JWT token
2. Get Sub-Accounts → Obtain sub-account id for your portfolio
3. Get Instruments → Obtain instrument id for assets you need
4. Get Pairs → Obtain pair id for trading pairs
5. Execute Operations → Use collected IDs in trading/payment endpoints

---

Entity Lifecycle

Creating a Trading Setup

1. User registers/is created
   └─► User linked to Client Account

2. Client Account completes KYC
   └─► verificationStatus: UNVERIFIED → VERIFIED

3. Sub-Account created
   └─► Sub-account ready for trading

4. User granted Sub-Account access
   └─► Permissions assigned (read, trade, withdraw, etc.)

5. Trading enabled
   └─► User can place orders on permitted pairs

Permission Checks

Every API request validates:

1. Authentication: Valid JWT token with user identity
2. User Status: User must be ACTIVE
3. Client Account: Must be ACTIVE and VERIFIED (for trading)
4. Sub-Account Access: User must have access to the sub-account
5. Operation Permission: User must have required permission (trade, withdraw, etc.)
6. Resource Constraints: Pair restrictions, trading limits, etc.

---

Permission Model

Permissions are controlled through a combination of Actions and Domains.

Actions

Actions define what operations a user can perform:

Domains

Domains define the scope where permissions apply. Each domain is scoped to a client account and optionally a sub-account:

How Permissions Work

Permissions are evaluated against a domain path that includes:

• User type (fo for Front Office, bo for Back Office)
• Domain type (e.g., private/subaccount)
• Client Account ID
• Sub-Account ID (for sub-account scoped domains)

For example, to place a trade, a user needs:

1. trade action on the private/subaccount domain for that sub-account
2. trade action on the private/pair domain for the trading pair
3. trade action on the private/instrument domain for both base and quote instruments