Market Data > Stocks List

Retrieve Stocks List

Returns a paginated list of all PSX-listed equities with real-time price, volume, sector, market capitalisation, dividend yield, and 52-week range. Data is merged from Sarmaaya (primary) and the PSX live feed (fallback), so you always get the most complete picture available. Use this endpoint as your starting point before requesting detailed quotes or candle data for specific symbols.

GEThttps://api.psxmarket.io/api/v1/market/stocks

Requires API key — Free plan and above.

Query Parameters

Parameter	Type	Description	Required
search	string	Filter by ticker symbol or company name. Partial matches supported.	Optional
page	integer	Page number for pagination. Starts at 1.	Optional
limit	integer	Number of stocks per page. Default is 20. Maximum is 100.	Optional
sector	string	Filter by PSX sector code.	Optional
listedIn	string	Filter by index. KSE100, KSE30, ALLSHR, KMI30.	Optional

Request Headers

Header	Required	Description
X-API-Key	Required	Your API key. Pass in every request header.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/stocks?limit=5&sector=BANK" -H "X-API-Key: your_api_key_here"

Response

Fields

data array

Array of stock objects

meta object

Pagination metadata

Example Response

{"data":[{"symbol":"ENGRO","name":"Engro Corporation Limited","close":285.40,"changePercent":1.13,"volume":1240500,"source":"sarmaaya+psx"}],"meta":{"total":548,"page":1,"limit":20}}

Status Codes

Status	Meaning	When it occurs
200	OK	Request processed successfully.
400	Bad Request	Invalid parameter value.
401	Unauthorized	Missing or invalid X-API-Key header.
429	Too Many Requests	Per-minute or monthly rate limit exceeded.
500	Internal Server Error	Unexpected server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Stock Detail

Retrieve Stock Detail

Returns comprehensive data for a single PSX-listed stock identified by its ticker symbol.

GEThttps://api.psxmarket.io/api/v1/market/stocks/:symbol

Requires API key — Free plan and above.

Path Parameters

Parameter	Type	Description
symbol	string	PSX ticker symbol in uppercase. Example: ENGRO, HBL, LUCK, PSO.

Request Headers

Header	Required	Description
X-API-Key	Required	Your API key. Required on every request.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/stocks/ENGRO" -H "X-API-Key: your_api_key_here"

Response

Fields

symbol string

PSX ticker symbol.

close float

Last closing price in PKR.

Example Response

{"symbol":"ENGRO","close":285.40,"source":"sarmaaya"}

Status Codes

Status	Meaning	When it occurs
200	OK	Stock data returned successfully.
401	Unauthorized	Missing or invalid API key.
404	Not Found	The symbol does not exist on PSX.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Unexpected error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Rankings

Market Rankings

Returns a sorted list of stocks for the requested ranking category.

GEThttps://api.psxmarket.io/api/v1/market/rankings/:type

Requires API key — Free plan and above.

Path Parameters

Parameter	Type	Description
type	string	gainers, losers, active, dividend, kse100, etc.

Query Parameters

Parameter	Type	Description	Required
limit	integer	Maximum results to return. Default 20.	Optional

Request Headers

Header	Required	Description
X-API-Key	Required	Your API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/rankings/gainers?limit=10" -H "X-API-Key: your_api_key_here"

Response

Fields

data array

Sorted array of stock objects.

Example Response

{"category":"gainers","data":[{"symbol":"LUCK","changePercent":4.81}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Rankings returned successfully.
400	Bad Request	Invalid ranking type.
401	Unauthorized	Missing or invalid API key.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Intraday Candles

Intraday OHLCV Candles

Returns aggregated OHLCV candle data for a single stock. Available on Pro plan and above.

GEThttps://api.psxmarket.io/api/v1/market/candles/intraday/:symbol

Pro plan required. This endpoint is not available on the Free plan.

Path Parameters

Parameter	Type	Description
symbol	string	PSX ticker symbol.

Query Parameters

Parameter	Type	Description	Required
interval	string	1m,5m,15m,30m,1h.	Optional

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/candles/intraday/ENGRO?interval=5m" -H "X-API-Key: your_api_key_here"

Response

Fields

candles array

Array of OHLCV candle objects.

Example Response

{"symbol":"ENGRO","interval":"5m","candles":[{"t":1714370400,"o":282.00,"h":285.50,"l":281.00,"c":285.40,"v":62000}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Candle data returned successfully.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Requires Pro plan.
404	Not Found	Symbol not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Daily Candles

Daily EOD Candles

Returns end-of-day OHLCV candle data for historical charting.

GEThttps://api.psxmarket.io/api/v1/market/candles/daily/:symbol

Pro plan required. This endpoint is not available on the Free plan.

Path Parameters

Parameter	Type	Description
symbol	string	PSX ticker symbol.

Query Parameters

Parameter	Type	Description	Required
days	integer	Past trading days, default 365.	Optional

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/candles/daily/ENGRO?days=30" -H "X-API-Key: your_api_key_here"

Response

Fields

candles array

Daily EOD candles.

Example Response

{"symbol":"ENGRO","candles":[{"t":1714176000,"o":282.20,"h":286.00,"l":281.00,"c":285.40,"v":1240500}]}

Status Codes

Status	Meaning	When it occurs
200	OK	EOD candle data returned.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Requires Pro plan.
404	Not Found	Symbol not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Quotes & Order Book

Live Quotes & Order Book

Returns real-time ask/bid and circuit limits for one or more stocks.

GEThttps://api.psxmarket.io/api/v1/market/quotes

Pro plan required. This endpoint is not available on the Free plan.

Query Parameters

Parameter	Type	Description	Required
symbols	string	Comma-separated symbols.	Required
batchSize	integer	Batch size, default 5.	Optional
batchIndex	integer	Zero-indexed batch.	Optional

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/quotes?symbols=ENGRO,HBL,LUCK" -H "X-API-Key: your_api_key_here"

Response

Fields

quotes array

Array of live quote objects.

Example Response

{"quotes":[{"symbol":"ENGRO","askPrice":285.75,"bidPrice":285.40,"circuitBreakerUpper":303.37,"circuitBreakerLower":261.03}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Quotes returned successfully.
400	Bad Request	symbols missing or invalid.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Requires Pro plan.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Uptick / Downtick

Last Trade Direction

Returns last-trade direction for one or more symbols.

GEThttps://api.psxmarket.io/api/v1/market/uptick

Pro plan required. This endpoint is not available on the Free plan.

Query Parameters

Parameter	Type	Description	Required
symbols	string	Comma-separated symbols.	Required

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/uptick?symbols=ENGRO,HBL" -H "X-API-Key: your_api_key_here"

Response

Fields

ticks array

Array of tick direction objects.

Example Response

{"ticks":[{"symbol":"ENGRO","tick":"uptick","lastPrice":285.40}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Tick data returned.
401	Unauthorized	Invalid API key.
403	Forbidden	Requires Pro plan.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Market Data > Circuit Breaker

Circuit Breaker Limits

Returns upper/lower circuit breaker limits for symbols.

GEThttps://api.psxmarket.io/api/v1/market/circuit-breaker

Requires API key — Free plan and above.

Query Parameters

Parameter	Type	Description	Required
symbols	string	Comma-separated symbols.	Required

Request Headers

Header	Required	Description
X-API-Key	Required	Your API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/market/circuit-breaker?symbols=ENGRO,HBL" -H "X-API-Key: your_api_key_here"

Response

Fields

limits array

Circuit breaker values per symbol.

Example Response

{"limits":[{"symbol":"ENGRO","ldcp":282.20,"upper":303.37,"lower":261.03}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Limits returned.
401	Unauthorized	Invalid API key.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Reference Data > Company Profile

Company Profile

Returns static company information and key personnel from PSX pages.

GEThttps://api.psxmarket.io/api/v1/reference/company-profile/:symbol

Pro plan required. This endpoint is not available on the Free plan.

Path Parameters

Parameter	Type	Description
symbol	string	PSX ticker symbol in uppercase.

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/reference/company-profile/ENGRO" -H "X-API-Key: your_api_key_here"

Response

Fields

symbol string

Ticker symbol.

keyPeople array

Key management personnel.

Example Response

{"symbol":"ENGRO","sector":"Fertilizer","website":"https://www.engro.com","keyPeople":[{"name":"Ghias Khan","title":"President & CEO"}]}

Status Codes

Status	Meaning	When it occurs
200	OK	Profile returned.
401	Unauthorized	Invalid API key.
403	Forbidden	Requires Pro plan.
404	Not Found	Symbol not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.

Reference Data > Financial Statements

Financial Statements

Returns annual and quarterly statement data and key ratios.

GEThttps://api.psxmarket.io/api/v1/reference/financials/:symbol

Pro plan required. This endpoint is not available on the Free plan.

Path Parameters

Parameter	Type	Description
symbol	string	PSX ticker symbol in uppercase.

Request Headers

Header	Required	Description
X-API-Key	Required	Your Pro plan API key.

Code Examples

curl -X GET "https://api.psxmarket.io/api/v1/reference/financials/ENGRO" -H "X-API-Key: your_api_key_here"

Response

Fields

annual array

Annual financial rows.

ratios object

Key ratios.

Example Response

{"symbol":"ENGRO","annual":[{"year":2023,"revenue":425000000000,"netIncome":38000000000}],"ratios":{"pe":12.4,"pb":1.8}}

Status Codes

Status	Meaning	When it occurs
200	OK	Financials returned.
401	Unauthorized	Invalid API key.
403	Forbidden	Requires Pro plan.
404	Not Found	Symbol not found.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Server error.

Error Response Format

{ "error": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded 10 requests per minute on the Free plan.", "retryAfterSeconds": 47, "upgradeUrl": "https://api.psxmarket.io/pricing" }

All errors follow this shape. The error field is machine-readable. The message field is human-readable.