Settlement Lines

This guide covers settlement lines, a short-term facility that allows entitled clients to trade using funds up to a predefined limit.

Overview

Settlement lines act as short-term lending facilities for PRIME platform clients. If you are entitled to a settlement line, you can trade using funds up to the limit of the settlement line without having the full balance available upfront. PRIME tracks your consumption (exposure) and periodically notifies you via email about the exposure to be covered through deposits and subsequent settlement actions.

Key Concepts

Term	Description
Settlement Line	A limit assigned to a sub-account, denominated in a quotation currency
Exposure	The amount of the settlement line currently being used
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

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

Prerequisites

Authenticated session (JWT or API key)
Sub-account with an active settlement line (configured by platform operator)
CanTrade permission for settlement operations

Step 1: Check Your Settlement Line

Retrieve the settlement line configuration for your sub-account.

Endpoint: GET /api/rest/v1/exposure-lines/by-sub-account/{subAccountId}

Request

curl -X GET "https://api.t-dx.com/api/rest/v1/exposure-lines/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804" \
  -H "Authorization: Bearer <access-token>"

Response (200 OK)

{
  "result": {
    "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"
  }
}

Settlement Line Fields

Field	Type	Description
`id`	UUID	Unique identifier for the settlement line
`clientAccountId`	UUID	Parent client account
`subAccountId`	UUID	Sub-account this line belongs to
`quotationId`	UUID	Instrument ID for the quotation currency (e.g., USD)
`quantity`	decimal	Maximum limit in the quotation currency
`automaticSettlement`	boolean	Whether deposits automatically settle exposure
`createdAt`	timestamp	When the line was created
`updatedAt`	timestamp	Last modification time

Response (404 Not Found)

If the sub-account does not have a settlement line:

{
  "code": 5,
  "message": "account does not have an exposure line",
  "details": [
    {
      "@type": "type.googleapis.com/tgtraded.FailureDetail",
      "failure": "NOT_FOUND",
      "resourceName": "EXPOSURE_LINE"
    }
  ]
}

Step 2: Update Automatic Settlement

Control whether deposits automatically settle your exposure.

Endpoint: PUT /api/rest/v1/exposure-lines/by-sub-account/{subAccountId}

Request

curl -X PUT "https://api.t-dx.com/api/rest/v1/exposure-lines/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "automaticSettlement": false
  }'

Request Fields

Field	Type	Required	Description
`automaticSettlement`	boolean	Yes	Enable/disable automatic settlement on deposit

Response (200 OK)

Returns the updated settlement line:

{
  "result": {
    "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": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}

Step 3: View Exposure Calls

List the pending exposure calls (outstanding amounts to settle) for your sub-account.

Endpoint: GET /api/rest/v1/exposure-calls/by-sub-account/{subAccountId}

Request

curl -X GET "https://api.t-dx.com/api/rest/v1/exposure-calls/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804" \
  -H "Authorization: Bearer <access-token>"

Query Parameters

Parameter	Type	Default	Description
`sort`	string	`created_at-asc`	Sort order: `created_at-asc` or `created_at-desc`
`limit`	integer	20	Results per page (1-500)
`cursor`	string	-	Pagination cursor
`query`	string[]	-	Filter by `instrument_id`

Response (200 OK)

{
  "result": [
    {
      "id": "call-uuid-1",
      "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"
    },
    {
      "id": "call-uuid-2",
      "clientAccountId": "96e9c58d-f7fe-47b9-a33b-e898d5c01119",
      "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
      "instrumentId": "20000000-2000-0000-0000-000000000000",
      "demandQuantity": "5000.00",
      "coverQuantity": "5000.00",
      "status": "STATUS_CLOSED",
      "createdAt": "2024-01-10T10:00:00Z",
      "updatedAt": "2024-01-12T14:30:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  },
  "sortingKeys": [
    {"key": "created_at", "label": "Created At"}
  ],
  "filters": [
    {"key": "instrument_id", "label": "Instrument", "type": "FILTER_TYPE_SELECT"}
  ]
}

Exposure Call Fields

Field	Type	Description
`id`	UUID	Unique identifier for the exposure call
`clientAccountId`	UUID	Parent client account
`subAccountId`	UUID	Sub-account this call belongs to
`instrumentId`	UUID	Instrument to be settled
`demandQuantity`	decimal	Total amount that needs to be covered
`coverQuantity`	decimal	Amount already covered through settlements
`status`	enum	Current status (see below)
`createdAt`	timestamp	When the call was created
`updatedAt`	timestamp	Last modification time

Exposure Call Status Values

Status	Description
`STATUS_OPENED`	Settlement pending - you need to cover this exposure
`STATUS_CLOSED`	Fully settled - no action required

Understanding Exposure Calls

demandQuantity: The total amount you need to deposit in this instrument
coverQuantity: The amount you've already settled
Outstanding amount: demandQuantity - coverQuantity is what you still owe
When coverQuantity equals demandQuantity, the status changes to STATUS_CLOSED

Step 4: Settle Exposure

Manually settle an open exposure by using your available funds.

Endpoint: POST /api/rest/v1/exposure-calls/by-sub-account/{subAccountId}/settle

Request

curl -X POST "https://api.t-dx.com/api/rest/v1/exposure-calls/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804/settle" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instrumentId": "10000000-2000-0000-0000-000000000000",
    "quantity": "1.50000000"
  }'

Request Fields

Field	Type	Required	Description
`instrumentId`	UUID	Yes	Instrument ID of the exposure to settle
`quantity`	decimal	Yes	Amount to settle

Response (200 OK)

Empty response on success. The exposure call will be updated with the new coverQuantity.

Error Responses

Status	Code	Description
400	`INVALID_ARGUMENT`	Invalid instrument ID or quantity
403	`PERMISSION_DENIED`	Not authorized to settle this exposure
404	`NOT_FOUND`	No exposure line for this sub-account
422	`FAILED_PRECONDITION`	Insufficient funds to settle

Real-Time Exposure Updates

Subscribe to exposure updates via WebSocket to monitor your usage in real-time.

Topic: {subAccountId}@exposures

{
  "e": "tdx:subscribe",
  "t": "7376524e-6b6b-4137-9719-7e07a7709804@exposures",
  "a": "<jwt-token>"
}

Exposure Update Message

{
  "e": "exposure",
  "t": "7376524e-6b6b-4137-9719-7e07a7709804@exposures",
  "d": {
    "i": "20000000-2000-0000-0000-000000000000",
    "o": "15000.50",
    "u": "25000.00",
    "l": "100000.00"
  }
}

Message Fields

Field	Description
`i`	Quotation instrument ID
`o`	Overdraft amount (must be settled)
`u`	Utilized amount (total exposure)
`l`	Upper bound (settlement line limit)

Balance Fields

When querying balances, the following fields relate to settlement lines:

Field	Description
`exposureOverdraft`	Amount that must be settled by the account
`exposureReserved`	Amount reserved for exposure after order execution

See Wallet Information for details on balance queries.

Email Notifications

PRIME sends email notifications to help you manage your settlement line:

Daily Report

A daily summary sent at noon (Europe/Zurich timezone) containing:

Limit: Your total settlement line limit
Outstanding: Remaining available limit
Used: Current usage amount and percentage
Pending settlements in favor of PRIME: Assets you owe (deposits needed)
Pending settlements in your favor: Assets PRIME owes you (on external addresses)

Warning Notice

An urgent notification sent when your settlement line is almost fully consumed, warning you to fund your account to avoid trading disruption.

Typical Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Settlement Line Workflow                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Check Settlement Line                                        │
│     GET /exposure-lines/by-sub-account/{id}                     │
│     └─> View limit, quotation currency, auto-settlement          │
│                                                                  │
│  2. Trade (exposure increases)                                   │
│     POST /orders or /otc/orders                                  │
│     └─> Trades execute using the settlement line                 │
│                                                                  │
│  3. Monitor Exposure                                             │
│     - Subscribe to {id}@exposures WebSocket topic                │
│     - Receive daily email reports                                │
│                                                                  │
│  4. View Exposure Calls                                          │
│     GET /exposure-calls/by-sub-account/{id}                     │
│     └─> See what needs to be settled                             │
│                                                                  │
│  5. Settle Exposure                                              │
│     Option A: Enable automatic settlement (deposits auto-settle) │
│     Option B: Manual settlement via POST .../settle              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Error Scenarios

Status	Code	Description
400	`INVALID_ARGUMENT`	Invalid sub-account ID, instrument ID, or quantity
403	`PERMISSION_DENIED`	Not authorized to access this resource
404	`NOT_FOUND`	Sub-account does not have a settlement line
422	`FAILED_PRECONDITION`	Cannot settle - insufficient available funds

Wallet Information - Balance queries including exposure fields
Deposits & Withdrawals - Depositing funds to cover exposure
WebSocket Topics - Real-time exposure updates

Settlement Lines

Overview

Key Concepts

How It Works

Prerequisites

Step 1: Check Your Settlement Line

Request

Response (200 OK)

Settlement Line Fields

Response (404 Not Found)

Step 2: Update Automatic Settlement

Request

Request Fields

Response (200 OK)

Step 3: View Exposure Calls

Request

Query Parameters

Response (200 OK)

Exposure Call Fields

Exposure Call Status Values

Understanding Exposure Calls

Step 4: Settle Exposure

Request

Request Fields

Response (200 OK)

Error Responses

Real-Time Exposure Updates

Subscribe

Exposure Update Message

Message Fields

Balance Fields

Email Notifications

Daily Report

Warning Notice

Typical Workflow

Error Scenarios

Related