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

# Funding

# Funding Domain

The Funding domain handles all money movement: deposits, withdrawals, internal transfers, and settlement lines.

---

## Deposits

Deposits bring funds into your sub-account, either via crypto on-chain transactions or bank transfers.

### Crypto Deposit Flow

```
1. Generate deposit address for instrument
2. User sends funds to address
3. Platform detects transaction
4. Wait for confirmations
5. Balance credited
```

### Fiat Deposit Flow

```
1. Get platform bank details with reference code
2. User initiates bank transfer with reference
3. Bank processes transfer (1-3 business days)
4. Platform receives and matches by reference
5. Balance credited
```

### Deposit Status

| Status               | Description                                  |
| -------------------- | -------------------------------------------- |
| `STATUS_NEW`         | Deposit declared, awaiting funds             |
| `STATUS_TO_CONFIRM`  | Transaction detected, awaiting confirmations |
| `STATUS_CONFIRMED`   | Confirmations reached                        |
| `STATUS_IN_PROGRESS` | Being processed                              |
| `STATUS_EXECUTED`    | Balance credited                             |
| `STATUS_FAILED`      | Deposit failed                               |
| `STATUS_CANCELED`    | Cancelled by user                            |

### Deposit Endpoints

| Endpoint                                              | Method | Description                |
| ----------------------------------------------------- | ------ | -------------------------- |
| `/deposits`                                           | POST   | Create deposit declaration |
| `/deposits/by-sub-account/{subAccountId}`             | GET    | List deposits              |
| `/deposits/by-sub-account/{subAccountId}/{id}`        | GET    | Deposit details            |
| `/deposits/by-sub-account/{subAccountId}/{id}/cancel` | POST   | Cancel pending deposit     |

---

## Withdrawals

Withdrawals move funds out of your sub-account to external addresses (crypto) or bank accounts (fiat).

### Crypto Withdrawal Flow

```
1. Whitelist destination address (may require approval period)
2. Initiate withdrawal
3. Confirm with MFA
4. Platform broadcasts transaction
5. Balance deducted
```

### Fiat Withdrawal Flow

```
1. Register bank account (IBAN)
2. Initiate withdrawal
3. Confirm with MFA
4. Platform initiates transfer (1-3 business days)
5. Balance deducted
```

### Address Whitelisting

Security measure requiring addresses to be pre-approved before withdrawals.

| Status                            | Can Withdraw |
| --------------------------------- | ------------ |
| `STATUS_CREATED`                  | No           |
| `STATUS_CONFIRMED`                | No           |
| `STATUS_PENDING_VERIFICATION`     | No           |
| `STATUS_VERIFIED`                 | Yes          |
| `STATUS_WHITELISTED_IN_CUSTODIAN` | Yes          |

**Cooling Period**: New addresses may require 24-48 hours before becoming active.

### Withdrawal Status

| Status                                          | Description                    |
| ----------------------------------------------- | ------------------------------ |
| `STATUS_PENDING_USER_CONFIRMATION`              | Awaiting email code + MFA      |
| `STATUS_ACTIVE`                                 | User confirmed, processing     |
| `STATUS_TO_CONFIRM`                             | Awaiting internal confirmation |
| `STATUS_PENDING_BOOKING_IN_CORE_BANKING_SYSTEM` | Core banking processing        |
| `STATUS_PENDING_EXECUTION`                      | Ready for execution            |
| `STATUS_ACCEPTED`                               | Accepted, being sent           |
| `STATUS_EXECUTED`                               | Successfully completed         |
| `STATUS_FAILED`                                 | Withdrawal failed              |
| `STATUS_CANCELED`                               | Cancelled by user              |
| `STATUS_REFUSED`                                | Refused by compliance          |

### Withdrawal Endpoints

| Endpoint                                          | Method | Description                              |
| ------------------------------------------------- | ------ | ---------------------------------------- |
| `/withdrawals`                                    | POST   | Create withdrawal                        |
| `/withdrawals/init`                               | POST   | Initialize withdrawal (sends email code) |
| `/withdrawals/confirm`                            | POST   | Confirm with email code + MFA            |
| `/withdrawals/unconfirmed/cancel`                 | POST   | Cancel unconfirmed withdrawal            |
| `/withdrawals/by-sub-account/{subAccountId}`      | GET    | List withdrawals                         |
| `/withdrawals/by-sub-account/{subAccountId}/{id}` | GET    | Withdrawal details                       |

### External Address Endpoints

| Endpoint                                | Method | Description                       |
| --------------------------------------- | ------ | --------------------------------- |
| `/investors/addresses/external`         | GET    | List whitelisted addresses        |
| `/investors/addresses/external`         | POST   | Create whitelisted address        |
| `/investors/addresses/external/{id}`    | GET    | Get address details               |
| `/investors/addresses/external/{id}`    | DELETE | Remove whitelisted address        |
| `/investors/addresses/external/init`    | POST   | Resend confirmation code          |
| `/investors/addresses/external/confirm` | POST   | Confirm whitelisting (code + MFA) |
| `/investors/addresses/external/verify`  | POST   | Initiate address verification     |

### Bank Account Endpoints

| Endpoint                   | Method | Description           |
| -------------------------- | ------ | --------------------- |
| `/bank-accounts/mine`      | POST   | Register bank account |
| `/bank-accounts/mine`      | GET    | List bank accounts    |
| `/bank-accounts/mine/{id}` | DELETE | Remove bank account   |

---

## Transfers

Internal transfers move funds between sub-accounts within the same client account.

### Transfer Endpoints

| Endpoint                                   | Method | Description       |
| ------------------------------------------ | ------ | ----------------- |
| `/transfers`                               | POST   | Internal transfer |
| `/transfers/by-sub-account/{subAccountId}` | GET    | Transfer history  |

---

## Settlement Lines

Settlement lines are short-term lending facilities available to entitled PRIME platform clients. They allow you to trade using funds up to a predefined limit, with the obligation to settle the exposure within a defined time window.

### Key Concepts

| Term                | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| **Settlement Line** | A limit assigned to a sub-account, denominated in a quotation currency |
| **Exposure**        | The amount currently being used from the settlement line               |
| **Overdraft**       | The portion of exposure that must be settled within a defined window   |
| **Exposure Call**   | A request to settle a specific amount in a specific instrument         |
| **Settlement**      | The action of covering exposure using available funds                  |

### How It Works

1. **Line Allocation**: A settlement line is configured for your sub-account with a maximum limit in a quotation currency (e.g., USD, CHF)
2. **Trading**: You can place trades even without sufficient balance, up to your settlement line limit
3. **Exposure Tracking**: As trades execute, your exposure increases
4. **Notifications**: PRIME sends daily email reports showing your outstanding positions
5. **Settlement**: You deposit funds and settle the exposure, either manually or automatically

### Settlement Line Endpoints

| Endpoint                                        | Method | Description                           |
| ----------------------------------------------- | ------ | ------------------------------------- |
| `/exposure-lines/by-sub-account/{subAccountId}` | GET    | Get settlement line for a sub-account |
| `/exposure-lines/by-sub-account/{subAccountId}` | PUT    | Update automatic settlement flag      |

### Exposure Call Endpoints

| Endpoint                                               | Method | Description         |
| ------------------------------------------------------ | ------ | ------------------- |
| `/exposure-calls/by-sub-account/{subAccountId}`        | GET    | List exposure calls |
| `/exposure-calls/by-sub-account/{subAccountId}/settle` | POST   | Settle exposure     |

### Data Models

#### ExposureLine

Represents the settlement line configuration for a sub-account.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "clientAccountId": "96e9c58d-f7fe-47b9-a33b-e898d5c01119",
  "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
  "quotationId": "20000000-2000-0000-0000-000000000000",
  "quantity": "100000.00",
  "automaticSettlement": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

| Field                 | Type      | Description                          |
| --------------------- | --------- | ------------------------------------ |
| `id`                  | UUID      | Unique identifier                    |
| `clientAccountId`     | UUID      | Parent client account                |
| `subAccountId`        | UUID      | Sub-account this line belongs to     |
| `quotationId`         | UUID      | Instrument ID for valuation currency |
| `quantity`            | decimal   | Maximum limit                        |
| `automaticSettlement` | boolean   | Auto-settle on deposit               |
| `createdAt`           | timestamp | Creation time                        |
| `updatedAt`           | timestamp | Last update time                     |

#### ExposureCall

Represents an outstanding amount that needs to be settled.

```json
{
  "id": "call-uuid",
  "clientAccountId": "96e9c58d-f7fe-47b9-a33b-e898d5c01119",
  "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
  "instrumentId": "10000000-2000-0000-0000-000000000000",
  "demandQuantity": "2.50000000",
  "coverQuantity": "1.00000000",
  "status": "STATUS_OPENED",
  "createdAt": "2024-01-14T10:00:00Z",
  "updatedAt": "2024-01-15T08:00:00Z"
}
```

| Field             | Type      | Description                        |
| ----------------- | --------- | ---------------------------------- |
| `id`              | UUID      | Unique identifier                  |
| `clientAccountId` | UUID      | Parent client account              |
| `subAccountId`    | UUID      | Sub-account this call belongs to   |
| `instrumentId`    | UUID      | Instrument to settle               |
| `demandQuantity`  | decimal   | Total amount to cover              |
| `coverQuantity`   | decimal   | Amount already covered             |
| `status`          | enum      | `STATUS_OPENED` or `STATUS_CLOSED` |
| `createdAt`       | timestamp | Creation time                      |
| `updatedAt`       | timestamp | Last update time                   |

#### ExposureCall.Status

| Value           | Description        |
| --------------- | ------------------ |
| `STATUS_NONE`   | Unspecified        |
| `STATUS_OPENED` | Pending settlement |
| `STATUS_CLOSED` | Fully settled      |

### WebSocket Topic

Real-time exposure updates are available via WebSocket.

**Topic:** `{subAccountId}@exposures`

**Authentication:** Required

**Message Format:**

```json
{
  "e": "exposure",
  "t": "{subAccountId}@exposures",
  "d": {
    "i": "quotation-instrument-uuid",
    "o": "15000.50",
    "u": "25000.00",
    "l": "100000.00"
  }
}
```

| Field | Description                 |
| ----- | --------------------------- |
| `i`   | Quotation instrument ID     |
| `o`   | Overdraft (must settle)     |
| `u`   | Utilized (total exposure)   |
| `l`   | Limit (settlement line cap) |

### Balance Integration

Exposure information is also reflected in balance records:

| Balance Field       | Description                             |
| ------------------- | --------------------------------------- |
| `exposureOverdraft` | Amount that must be settled             |
| `exposureReserved`  | Amount reserved for pending settlements |

---

## Fees

| Fee Type     | Description                         |
| ------------ | ----------------------------------- |
| Network Fee  | Blockchain transaction fee (crypto) |
| Platform Fee | Service fee (may apply)             |
| Bank Fee     | Wire transfer fee (fiat)            |

Fees are shown before confirmation and deducted from the withdrawal amount.

---

## Related

* [Use Case: Deposits & Withdrawals](/prime/docs/api-usec-06-deposits-withdrawals)
* [Use Case: Settlement Lines](/prime/docs/api-usec-08-settlement-lines)
* [Use Case: Wallet Information](/prime/docs/api-usec-03-wallet-information)
* [Assets Domain](/prime/docs/api-doma-asse-assets) - Balance information
* [WebSocket Topics](/prime/docs/api-webs-topics) - Real-time updates