> This page is for Taurus PRIME.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# Core Concepts

# 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:

| Venue        | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| **Exchange** | Central order book with limit and market orders                   |
| **OTC**      | RFQs and Orders with external dealers; PRIME acts as intermediary |

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

| Field             | Type    | Description                                                              |
| ----------------- | ------- | ------------------------------------------------------------------------ |
| `id`              | UUID    | Unique identifier                                                        |
| `clientAccountId` | UUID    | Parent Client Account                                                    |
| `status`          | enum    | `ACTIVE`, `INACTIVE`, `DELETED`, `PENDING_MFA`, `PENDING_PASSWORD_RESET` |
| `type`            | enum    | `FRONT_OFFICE` (trader), `BACK_OFFICE` (admin), `SYSTEM`                 |
| `mfaEnabled`      | boolean | Whether MFA is required                                                  |

### Permissions

User permissions are controlled through **Actions** applied to **Domains**. See the [Permission Model](#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

| Field                | Type    | Description                          |
| -------------------- | ------- | ------------------------------------ |
| `id`                 | UUID    | Unique identifier                    |
| `status`             | enum    | `ACTIVE`, `INACTIVE`, `SUSPENDED`    |
| `verificationStatus` | enum    | KYC verification state               |
| `internal`           | boolean | System/internal account flag         |
| `locked`             | boolean | Cannot manage own users/sub-accounts |

### Verification Status

Client Accounts must be verified before trading is enabled:

| Status             | Description                     |
| ------------------ | ------------------------------- |
| `UNVERIFIED`       | Initial state, no KYC submitted |
| `PENDING_APPROVAL` | KYC submitted, awaiting review  |
| `APPROVED`         | KYC approved by compliance      |
| `PENDING_VERIFY`   | Additional verification needed  |
| `VERIFIED`         | Fully verified, trading enabled |
| `REJECTED`         | KYC rejected                    |

### 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

| Field             | Type    | Description                                               |
| ----------------- | ------- | --------------------------------------------------------- |
| `id`              | UUID    | Unique identifier                                         |
| `clientAccountId` | UUID    | Parent Client Account                                     |
| `name`            | string  | Human-readable name (e.g., "Main Trading", "Portfolio A") |
| `venue`           | enum    | `VENUE_MARKETPLACE` (Exchange) or `VENUE_OTC`             |
| `pairs`           | \[]UUID | Allowed pair IDs (empty = all pairs allowed)              |

### 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

| Category       | Types                                                 | Examples                  |
| -------------- | ----------------------------------------------------- | ------------------------- |
| **Fiat**       | `CURRENCY`                                            | CHF, EUR, USD             |
| **Crypto**     | `CRYPTO_CURRENCY`                                     | BTC, ETH, SOL             |
| **Securities** | `STOCK`, `DEBT`, `FUND_SHARES`, `ASSET`               | Tokenized equities, bonds |
| **Bonds**      | `GOVERNMENT_BOND`, `CORPORATE_BOND`, `MUNICIPAL_BOND` | Fixed income              |
| **Other**      | `COMMODITY`, `DERIVATIVE`, `NFT`, `UTILITY_TOKEN`     | Specialized assets        |

### Key Properties

| Field               | Type    | Description                                     |
| ------------------- | ------- | ----------------------------------------------- |
| `id`                | UUID    | Unique identifier (used in API calls)           |
| `symbol`            | string  | Trading symbol (e.g., "BTC", "CHF")             |
| `type`              | enum    | Asset classification                            |
| `decimals`          | int     | Precision for quantities                        |
| `blockchain`        | string  | For crypto: which blockchain (e.g., "ethereum") |
| `contractAddress`   | string  | For tokens: smart contract address              |
| `nativeCurrency`    | boolean | True if blockchain's native asset (ETH, BTC)    |
| `depositEnabled`    | boolean | Can receive deposits                            |
| `withdrawalEnabled` | boolean | Can withdraw                                    |

### 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

| Field                   | Type    | Description                                 |
| ----------------------- | ------- | ------------------------------------------- |
| `id`                    | UUID    | Unique identifier (used in order placement) |
| `symbol`                | string  | Trading symbol (e.g., "BTC/CHF")            |
| `baseId`                | UUID    | Base instrument ID                          |
| `quoteId`               | UUID    | Quote instrument ID                         |
| `status`                | enum    | `OPEN`, `SUSPENDED`, `CLOSED`               |
| `tradable`              | boolean | Available on Exchange                       |
| `otcTradable`           | boolean | Available for OTC                           |
| `minOrderQuantity`      | decimal | Minimum order size                          |
| `maxOrderQuantity`      | decimal | Maximum order size                          |
| `priceDecimalPoints`    | int     | Price precision                             |
| `priceTicks`            | decimal | Minimum price increment                     |
| `quantityDecimalPoints` | int     | Quantity precision                          |
| `quantityTicks`         | decimal | Minimum quantity increment                  |

### 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:

| Operation                | Required IDs                   | How to Obtain                                             |
| ------------------------ | ------------------------------ | --------------------------------------------------------- |
| List balances            | `subAccountId`                 | `GET /sub-accounts` → use `id` field                      |
| Place order              | `subAccountId`, `pairId`       | `GET /sub-accounts`, `GET /pairs` → use `id` fields       |
| Generate deposit address | `subAccountId`, `instrumentId` | `GET /sub-accounts`, `GET /instruments` → use `id` fields |
| Initiate withdrawal      | `subAccountId`, `instrumentId` | `GET /sub-accounts`, `GET /instruments` → use `id` fields |

### 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:

| Action     | Description                   | Requires MFA |
| ---------- | ----------------------------- | ------------ |
| `read`     | View data                     | No           |
| `write`    | Modify data                   | Yes          |
| `execute`  | Execute operations            | No           |
| `trade`    | Place and manage orders       | Yes          |
| `replace`  | Replace existing orders       | Yes          |
| `deposit`  | Initiate deposits             | Yes          |
| `withdraw` | Initiate withdrawals          | Yes          |
| `convert`  | Convert between instruments   | Yes          |
| `manage`   | Manage users and sub-accounts | Yes          |

### Domains

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

| Domain               | Scope          | Description                                        |
| -------------------- | -------------- | -------------------------------------------------- |
| `private/general`    | Client Account | General client account operations                  |
| `private/subaccount` | Sub-Account    | Sub-account specific operations (balances, orders) |
| `private/settings`   | Client Account | Account settings and preferences                   |
| `private/pair`       | Sub-Account    | Trading pair access within a sub-account           |
| `private/instrument` | Client Account | Instrument-level operations                        |
| `private/investor`   | Client Account | Investor profile operations                        |
| `public`             | Global         | Public data (prices, pairs, instruments)           |

### 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