Settlement Analysis

Retrieve settlement data including trade volumes, settlement values, and settlement percentages for equities.

GET/3.0/settlements

Description

This endpoint returns settlement analysis data for equity trades. The data includes trade volumes, settlement volumes, and the corresponding percentages showing the proportion of trades that were settled. Settlement data can be queried by specific date, date range, or aggregated for the entire market.

Request

Authentication

• Type: Bearer Token
• Required: Yes

Parameters

Name	Type	Required	Description	Example
date	string	No	Specific date filter (format: YYYY-MM-DD). When provided, returns settlement data for that date.	2025-05-08
date_range	string	No	Date range filter in format YYYY-MM-DD:YYYY-MM-DD. Use for querying settlement data across a date range.	2025-05-01:2025-05-08

Response

Success Response (200) - By Date

{
  "status": "ok",
  "message": "",
  "data": [
    {
      "date": "2025-05-08",
      "symbol": "UBL",
      "sector_code": "COMMERCIAL_BANKS",
      "value": 2750000000.00,
      "volume": 10000000,
      "sett_value": 2725000000.00,
      "sett_volume": 9900000,
      "sett_value_pct": 99.09,
      "sett_volume_pct": 99.00
    },
    {
      "date": "2025-05-08",
      "symbol": "MCB",
      "sector_code": "COMMERCIAL_BANKS",
      "value": 2600000000.00,
      "volume": 10000000,
      "sett_value": 2574000000.00,
      "sett_volume": 9900000,
      "sett_value_pct": 99.00,
      "sett_volume_pct": 99.00
    },
    {
      "date": "2025-05-08",
      "symbol": "HUBC",
      "sector_code": "POWER_GENERATION",
      "value": 652500000.00,
      "volume": 10000000,
      "sett_value": 647475000.00,
      "sett_volume": 9930000,
      "sett_value_pct": 99.23,
      "sett_volume_pct": 99.30
    }
  ],
}

Response Fields

Field	Type	Description
date	string (YYYY-MM-DD)	Date of settlement record
symbol	string	Stock symbol of the security
sector_code	string	Sector classification code
value	float	Total trade value in PKR
volume	float	Total trade volume in shares
sett_value	float	Settled trade value in PKR
sett_volume	float	Settled trade volume in shares
sett_value_pct	float	Percentage of value that was settled
sett_volume_pct	float	Percentage of volume that was settled

Error Responses

For detailed Common Error responses, see the Error Handling.

Invalid Date Format

{
    "status": "error",
    "message": "invalid_date"
}

Invalid Period

{
    "status": "error",
    "message": "invalid_period"
}

Examples

Get Settlement Data for Specific Date

curl -X GET "https://csapis.com/3.0/settlements?date=2025-05-08" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Cases

• Settlement Analysis: Track settlement rates and effectiveness
• Market Quality: Monitor market settlement percentages and performance
• Risk Management: Analyze settlement volumes and values by security
• Liquidity Analysis: Assess market liquidity through settlement metrics
• Regulatory Reporting: Generate settlement reports for compliance